PMRX_CREATE_SRVCALL回呼函式 (mrx.h)

發行項
03/05/2024

RDBSS 會呼叫 MRxCreateSrvCall 例程，要求網路迷你重新導向器建立SRV_CALL結構，並建立與伺服器的連線。

語法

PMRX_CREATE_SRVCALL PmrxCreateSrvcall;

NTSTATUS PmrxCreateSrvcall(
  IN OUT PMRX_SRV_CALL SrvCall,
  IN OUT PMRX_SRVCALL_CALLBACK_CONTEXT SrvCallCallBackContext
)
{...}

參數

SrvCall

[in， out]要建立之SRV_CALL結構的指標。

SrvCallCallBackContext

[in， out]網路迷你重新導向器用來在 MRxCreateSrvCall 要求完成時通知 RDBSS 的回呼內容的指標。 SrvCallCallBackContext 參數指向包含此要求的RX_CONTEXT結構MRX_SRVCALLDOWN_STRUCTURE結構，以及迷你重新導向器在 MRxCreateSrvCall 要求完成時所呼叫的回呼例程。

傳回值

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

呼叫完成後，SrvCallCallBackContext-Status> 成員會傳回最終完成狀態，而網路迷你重新導向器會呼叫 MRX_SRVCALLDOWN_STRUCTURE 結構中回呼成員中的例程。此成員一開始包含STATUS_BAD_NETWORK_PATH，直到網路迷你重新導向器在完成時變更此值為止。

SrvCallCallBackContext-Status> 成員在呼叫完成之後，包含成功時STATUS_SUCCESS，或失敗時發生下列其中一個常見錯誤碼 (，但其他錯誤碼可能) ：

傳回碼	Description
STATUS_BAD_NETWORK_PATH	指定的網路路徑不正確。
STATUS_NETWORK_UNREACHABLE	無法連線到網路。

備註

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

建立SRV_CALL結構通常牽涉到至少一個網路往返。這項作業可能需要相當長的時間才能完成，因為可能需要建立與遠端資源的網路連線。為了確保異步操作繼續，建立SRV_CALL結構會模型化為兩階段活動。每個呼叫建立SRV_CALL結構的網路迷你重新導向器，都會伴隨從網路迷你重新導向器呼叫 RDBSS，以指定要求的完成狀態。 RDBSS 假設 MRxCreateSrvCall 會以異步方式完成。因此 RDBSS 預期 MRxCreateSrvCall 會傳回STATUS_PENDING。 RDBSS 會在呼叫最後完成時，使用回呼例程收到通知。

MRxCreateSrvCall 的網路迷你重新導向器實作預期會傳回初始呼叫STATUS_PENDING。處理完成時，網路迷你重新導向器會呼叫作為 SrvCallCallBackContext 參數一部分傳入的回呼例程，以通知 RDBSS 呼叫已完成並傳回完成狀態。網路迷你重新導向器呼叫的回呼例程會指定為 SrvCallCallBackContext 參數MRX_SRVCALLDOWN_STRUCTURE中的 Callback 成員。呼叫的最終完成狀態必須儲存在 SrvCallCallBackContext 參數的 Status 成員中。

成功時，網路迷你重新導向器也必須將某些值儲存在 SrvCallBackContext 的 RecommunicateContext 成員中。儲存在 RecommunicateContext 成員中的值是如果 MRxCreateSrvCall 成功，RDBSS 將會傳遞至 RecommunicateContext 參數中的 MRxSrvCallWinnerNotify 的值。網路迷你重新導向器也必須在 SrvCall 參數中填入所建立之SRV_CALL結構的適當數據。請注意，傳遞至 MRxCreateSrvCall 的 SrvCall 參數與 SrvCall 參數MRX_SRVCALLDOWN_STRUCTURE中的 SrvCall 成員相同。這個相同的 SrvCall 參數也會傳遞至 SrvCall 參數中的 MRxSrvCallWinnerNotify。

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

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

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

網路迷你重新導向器的開發人員決定如何實作 MRxCreateSrvCall 。如果建立SRV_CALL的程式可能需要相當長的時間，則應該以異步方式完成 MRxCreateSrvCall 。如果需要傳輸句柄，網路迷你重新導向器必須尋找長時間存留的系統進程，才能建立這些句柄。

當此呼叫完成時，應該使用從網路迷你重新導向器更新的 SRV_CALL 結構資訊來修改 SrvCall 參數。

指出支援為 UNC 提供者的網路迷你重新導向器，將會從多個 UNC 提供者收到前置詞宣告， (MUP) 作為 MRxCreateSrvCall 的呼叫。如需 UNC 命名和 MUP 的詳細資訊，請參閱 UNC 命名和 MUP 的支援。