使用內容句柄進行客戶端開發

唯一的用途是用戶端程式使用上下文控制代碼在每次遠端過程調用時將其傳遞給伺服器。 用戶端應用程式不需要存取句柄的內容。 它不應該嘗試以任何方式變更內容處理數據。 用戶端叫用的遠端程式會在伺服器的內容上執行所有必要的作業。

在向伺服器要求內容句柄之前，客戶端必須與伺服器建立系結。 客戶端可以使用自動、隱式或顯式的綁定句柄。 透過有效的系結句柄，用戶端可以在伺服器上呼叫遠端程式，該程式會傳回已開啟的（非NULL）內容句柄，或透過遠端程序參數清單中的 [out] 參數傳遞一個。

客戶可以透過任何需要的方式使用已開啟的內容句柄。 不過，當不再需要時，應該使句柄失效。 有兩種方式可以執行此動作：

• 若要叫用伺服器程序所提供的遠端程序以釋放上下文並關閉上下文句柄（將其設為 NULL）。
• 當伺服器無法連線時，請呼叫 RpcSsDestroyClientContext 函式。

第二種方法只會清除客戶端狀態，而且不會清除伺服器端狀態，因此只有在懷疑網路分割區時才會使用，而用戶端和伺服器會執行獨立的清除。 伺服器會透過 run-down 例程執行獨立清除，用戶端會使用 RpcSsDestroyClientContext 函式來執行。

下列代碼段提供用戶端如何使用內容句柄的範例。 若要檢視此範例所使用的介面定義，請參閱使用內容句柄 介面開發。 如需伺服器實作，請參閱使用內容句柄 伺服器開發。

在此範例中，用戶端會呼叫 RemoteOpen，以取得包含有效數據的內容句柄。 客戶端接著可以在遠端程序呼叫中使用上下文句柄。 因為不再需要系結句柄，用戶端可以釋放它用來建立內容句柄的明確句柄：

// cxhndlc.c  (fragment of client side application)
printf("Calling the remote procedure RemoteOpen\n");
if (RemoteOpen(&phContext, pszFileName) < 0) 
{
    printf("Unable to open %s\n", pszFileName);
    Shutdown();
    exit(2);
}
 
// Now the context handle also manages the binding.
// The variable hBindingHandle is a valid binding handle.
status = RpcBindingFree(&hBindingHandle);
printf("RpcBindingFree returned 0x%x\n", status);
if (status) 
    exit(status);

此範例中的用戶端應用程式會使用名為 RemoteRead 的程式，讀取伺服器上的資料檔，直到它遇到檔尾為止。 然後，它會呼叫 RemoteClose 來關閉檔案。 上下文句柄作為 RemoteRead 和 RemoteClose 函式中的參數。

printf("Calling the remote procedure RemoteRead\n");
do 
{
    cbRead = 1024; // Using a 1K buffer
    RemoteRead(phContext, pbBuf, &cbRead);
    // cbRead contains the number of bytes actually read.
    for (int i = 0; i < cbRead; i++)
        putchar(*(pbBuf+i));
} while(cbRead);
 
printf("Calling the remote procedure RemoteClose\n");
if (RemoteClose(&phContext) < 0 ) 
{
    printf("Close failed on %s\n", pszFileName);
    exit(2);
}