IRP_MJ_DIRECTORY_CONTROL (FS and filter drivers)

  • Artigo

When Sent

The I/O Manager, other operating system components, and other kernel-mode drivers send IRP_MJ_DIRECTORY_CONTROL requests. It can be sent, for example, when a user-mode application has called a Win32 function such as ReadDirectoryChangesW or FindNextVolumeMountPoint or when a kernel-mode component has called ZwQueryDirectoryFile or ZwQueryDirectoryFileEx.

Operation: File System Drivers

The file system driver should check the minor function code to determine which directory control operation is requested. The following are the valid minor function codes:

Code Description
IRP_MN_QUERY_DIRECTORY Indicates a directory query request. The types of information that can be queried are file-system-dependent, but generally include the following values: FileBothDirectoryInformation, FileDirectoryInformation, FileFullDirectoryInformation, FileIdBothDirectoryInformation, FileIdFullDirectoryInformation, FileNamesInformation, FileObjectIdInformation, FileReparsePointInformation.
IRP_MN_NOTIFY_CHANGE_DIRECTORY Indicates a request for notification of changes to the directory. Usually, instead of satisfying this request immediately, the file system driver holds the IRP in a private queue. When a change occurs to the directory, the file system driver performs the notification, and dequeues and completes the IRP. The file system driver returns the information in a FILE_NOTIFY_INFORMATION structure.
IRP_MN_NOTIFY_CHANGE_DIRECTORY_EX Indicates a request for notification of changes to the directory. Usually, instead of satisfying this request immediately, the file system driver holds the IRP in a private queue. When a change occurs to the directory, the file system driver performs the notification, and dequeues and completes the IRP. The file system driver returns information based on the specified IrpSp->Parameters.NotifyDirectoryEx.DirectoryNotifyInformationClass.

Note

The FileQuotaInformation information class is obsolete. IRP_MJ_QUERY_QUOTA should be used instead.

The file system driver should complete the IRP after it performs the requested operation.

Operation: Legacy File System Filter Drivers

The filter driver must pass this IRP down to the next-lower driver on the stack.

Parameters

A file system or filter driver calls IoGetCurrentIrpStackLocation for the given IRP to get a pointer to its own stack location in the IRP. In the following parameters, Irp points to the IRP and IrpSp points to the IO_STACK_LOCATION. The driver can use the information that is set in the following members of the IRP and the IRP stack location to process a directory control request.

  • DeviceObject is a pointer to the target device object.

  • Irp->AssociatedIrp.SystemBuffer points to an IO_STATUS_BLOCK structure that receives the final completion status and information about the requested operation.

  • Irp->UserBuffer points to a caller-supplied output buffer that receives the requested information about the contents of the directory.

  • IrpSp->FileObject points to the file object that is associated with DeviceObject.

    The IrpSp->FileObject parameter contains a pointer to the RelatedFileObject field, which is also a FILE_OBJECT structure. The RelatedFileObject field of the FILE_OBJECT structure isn't valid during the processing of IRP_MJ_DIRECTORY_CONTROL and shouldn't be used.

  • IrpSp->Flags can be set to one or more of the following values for IRP_MN_QUERY_DIRECTORY.

Flag Meaning
SL_INDEX_SPECIFIED Begin the scan at the entry in the directory whose index is given by IrpSp->Parameters.QueryDirectory.FileIndex.
SL_RESTART_SCAN Begin the scan at the first entry in the directory. If this flag isn't set, resume the scan from a previous IRP_MN_QUERY_DIRECTORY request.
SL_RETURN_SINGLE_ENTRY Return only the first entry that is found.
SL_RETURN_ON_DISK_ENTRIES_ONLY Instructs any filters that perform directory virtualization or just-in-time expansion to simply pass the request through to the file system and return entries that are currently on disk.

The following flag can be set for IRP_MN_NOTIFY_CHANGE_DIRECTORY:

