RxStartMinirdr 函式 (mrx.h)

發行項
02/26/2024

系統會呼叫 RxStartMinirdr 來啟動先前呼叫以向 RDBSS 註冊的網路迷你重新導向器。在 RxStartMinirdr 中，如果驅動程式指出 UNC 名稱支援，RDBSS 也會將網路迷你重新導向器驅動程式註冊為通用命名慣例， (UNC) 提供者 (MUP) 。

語法

NTSTATUS RxStartMinirdr(
  [in]  IN PRX_CONTEXT RxContext,
  [out] OUT PBOOLEAN   PostToFsp
);

參數

[in] RxContext

用來取得裝置物件的RX_CONTEXT結構的指標，並判斷這是否為文件系統進程。

[out] PostToFsp

如果要求必須張貼以供文件系統進程稍後處理，則邏輯值的指標會在傳回時設定為 TRUE。

傳回值

如果啟動序列成功或下列其中一個錯誤值，RxStartMinirdr 會傳回STATUS_SUCCESS：

傳回碼	Description
STATUS_ACCESS_DENIED	註冊為 UNC 提供者的要求失敗，因為存取遭到拒絕。
STATUS_ACCESS_VIOLATION	註冊為 UNC 提供者的要求因存取違規而失敗。
STATUS_INSUFFICIENT_RESOURCES	資源不足，無法完成此例程。
STATUS_PENDING	RDBSS 和網路迷你重新導向器的啟動順序必須在系統進程的內容中完成，而不是使用者模式應用程式進程。如果對 RxStartMinirdr 的呼叫來自使用者模式進程， (使用者模式服務要求，例如) ，則會在 RDBSS 內張貼要求以供稍後處理，並傳回STATUS_PENDING。如果某些內部 RDBSS 鎖定無法在等候的情況下取得，也可以傳回此錯誤。稍後會從系統線程完成呼叫。
STATUS_REDIRECTOR_STARTED	網路迷你重新導向器已啟動。

備註

每當核心載入驅動程式時，網路迷你重新導向器會向 RDBSS 註冊，然後在卸除驅動程式時向 RDBSS 取消註冊。網路迷你重新導向器會通知 RDBSS，其已透過呼叫 RxRegisterMinirdr 來載入，這是從 RDBSS 導出的註冊例程。在此註冊程式中，網路迷你重新導向器會將參數傳遞至 RxRegisterMinirdr ，這是大型結構的指標，MINIRDR_DISPATCH，其中包含網路迷你重新導向器的組態資訊，以及網路迷你重新導向器驅動程式所實作回呼例程的指標數據表。 RDBSS 會使用此結構中傳遞的回呼例程來與網路迷你重新導向器通訊。

網路迷你重新導向器在收到 MRxStart 例程的呼叫之前，不會實際啟動作業，這是在MINIRDR_DISPATCH結構中傳遞的其中一個回呼例程。如果想要接收作業的回呼例程，網路迷你重新導向器驅動程序必須實作 MrxStart 回呼例程，除非網路迷你重新導向器保留自己的驅動程式分派進入點。否則，RDBSS 將只允許下列 I/O 要求封包傳送至驅動程式，直到 MrxStart 成功傳回為止：

IRP 要求裝置建立作業和裝置作業，其中 IRPSP 上的 FileObject-FileName.Length> 參數為零，而 FileObject-RelatedFileObject> 參數為 NULL。

對於任何其他 IRP 要求，RDBSS 分派例程 RxFsdDispatch 會傳回STATUS_REDIRECTOR_NOT_STARTED的狀態。

RDBSS 分派例程也會失敗下列 I/O 要求封包的任何要求：

IRP_MJ_CREATE_MAILSLOT
IRP_MJ_CREATE_NAMED_PIPE

呼叫 RxStartMinirdr 例程時，RDBSS 會呼叫網路迷你重新導向器 MrxStart 例程。 RDBSS RxStartMinirdr 例程通常會因為來自使用者模式應用程式或服務的 FSCTL 或 IOCTL 要求而呼叫，以啟動網路迷你重新導向器。在成功呼叫 RxRegisterMinirdr 之後，無法從網路迷你重新導向器的 DriverEntry 例程呼叫 RxRegisterMinirdr 進行，因為某些開始處理需要完成驅動程式初始化。

當 RDBSS 收到從使用者模式傳送至網路迷你重新導向器驅動程式的 FSCTL 或 IOCTL 要求時，RDBSS 會建立RX_CONTEXT結構，並將此呼叫傳遞至網路迷你重新導向器的 MRxLowIOSubmit[LOWIO_OP_FSCTL] 或 MRxLowIOSubmit[LOWIO_OP_IOCTL] 呼叫MINIRDR_DISPATCH結構中定義的例程。此回呼例程的網路迷你重新導向器實作會辨識啟動和呼叫 RxStartMinirdr 的要求。以下更詳細地列出此一般事件程式：

使用者模式應用程式發出私人 FSCTL 或 IOCTL 要求，以啟動網路迷你重新導向器。
RDBSS 核心驅動程式會代表網路迷你重新導向器接收 FSCTL 或 IOCTL 要求，因為 RDBSS 已取代迷你重新導向器驅動程式的分派進入點，以指向 RDBSS 內部例程。請注意，這假設在呼叫 RxRegisterMinirdr 時，網路迷你重新導向器並未在 Controls 參數中設定RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH。傳遞至 RxRegisterMinirdr 的這個選項會很不尋常，並指出網路迷你重新導向器不希望 RDBSS 取代其驅動程式分派進入點。
RDBSS 會代表網路重新導向器在內部接收 FSCTL 或 IOCTL 要求。 RDBSS 發送器會配置和初始化RX_CONTEXT結構。 RDBSS 接著會呼叫網路迷你重新導向器 MRxLowIOSubmit[LOW_OP_FSCTL] 或 MRxLowIOSubmit[LOW_OP_IOCTL] 例程，此網络迷你重新導向器MINIRDR_DISPATCH結構中所定義的例程，以參數方式傳入初始化RX_CONTEXT結構。
此回呼例程的網路迷你重新導向器實作會辨識要啟動和呼叫 RxStartMinirdr 的私人 FSCTL 或 IOCTL 要求，並傳入從 RDBSS 收到的RX_CONTEXT結構作為 RxContext 參數，以及 RxContext 的 PostToFSP 成員地址作為 PostToFsp 參數。
由於此呼叫是從使用者模式起始， 所以 RxStartMinirdr 會傳回STATUS_PENDING並將 PostToFsp 設定為 TRUE。
網路迷你重新導向器 MRxLowIOSubmit[LOW_OP_FSCTL] 或 MRxLowIOSubmit[LOW_OP_IOCTL] 例程會收到此傳回值，並將其傳回 RDBSS 發送器。
RDBSS 發送器會收到STATUS_PENDING傳回值，並將 PostToFsp 設定為 TRUE，然後將要求張貼至背景工作線程，以重新執行對網路迷你重新導向器的呼叫。

此時，根據 FSCTL 或 IOCTL 要求為異步或同步作業，有兩個可能的結果。

如果這是異步要求，就會發生下列情況：

使用者模式呼叫者會收到來自呼叫的STATUS_PENDING回應。張貼的背景工作線程最終會從文件系統線程呼叫 RxStartMinirdr ，並處理呼叫。如果要求， RxStartMinirdr 例程會嘗試將網路迷你重新導向器註冊為 UNC 提供者。在 Windows Vista 之前的 Windows 版本上，RDBSS 會嘗試向 I/O 管理員註冊網路迷你重新導向器作為文件系統。如果這些呼叫成功， 則 RxStartMinirdr 會呼叫網路迷你重新導向器所實作的 MrxStart 回呼例程。 MrxStart 的傳回值最終會傳回至使用者模式應用程式，以異步操作的形式起始呼叫順序進程。

如果這是同步要求，會發生下列情況：

使用者模式呼叫端不會收到STATUS_PENDING回應，但會強制等候從張貼背景工作線程傳回的呼叫。張貼的背景工作線程最終會從文件系統線程呼叫 RxStartMinirdr ，並處理呼叫。如果要求， RxStartMinirdr 例程會嘗試將網路迷你重新導向器註冊為 UNC 提供者。在 Windows Vista 之前的 Windows 版本上，RDBSS 會嘗試向 I/O 管理員註冊網路迷你重新導向器作為文件系統。如果這些呼叫成功， 則 RxStartMinirdr 會呼叫網路迷你重新導向器所實作的 MrxStart 回呼例程。 MrxStart 的傳回值會傳回至起始呼叫順序進程的使用者模式應用程式。

如果網路迷你重新導向器指出在向 RDBSS 註冊時支援 UNC (Controls 參數至 RxRegisterMinirdr) ， 則 RxStartMinirdr 會嘗試將網路迷你重新導向器的 DeviceName 參數註冊為具有 MUP (RDBSS 呼叫 FsRtlRegisterUncProvider 的 UNC 提供者，以代表網路迷你重新導向器) 。

在 Windows Vista 之前的 Windows 版本上， RxStartMinirdr 會代表網路迷你重新導向器) 向 I/O 管理員註冊文件系統 (RDBSS 呼叫 IoRegisterFileSystem 。

如果呼叫成功， 則 RxStartMinirdr 會呼叫網路迷你重新導向器 MrxStart 例程。如果 MrxStart 傳回成功，RDBSS 中迷你重新導向器的內部狀態會設定為 RDBSS_STARTED。迷你重新導向器裝置物件的 StartStopContext.Version 成員也會遞增。

如果要求異步操作，就必須在系統進程的內容中完成 RDBSS 和網路迷你重新導向器的啟動順序。如果 對 RxStartMinirdr 的呼叫來自使用者模式進程 (使用者模式服務要求，例如) ，則 RDBSS 會在內部將要求張貼到工作佇列以供稍後處理，並傳回 STATUS_PENDING，PostToFsp 參數會設定為 TRUE。此外，如果在等候的情況下無法取得某些內部 RDBSS 鎖定，則會傳回STATUS_PENDING，且 PostToFsp 設定為 TRUE。傳回STATUS_PENDING時，系統會從系統進程內再次呼叫 RxStartMinirdr 。如果已針對異步操作設定起始對 RxStartMinirdr 呼叫的 FSCTL 或 IOCTL 要求，則 RDBSS 會傳回STATUS_PENDING將呼叫鏈備份至使用者模式的原始 FSCTL 或 IOCTL 要求。相反地，如果 FSCTL 或 IOCTL 要求用於同步作業，則呼叫也會張貼到工作線程以供稍後執行，但在文件系統進程的內容中執行 RxStartMinirdr 之前，FSCTL 或 IOCTL 呼叫不會返回使用者模式。在此情況下，FSCTL 或 IOCTL 的呼叫端永遠不會看到傳回STATUS_PENDING錯誤。較常見的行為是起始這些啟動/停止作業的同步要求，以簡化使用者模式應用程式程序代碼。

在異常終止或其他失敗時， RxStartMinirdr 會嘗試復原這些作業，包括取消向 MUP 註冊 UNC 提供者、取消註冊文件系統、釋放配置用來儲存 mailslot 廣播所用功能變數名稱的記憶體，以及更新內部 RDBSS 數據表。