基元和自定义绑定句柄

使用 handle_tRPC_BINDING_HANDLE 类型声明的所有句柄都是基元绑定句柄。 可以扩展 handle_tRPC_BINDING_HANDLE 类型,以包含比基元句柄类型包含的更多或不同的信息。 执行此操作时,将创建自定义绑定句柄。

若要为分布式应用程序创建自定义绑定句柄,需要创建自己的数据类型,并在 IDL 文件中的类型定义上指定 [ handle] 属性。 最终,存根文件将自定义绑定句柄映射到基元句柄。

如果确实创建了自己的绑定句柄类型,则还必须提供客户端存根用于将自定义句柄映射到基元句柄的绑定和取消绑定例程。 存根在每个远程过程调用的开头和结尾调用绑定和取消绑定例程。 绑定和取消绑定例程必须符合以下函数原型。

函数原型 说明
handle_t type_bind (类型) 绑定例程
void type_unbind (类型handle_t) 取消绑定例程

 

以下示例演示如何在 IDL 文件中定义自定义绑定句柄:

/* usrdef.idl */
[
  uuid(20B309B1-015C-101A-B308-02608C4C9B53),
  version(1.0),
  pointer_default(unique)
]
interface usrdef
{
  typedef struct _DATA_TYPE 
  {
      unsigned char * pszUuid;
      unsigned char * pszProtocolSequence;
      unsigned char * pszNetworkAddress;
      unsigned char * pszEndpoint;
      unsigned char * pszOptions;
  } DATA_TYPE;
 
  typedef [handle] DATA_TYPE * DATA_HANDLE_TYPE;
  void UsrdefProc([in] DATA_HANDLE_TYPE  hBinding,
                  [in, string] unsigned char *   pszString);
 
  void Shutdown([in] DATA_HANDLE_TYPE hBinding);
}

如果绑定例程遇到错误,它应使用 RpcRaiseException 函数引发异常。 然后,客户端存根将清理,并让异常筛选到客户端上远程过程调用周围的异常块。 如果绑定例程仅返回 NULL,则客户端代码RPC_S_INVALID_BINDING收到错误。 虽然在某些情况下可以接受这一点,但其他 (情况(例如内存不足) 响应不佳)。 应设计取消绑定例程,使其不会失败。 取消绑定例程不应引发异常。

程序员定义的绑定和取消绑定例程显示在客户端应用程序中。 在以下示例中,绑定例程调用 RpcBindingFromStringBinding 将字符串绑定信息转换为绑定句柄。 取消绑定例程调用 RpcBindingFree 以释放绑定句柄。

程序员定义的绑定句柄的名称(DATA_HANDLE_TYPE)显示为函数名称的一部分。 它还用作函数参数中的参数类型。

/* The client stub calls this _bind routine at the */
/* beginning of each remote procedure call                */
 
RPC_BINDING_HANDLE __RPC_USER DATA_HANDLE_TYPE_bind(
    DATA_HANDLE_TYPE dh1)
{
    RPC_BINDING_HANDLE hBinding;
    RPC_STATUS status;
 
    unsigned char *pszStringBinding;
 
    status = RpcStringBindingCompose(
          dh1.pszUuid,
          dh1.pszProtocolSequence,
          dh1.pszNetworkAddress,
          dh1.pszEndpoint,
          dh1.pszOptions,
          &pszStringBinding);
          ...
 
    status = RpcBindingFromStringBinding(
          pszStringBinding,
          &hBinding);
          ...
 
    status = RpcStringFree(&pszStringBinding); 
    ...
 
    return(hBinding);
}
 
/* The client stub calls this _unbind routine */
/* after each remote procedure call.                            */
void __RPC_USER DATA_HANDLE_TYPE_unbind(
    DATA_HANDLE_TYPE dh1, 
    RPC_BINDING_HANDLE h1)
{
    RPC_STATUS status;
    status = RpcBindingFree(&h1); 
    ...
}

隐式和显式绑定句柄可以是基元句柄,也可以是自定义句柄。 也就是说,句柄可以是:

  • 基元和隐式
  • 自定义和隐式
  • 基元和显式
  • 自定义和显式