IOCTL_REDIR_QUERY_PATH_EX IOCTL (ntifs.h)

Статья
08/07/2023

Начиная с 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 , на которую указывает выходной буфер, в байтах.

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

Недоступно

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

Недоступно

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

Элемент Status имеет значение 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_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. Большинство поставщиков обычно запрашивают часть \\servername\sharename пути в формате \\servername\путьк имени_общей папки\. Например, если поставщик запросил \\server\public с помощью пути \\server\public\dir1\dir2, все операции на основе имен для префикса \\server\public (\\server\public\file1, например) будут перенаправлены к поставщику автоматически без разрешения префикса, так как префикс уже находится в кэше префиксов. Однако путь с префиксом \\server\маркетинговой\презентации будет проходить через разрешение префикса.

Если перенаправитель сети запрашивает имя сервера (\\server, например), все запросы общих папок на этом сервере будут отправляться этому сетевому перенаправлению. Такое поведение допустимо только в том случае, если другой сетевой перенаправитель не может получить доступ к другой общей папке на том же сервере. Например, перенаправитель сети, который утверждает \\serverUNC-пути, будет препятствовать доступу других перенаправителей сети к другим общим папкам на этом сервере (например, доступ WebDAV к \\server\ web).

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