IOCTL_REDIR_QUERY_PATH_EX IOCTL (ntifs.h)

Статья
12/21/2024

Начиная с Windows Vista, несколько поставщиков UNC (MUP) отправляет код управления IOCTL_REDIR_QUERY_PATH_EX в сетевые перенаправления, чтобы определить, какой поставщик может обрабатывать определенный UNC-путь в операции на основе имен, как правило, запрос IRP_MJ_CREATE. Этот запрос называется разрешением префикса.

MUP — это компонент режима ядра, отвечающий за передачу всех удаленных файловых систем доступа с помощью имени UNC к сетевому перенаправлению (поставщику UNC), который может обрабатывать запросы удаленной файловой системы. MUP используется, когда UNC-путь используется, как показано в следующем примере, который можно выполнить из командной строки:

notepad \\server\public\readme.txt

MUP не участвует во время операции, которая создает сопоставленную букву диска (например, команду NET USE). Эта операция обрабатывается несколькими маршрутизаторами поставщиков (MPR) и библиотекой DLL поставщика WNet в пользовательском режиме для сетевого перенаправления. Однако библиотека DLL поставщика WNet в пользовательском режиме может напрямую взаимодействовать с драйвером сетевого перенаправления в режиме ядра во время этой операции.

Для сетевых перенаправлений, соответствующих модели перенаправления Windows Vista, MUP участвует даже при использовании сопоставленного сетевого диска. Операции с файлами, выполняемые на сопоставленном диске, проходят через MUP с сетевым перенаправлением. Обратите внимание, что в этом случае MUP просто передает операцию сетевому перенаправлению, который участвует.

Код управления IOCTL_REDIR_QUERY_PATH_EX отправляется в сетевые перенаправления, зарегистрированные в MUP в качестве поставщиков универсального соглашения об именовании (UNC), вызывая FsRtlRegisterUncProviderEx. В MUP может быть несколько поставщиков UNC.

Операция разрешения префикса служит двумя целями:

Операция на основе имен, которая привела к разрешению префикса, направляется поставщику, который утверждает префикс. При успешном выполнении MUP гарантирует, что последующие операции на основе дескриптора (IRP_MJ_READ и IRP_MJ_WRITE, например) проходят через MUP к тому же поставщику. Обратите внимание, что это поведение отличается для сетевых перенаправлений, которые не соответствуют модели перенаправления Windows Vista, которая будет отправлена IOCTL_REDIR_QUERY_PATH для разрешения префикса. Для сетевых перенаправлений, которые не соответствуют модели перенаправления Windows Vista, MUP полностью обходятся для последующих операций на основе дескриптора.
Поставщик и префикс, которые он утверждал, вводятся в кэш префикса, поддерживаемый MUP. Для последующих операций на основе имен MUP использует этот кэш префикса, чтобы определить, утверждал ли поставщик префикс до попытки MUP выполнить разрешение префикса. Каждая запись в этом кэше префикса подвергается времени ожидания (называемому TTL) после добавления в кэш. Запись удаляется после истечения срока действия этого времени ожидания, в которой MUP снова выполнит разрешение префикса для этой префикса при последующей операции на основе имен.

Основной код

IOCTL_REDIR_QUERY_PATH_EX

Входной буфер

IrpSp->Parameters.DeviceIoControl.Type3InputBuffer имеет QUERY_PATH_REQUEST_EX структуру данных, содержащую запрос.

Длина входного буфера

Размер структуры QUERY_PATH_REQUEST_EX, на которую указывает входной буфер, в байтах.

Выходной буфер

IRP->UserBuffer имеет QUERY_PATH_RESPONSE структуру данных, содержащую ответ.

Длина выходного буфера

Размер структуры QUERY_PATH_RESPONSE, на которую указывает выходной буфер, в байтах.

Буфер входных и выходных данных

n/a

Длина буфера ввода и вывода

n/a

Блок состояния

Элемент состояния имеет значение STATUS_SUCCESS при успешном выполнении, если распознается имя префикса \\server\share или соответствующее значение NTSTATUS, например одно из следующих:

