IOCTL_REDIR_QUERY_PATH_EX IOCTL (ntifs.h)

發行項
02/29/2024

從 Windows Vista 開始，多個 UNC 提供者 (MUP) 會將 IOCTL_REDIR_QUERY_PATH_EX 控制程式代碼傳送給網路重新導向器，以判斷哪些提供者可以在以名稱為基礎的作業中處理特定 UNC 路徑，通常是IRP_MJ_CREATE要求。此要求稱為「前置詞解析」。

MUP 是核心模式元件，負責使用 UNC 名稱將所有遠端檔案系統存取通道傳送至網路重新導向器， (UNC 提供者) 能夠處理遠端檔案系統要求。使用 UNC 路徑時牽涉到 MUP，如下列可從命令行執行的範例所示：

notepad \\server\public\readme.txt

在建立對應驅動器號的作業期間，不會涉及 MUP (“NET USE” 命令，例如) 。此作業是由多個提供者路由器處理， (MPR) ，以及網路重新導向器的使用者模式 WNet 提供者 DLL。不過，使用者模式 WNet 提供者 DLL 可能會在這項作業期間直接與內核模式網路重新導向器驅動程序通訊。

對於符合 Windows Vista 重新導向器模型的網路重新導向器，即使使用對應的網路驅動器機，也會涉及 MUP。在對應的磁碟驅動器上執行的檔案作業會通過 MUP 至網路重新導向器。請注意，在此情況下，MUP 只會將作業傳遞至所涉及的網路重新導向器。

IOCTL_REDIR_QUERY_PATH_EX控制程式代碼會藉由呼叫 FsRtlRegisterUncProviderEx，將 MUP 註冊為通用命名慣例 (UNC) 提供者的網路重新導向器。可以有多個 UNC 提供者向 MUP 註冊。

前置詞解析作業有兩個用途：

導致前置詞解析的名稱型作業會路由傳送至宣告前置詞的提供者。如果成功，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 前置詞名稱，或設為適當的 NTSTATUS 值， 則 Status 成員會在成功時設定為STATUS_SUCCESS，例如下列其中一項：

狀態碼	意義
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。

備註

網路重新導向器應該只接受此 IOCTL 的核心模式傳送者，方法是確認 Irp-RequestorMode> 為 KernelMode。

請注意，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 成員，其長度，以位元組為單位，其已宣告前置詞的 LengthAccepted 成員，並使用STATUS_SUCCESS完成 IRP。如果提供者無法處理指定的 UNC 路徑，它必須以適當的 NTSTATUS 錯誤碼失敗IOCTL_REDIR_QUERY_PATH_EX要求，且不得更新QUERY_PATH_RESPONSE結構的 LengthAccepted 成員。提供者不得在任何條件下修改任何其他成員或 PathName 成員。

提供者所宣告前置詞的長度取決於個別的 UNC 提供者。大部分的提供者通常會宣告格式為 \\servername\共享名稱路徑之路徑的 \\servername\ 共用名稱\部分。例如，如果提供者宣告 \\server\public 指定路徑 \\server\public\dir2\，則前置詞 \\serverpublic (\\server\\public\file1 的所有名稱型作業都會自動路由傳送至該提供者) ，而不需要前置詞解析，因為前置詞已經位於前置詞快取中。不過，前置詞為 \\server\marketing\簡報的路徑將經歷前置詞解析。

如果網路重新導向器宣告伺服器名稱 (\\server，例如) ，此伺服器上共用的所有要求都會移至此網络重新導向器。只有在不同網路重新導向器無法存取相同伺服器上的另一個共用時，才能接受此行為。例如，宣告 UNC 路徑 \\server 的網路重新導向器會防止其他網路重新導向器存取此伺服器上的其他共用， (WebDAV 存取 \\server\web，例如) 。

如需詳細資訊，請參閱設計指南中的下列各節：