使用上下文句柄進行介面開發

一般而言，您會在 IDL 檔案的類型定義上指定 [context_handle] 屬性，以建立內容句柄。 類型定義還會隱含指定上下文終止例程，您必須提供此例程。 如果客戶端與伺服器之間的通訊中斷，伺服器運行時間會叫用此例程來執行任何必要的清除。 如需內容執行例程的詳細資訊，請參閱 伺服器內容執行例程。

使用上下文句柄的介面必須先具備初始系結的系結句柄，這必須在伺服器傳回上下文句柄之前完成。 您可以使用自動、隱含或明確的系結句柄來建立系結並建立內容。

上下文句柄必須是 void * 類型，或者是一種解析為 void *的類型。 伺服器程式會將它轉換成所需的類型。

注意

除非用於關閉上下文控制碼的例程，否則不建議在中使用 [， out]。 如果使用上下文句柄被標記為 [， out] 的參數，請勿將 NULL 或未初始化的上下文句柄從客戶端傳遞至伺服器。 應該改為傳遞內容句柄 NULL 指標。 請注意，標示為 [在] 的上下文控制參數不接受 NULL 指標。

 

下列範例介面定義的片段顯示分散式應用程式如何使用內容句柄來開啟伺服器，並更新每個客戶端的數據檔。

介面必須包含遠端程序呼叫來初始化句柄，並將其設定為非null 值。 在此範例中，RemoteOpen 函式會執行這項作業。 它會指定具有 [out] 方向屬性的上下文處理程序。 或者，您可以將上下文句柄作為程序的傳回值。 不過，在此範例中，我們將透過參數清單傳遞內容句柄。

在此範例中，內容資訊是文件句柄。 它會追蹤檔案中的目前位置。 介面會將檔案句柄封裝為內容句柄，並將它當做參數傳遞給遠端過程調用。 結構包含檔名和檔句柄。

/* file: cxhndl.idl (fragment of interface definition file) */
typedef [context_handle] void * PCONTEXT_HANDLE_TYPE;
typedef [ref] PCONTEXT_HANDLE_TYPE * PPCONTEXT_HANDLE_TYPE;
 
short RemoteOpen([out] PPCONTEXT_HANDLE_TYPE pphContext,
    [in, string] unsigned char * pszFile);
 
void RemoteRead(
    [in] PCONTEXT_HANDLE_TYPE phContext,
    [out, size_is(cbBuf)] unsigned char achBuf[],
    [in, out] short *pcbBuf);
 
short RemoteClose([in, out] PPCONTEXT_HANDLE_TYPE pphContext);

RemoteOpen 函式會建立有效的非空 上下文句柄。 它會將上下文控制代碼傳遞給用戶端。 後續的遠端過程呼叫，例如 RemoteRead，使用上下文句柄作為輸入指標。

除了初始化內容句柄的遠端程式之外，介面還必須包含釋放伺服器內容的程式，並將內容句柄設定為 NULL。 在上述範例中，RemoteClose 函式會執行這項作業。