Код состояния	Значение
STATUS_BAD_NETWORK_NAME	Указанное имя общей папки не удается найти на удаленном сервере. Имя компьютера (\\server, например) допустимо, но указанное имя общей папки не удается найти на удаленном сервере.
STATUS_BAD_NETWORK_PATH	Не удается найти сетевой путь. Имя компьютера (\\server, например) недопустимо или сетевой перенаправление не может разрешать имя компьютера (используя все доступные механизмы разрешения имен).
STATUS_INSUFFICIENT_RESOURCES	Недостаточно ресурсов для выделения памяти для буферов.
STATUS_INVALID_DEVICE_REQUEST	Запрос IOCTL_REDIR_QUERY_PATH_EX должен поступать только из MUP, а элемент RequestorMode структуры IRP всегда должен быть KernelMode. Этот код ошибки возвращается, если режим запрашивающего потока не был KernelMode.
STATUS_INVALID_PARAMETER	Элемент PathNameLength в структуре QUERY_PATH_REQUEST превышает максимальную допустимую длину UNICODE_STRING_MAX_BYTES для строки Юникода.
STATUS_LOGON_FAILURE или STATUS_ACCESS_DENIED	Если сбой операции разрешения префикса из-за недопустимых или неверных учетных данных, поставщик должен вернуть точный код ошибки, возвращенный удаленным сервером; Эти коды ошибок не должны быть преобразованы в STATUS_BAD_NETWORK_NAME или STATUS_BAD_NETWORK_PATH. Коды ошибок, такие как STATUS_LOGON_FAILURE и STATUS_ACCESS_DENIED служат механизмом обратной связи для пользователя и указывают требование использовать соответствующие учетные данные. Эти коды ошибок также используются в некоторых случаях для автоматического запроса пользователя на учетные данные. Без этих кодов ошибок пользователь может предположить, что компьютер недоступен.

Если сетевой перенаправление не удается устранить префикс, он должен вернуть код NTSTATUS, который тесно соответствует предполагаемой семантике из приведенного выше списка рекомендуемых кодов NTSTATUS. Сетевой перенаправление не должен возвращать фактическую обнаруженную ошибку (например, STATUS_CONNECTION_REFUSED) непосредственно в MUP, если код NTSTATUS не находится в приведенном выше списке.

Замечания

Сетевые перенаправления должны учитывать только отправителей в режиме ядра этого IOCTL, убедившись, что Irp->RequestorModeKernelMode.

Обратите внимание, что IOCTL_REDIR_QUERY_PATH_EX является METHOD_NEITHER IOCTL. Это означает, что входные и выходные буферы могут не находиться в одном адресе. Распространенная ошибка поставщиков UNC заключается в том, чтобы предположить, что входной буфер и выходной буфер совпадают и используют указатель входного буфера для предоставления ответа.

Когда поставщик UNC получает запрос IOCTL_REDIR_QUERY_PATH_EX, он должен определить, может ли он обрабатывать UNC-путь, указанный в элементе PathName структуры QUERY_PATH_REQUEST_EX. Если это так, поставщик UNC должен обновить LengthAccepted член структуры QUERY_PATH_RESPONSE длиной в байтах утверждения префикса и завершить IRP с STATUS_SUCCESS. Если поставщик не может обработать указанный UNC-путь, он должен завершить запрос IOCTL_REDIR_QUERY_PATH_EX соответствующим кодом ошибки NTSTATUS и не должен обновлять LengthAccepted член структуры QUERY_PATH_RESPONSE. Поставщики не должны изменять другие члены или PathName в любом условии.

Длина префикса, заявленного поставщиком, зависит от отдельного поставщика UNC. Большинство поставщиков обычно утверждают имя сервера \\имя сервера\имя общего ресурса часть пути формы \\имя сервера\имени общего ресурса\пути. Например, Если поставщик утверждал \\серверобщедоступный с помощью пути \\сервераобщедоступногоdir1dir2, все операции на основе имен для префикса \\Серверобщедоступной (\\сервера,общедоступногоfile1, например), будет перенаправлен в этот поставщик автоматически без разрешения префикса, так как префикс уже находится в кэш префикса. Однако путь к префиксу \\серверамаркетинговойпрезентации будет проходить через разрешение префикса.

Если сетевой перенаправление утверждает имя сервера (\\сервера, например), все запросы на общие ресурсы на этом сервере будут отправляться в этот сетевой перенаправитель. Это поведение допускается только в том случае, если нет возможности доступа к другому ресурсу на том же сервере, к которым обращается другой сетевой перенаправление. Например, сетевой перенаправитель, который утверждает \\сервера пути UNC, будет препятствовать доступу других сетевых перенаправлений к другим общим ресурсам на этом сервере (доступ к \\сервера\веб-, например).

Дополнительные сведения см. в следующих разделах руководства по проектированию: