PMRX_CREATE_V_NET_ROOT回呼函式 (mrx.h)

發行項
02/26/2024

MRxCreateVNetRoot 例程是由 RDBSS 呼叫，以要求網路迷你重新導向器建立V_NET_ROOT結構，在某些情況下為NET_ROOT結構。

語法

PMRX_CREATE_V_NET_ROOT PmrxCreateVNetRoot;

NTSTATUS PmrxCreateVNetRoot(
  IN OUT PMRX_CREATENETROOT_CONTEXT Context
)
{...}

參數

Context

[in， out]網路迷你重新導向器用來在呼叫完成時通知 RDBSS 的回呼內容的指標。這包括在Context-RxContext>要求RX_CONTEXT結構。 Context 參數包含要建構於 Context-pVNetRoot> 的V_NET_ROOT結構。這個V_NET_ROOT結構包含 pVNetRoot-pNetRoot> 上NET_ROOT結構的指標。 NET_ROOT 結構也包含 pNetRoot-pSrvCall> 上SRV_CALL結構的指標。

傳回值

RDBSS 預期 MRxCreateVNetRoot 會在成功或失敗時傳回STATUS_PENDING。此行為會導致 RDBSS 預期此呼叫會以異步方式完成。網路迷你重新導向器應該將STATUS_SUCCESS對應至STATUS_PENDING做為 MRxCreateVNetRoot 的傳回值。

一旦呼叫完成，內容結構之Callback 成員中的例程就會在 Context-VirtualNetRootStatus> 和 Context-NetRootStatus> 成員中傳回最終完成狀態，由網路迷你重新導向器呼叫。這些成員一開始會包含STATUS_SUCCESS，直到網路迷你重新導向器在完成時變更此值為止。如果呼叫成功完成，則這兩個成員都包含STATUS_SUCCESS。

在無法建立V_NET_ROOT或NET_ROOT結構時，會傳 (回VirtualNetRootStatus 或 NetRootStatus 成員的下列其中一個常見錯誤碼，但可能會) ：

傳回碼	Description
STATUS_CONNECTION_RESET	已重設遠端資源的連線。
STATUS_IO_TIMEOUT	I/O 要求發生逾時。
STATUS_RETRY	遠端開機伺服器尚未準備好滿足要求。
STATUS_UNEXPECTED_NETWORK_ERROR	發生非預期的網路錯誤通常是由無效的句柄所造成。

備註

RDBSS 與網路迷你重新導向器之間介面中使用的兩個重要抽象概念是SRV_CALL結構和NET_ROOT/V_NET_ROOT結構。 SRV_CALL 結構會對應至與已建立連接之伺服器相關聯的內容。 NET_ROOT結構會對應至伺服器上的共用。 V_NET_ROOT結構可視為網路迷你重新導向器所宣告NET_ROOT結構下方命名空間的一部分。

建立NET_ROOT/V_NET_ROOT結構通常牽涉到至少一個網路來回行程。這項作業可能需要相當長的時間才能完成，因為可能需要建立與遠端資源的網路連線。為了確保異步操作繼續，建立NET_ROOT/V_NET_ROOT結構會模型化為兩階段活動。每次呼叫網路迷你重新導向器以建立NET_ROOT/V_NET_ROOT結構，後面接著從網路迷你重新導向器回呼至 RDBSS，以指出 RDBSS 對網路迷你重新導向器的要求完成狀態。因為 RDBSS 預期 MRxCreateVNetRoot 是以異步方式完成，所以 RDBSS 預期 MRxCreateVNetRoot 會傳回STATUS_PENDING。當呼叫最後完成時，RDBSS 將會使用回呼例程收到通知。

MRxCreateVNetRoot 必須處理兩個感興趣的案例：

正在建立新的V_NET_ROOT結構和相關聯的新NET_ROOT結構。
正在建立與現有NET_ROOT結構相關聯的新V_NET_ROOT結構。

這兩種情況可以藉由檢查與NET_ROOT結構相關聯的內容是否為 NULL 來區分。

MRxCreateVNetRoot 的網路迷你重新導向器實作預期會傳回初始呼叫STATUS_PENDING。處理完成時，網路迷你重新導向器會呼叫傳入做為 Context 參數一部分的回呼例程，以通知 RDBSS 呼叫已完成並傳回完成狀態。網路迷你重新導向器應該呼叫的回呼例程會指定為傳遞為Context參數之MRX_CREATENETROOT_CONTEXT結構中的 Callback 成員。 MRxCreateVNetRoot 呼叫的最終完成狀態必須儲存在 Context 參數的 VirtualNetRootStatus 和 NetRootStatus 成員中。請注意，會針對NET_ROOT和V_NET_ROOT結構傳回個別的狀態。

網路迷你重新導向器中的 MRxCreateVNetRoot 實作也會因傳輸句柄的需求而複雜。某些傳輸相關介面需要建立句柄，並用於所有通訊。建立NET_ROOT或V_NET_ROOT結構可能需要建立網路通訊的傳輸相關句柄。由於建立網路連線的程式可能相當耗時，一旦建立連線，就盡可能使用聯機進行通訊是有意義的。一旦建立遠端網路資源的傳輸句柄，就可以由任意數目的其他應用程式要求重複使用。當使用者應用程式終止時，會刪除與進程相關聯的句柄。因此，在暫時性使用者模式進程的內容中建立傳輸句柄可能短期並不合理。因此，NET_ROOT或V_NET_ROOT結構通常必須在已知進程的內容中初始化，而這些傳輸句柄用於通訊時不會消失。

在網路迷你重新導向器中用來管理此動作的其中一種方法是讓 RDBSS 系統進程配置這些傳輸句柄。這會影響 MRxCreateVNetRoot 例程的執行方式。如果在 RDBSS 系統進程的內容中發出 MRxCreateVNetRoot 的要求，則可以立即執行此呼叫，而不需要張貼到工作佇列。不過，為了避免發生問題，如果 MRxCreateVNetRoot 的要求來自任何其他進程，則會使用 RxDispatchToWorkerThread 將要求張貼到系統工作佇列，以供稍後執行。 RDBSS 稍後會使用其中一個系統線程來處理工作佇列要求，並執行 MRxCreateVNetRoot。這可確保系統進程會擁有任何傳輸句柄。

網路迷你重新導向器可以透過呼叫 RxGetRDBSSProcess，判斷是否直接從 RDBSS 接收 MRxCreateVNetRoot 呼叫。 RxGetRDBSSProcess 會傳回 RDBBS 進程，而且此值可以與呼叫 IoGetCurrentProcess 傳回的目前進程進行比較。如果在 RDBSS 系統進程的內容中未起始 MRxCreateVNetRoot 呼叫， 則 MRxCreateVNetRoot 可以傳回STATUS_PENDING並使用 RxDispatchToWorkerThread 呼叫工作佇列，以供 RDBSS 稍後執行。一般而言，這些呼叫會張貼到 DelayedWorkQueue。

由網路迷你重新導向器決定如何實作 MRxCreateVNetRoot 。如果此程式可能需要相當長的時間，則應該以異步方式完成此呼叫。如果需要傳輸句柄，則網路迷你重新導向器可能會想要長時間存在的系統進程來建立這些句柄。

如果無法建立連線，則網路迷你重新導向器可以嘗試將NET_ROOT和V_NET_ROOT結構轉換成中斷連線模式， (如果支援此) 並脫機建立連線。

當 MRxCreateVNetRoot 完成時，Context 參數應該使用適當的NET_ROOT修改，並V_NET_ROOT從網路迷你重新導向器更新的結構資訊。