使用上下文句柄进行接口开发

通常，可以通过在 IDL 文件中的类型定义上指定 [context_handle] 属性来创建上下文句柄。 类型定义还隐式指定必须提供的上下文运行例程。 如果客户端和服务器之间的通信中断，服务器运行时会调用此例程来执行任何所需的清理。 有关上下文向下运行例程的详细信息，请参阅 服务器上下文运行例程。

使用上下文句柄的接口必须具有初始绑定的绑定句柄，这必须先发生，服务器才能返回上下文句柄。 可以使用自动、隐式或显式绑定句柄来创建绑定并建立上下文。

上下文句柄必须是 void * 类型，或解析为 void *的类型。 服务器程序将其强制转换为所需的类型。

注意

不建议将 [in， out] 用于上下文句柄参数，但关闭上下文句柄的例程除外。 如果使用上下文句柄标记为 [in， out] 的参数，请不要将 NULL 或未初始化的上下文句柄从客户端传递到服务器。 应改为传递指向上下文句柄的 NULL 指针。 请注意，标记为 [in] 的上下文句柄参数不接受 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 函数创建有效的非 null 上下文句柄。 它将上下文句柄传递给客户端。 后续远程过程调用（如 RemoteRead）使用上下文句柄作为指针中的 。

除了初始化上下文句柄的远程过程外，接口还必须包含释放服务器上下文并将上下文句柄设置为 NULL 的过程。 在前面的示例中，RemoteClose 函数执行此操作。