IOCTL_REDIR_QUERY_PATH_EX IOCTL (ntifs.h)

项目
02/26/2024

从 Windows Vista 开始，多个 UNC 提供程序 (MUP) 将 IOCTL_REDIR_QUERY_PATH_EX 控制代码发送到网络重定向程序，以确定哪个提供程序可以在基于名称的操作（通常是IRP_MJ_CREATE请求）中处理特定的 UNC 路径。此请求称为“前缀解析”。

MUP 是一个内核模式组件，负责使用 UNC 名称将所有远程文件系统访问定向到网络重定向程序， (能够处理远程文件系统请求的 UNC 提供程序) 。使用 UNC 路径时涉及 MUP，如以下示例所示，该路径可从命令行执行：

notepad \\server\public\readme.txt

在 (“NET USE”命令（例如) ）创建映射驱动器号的操作期间，不涉及 MUP。此操作由多个提供程序路由器 (MPR) 和网络重定向程序的用户模式 WNet 提供程序 DLL 进行处理。但是，用户模式 WNet 提供程序 DLL 可能会在此操作期间直接与内核模式网络重定向程序驱动程序通信。

对于符合 Windows Vista 重定向程序模型的网络重定向程序，即使使用映射的网络驱动器，也会涉及 MUP。在映射驱动器上执行的文件操作通过 MUP 转到网络重定向程序。请注意，在这种情况下，MUP 只是将操作传递给所涉及的网络重定向程序。

IOCTL_REDIR_QUERY_PATH_EX控制代码通过调用 FsRtlRegisterUncProviderEx，将发送到已注册 MUP 为通用命名约定的网络重定向程序， (UNC) 提供程序。可以使用 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

状态块

如果识别 \\server\share 前缀名称，则状态成员设置为成功时STATUS_SUCCESS，或设置为相应的 NTSTATUS 值，例如以下值之一：

状态代码	含义
STATUS_BAD_NETWORK_NAME	在远程服务器上找不到指定的共享名称。计算机名称 (\\server，例如，) 有效，但在远程服务器上找不到指定的共享名称。
STATUS_BAD_NETWORK_PATH	无法找到网络路径。计算机名称 (\\server，例如，) 无效，或者网络重定向程序无法使用) 可用的任何名称解析机制 (解析计算机名称。
STATUS_INSUFFICIENT_RESOURCES	没有足够的资源可用于为缓冲区分配内存。
STATUS_INVALID_DEVICE_REQUEST	IOCTL_REDIR_QUERY_PATH_EX请求应仅来自 MUP，并且 IRP 结构的 RequestorMode 成员应始终为 KernelMode。如果调用线程的请求者模式不是 KernelMode，则返回此错误代码。
STATUS_INVALID_PARAMETER	QUERY_PATH_REQUEST 结构中的 PathNameLength 成员超出了 Unicode 字符串允许的最大长度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，例如，如果 NTSTATUS 代码不来自上述列表，则直接) MUP。

注解

网络重定向程序应仅通过验证 Irp-RequestorMode> 是否为 KernelMode 来接受此 IOCTL 的内核模式发送方。

请注意，IOCTL_REDIR_QUERY_PATH_EX是 IOCTL METHOD_NEITHER。这意味着输入和输出缓冲区可能不在同一地址。 UNC 提供程序的一个常见错误是假定输入缓冲区和输出缓冲区相同，并使用输入缓冲区指针提供响应。

当 UNC 提供程序收到IOCTL_REDIR_QUERY_PATH_EX请求时，它必须确定它是否可以处理在 QUERY_PATH_REQUEST_EX 结构的 PathName 成员中指定的 UNC 路径。如果是这样，UNC 提供程序必须更新QUERY_PATH_RESPONSE结构的 LengthAccepted 成员，其所声明的前缀长度（以字节为单位），并使用STATUS_SUCCESS完成 IRP。如果提供程序无法处理指定的 UNC 路径，则它必须使IOCTL_REDIR_QUERY_PATH_EX请求失败并显示相应的 NTSTATUS 错误代码，并且不得更新QUERY_PATH_RESPONSE结构的 LengthAccepted 成员。提供程序不得在任何条件下修改任何其他成员或 PathName 成员。

提供程序声明的前缀的长度取决于单个 UNC 提供程序。大多数提供程序通常声明 \\servername\sharename 路径 形式的路径的 \\servername\sharename\部分。例如，如果提供程序在给定路径 \\server\ publicdir1\dir2 的情况下声明了 \\server\public\，则前缀 \\server\public (\\server\public\file1（例如，) ）的所有基于名称的操作将自动路由到该提供程序，而无需任何前缀解析，因为前缀已在前缀缓存中。但是，前缀为 \\server\marketing\演示文稿 的路径将经过前缀解析。

如果网络重定向程序声明服务器名称 (\\server（例如) ），则此服务器上的所有共享请求都将转到此网络重定向程序。仅当不同网络重定向程序不可能访问同一服务器上的另一个共享时，此行为才可接受。例如，声明 UNC 路径 \\server 的网络重定向程序将阻止其他网络重定向程序访问此服务器上的其他共享， (WebDAV 访问 \\server\Web，例如) 。

有关详细信息，请参阅设计指南中的以下部分：