Flag Meaning
SL_WATCH_TREE Set to TRUE if all subdirectories of this directory should also be watched. Set to FALSE if only the directory itself is to be watched.

  • IrpSp->MajorFunction is set to IRP_MJ_DIRECTORY_CONTROL.

  • IrpSp->MinorFunction can be set to one of the following values.

    • IRP_MN_QUERY_DIRECTORY
    • IRP_MN_NOTIFY_CHANGE_DIRECTORY
    • IRP_MN_NOTIFY_CHANGE_DIRECTORY_EX

  • IrpSp->Parameters.QueryDirectory.FileIndex is the index of the file at which to begin the directory scan. This value is ignored if the SL_INDEX_SPECIFIED flag isn't set. This parameter can't be specified in any Win32 function or kernel-mode support routine. Currently it's used only by the NT virtual DOS machine (NTVDM), which exists only on 32-bit NT-based platforms. The file index is undefined for file systems, such as NTFS, in which the position of a file within the parent directory isn't fixed and can be changed at any time to maintain sort order.

  • IrpSp->Parameters.QueryDirectory.FileInformationClass is set to one of the following values.

    Value Meaning
    FileBothDirectoryInformation Return a FILE_BOTH_DIR_INFORMATION structure for each file.
    FileDirectoryInformation Return a FILE_DIRECTORY_INFORMATION structure for each file.
    FileFullDirectoryInformation Return a FILE_FULL_DIR_INFORMATION" structure for each file.
    FileIdBothDirectoryInformation Return a FILE_ID_BOTH_DIR_INFORMATION structure for each file.
    FileIdFullDirectoryInformation Return a FILE_ID_FULL_DIR_INFORMATION structure for each file.
    FileNamesInformation Return a FILE_NAMES_INFORMATION structure for each file.
    FileObjectIdInformation Return a FILE_OBJECTID_INFORMATION structure for each file.
    FileQuotaInformation Obsolete. Use IRP_MJ_QUERY_QUOTA instead.
    FileReparsePointInformation Return a single FILE_REPARSE_POINT_INFORMATION structure for the directory.

  • IrpSp->Parameters.QueryDirectory.FileName is the optional name of a file within the specified directory.

  • IrpSp->Parameters.QueryDirectory.Length is the length in bytes of the buffer pointed to by Irp->UserBuffer.

  • IrpSp->Parameters.NotifyDirectory.Length is the length in bytes of the buffer pointed to by Irp->UserBuffer.

  • IrpSp->Parameters.NotifyDirectory.CompletionFilter: For more information, see the description of the CompletionFilter parameter to FsRtlNotifyFullChangeDirectory.

  • IrpSp->Parameters.NotifyDirectoryEx.Length is the length in bytes of the buffer pointed to by Irp->UserBuffer.

  • IrpSp->Parameters.NotifyDirectoryEx.CompletionFilter: For more information, see the description of the CompletionFilter parameter to FsRtlNotifyFullChangeDirectory.

  • IrpSp->Parameters.NotifyDirectoryEx.DirectoryNotifyInformationClass is one of the following values.

    Value Meaning
    DirectoryNotifyInformation Return a FILE_NOTIFY_INFORMATION structure for directory change.
    DirectoryNotifyExtendedInformation Return a FILE_NOTIFY_EXTENDED_INFORMATION structure for each directory change.
    DirectoryNotifyFullInformation Return a FILE_NOTIFY_FULL_INFORMATION structure for each directory change.

See also

FILE_BOTH_DIR_INFORMATION

FILE_DIRECTORY_INFORMATION

FILE_FULL_DIR_INFORMATION

FILE_ID_BOTH_DIR_INFORMATION

FILE_ID_FULL_DIR_INFORMATION

FILE_NAMES_INFORMATION

FILE_OBJECTID_INFORMATION

FILE_REPARSE_POINT_INFORMATION

FsRtlNotifyFullChangeDirectory

FILE_NOTIFY_INFORMATION

FILE_NOTIFY_EXTENDED_INFORMATION

FILE_NOTIFY_FULL_INFORMATION

IO_STACK_LOCATION

IO_STATUS_BLOCK

IoGetCurrentIrpStackLocation

IRP

IRP_MJ_QUERY_QUOTA

ZwQueryDirectoryFile

ZwQueryDirectoryFileEx