Microsoft RPC Binding-Handle Extensions

  • Article

The Microsoft extensions to the IDL language support multiple handle parameters that appear in positions other than the first, leftmost, parameter. The following steps describe the sequence that the MIDL compiler goes through to resolve the binding-handle parameter in DCE-compatibility mode (/osf), and in default (Microsoft-extended) mode.

DCE-compatibility mode

  • Binding handle that appears in first position.
  • Leftmost [in, context_handle] parameter.
  • Implicit binding handle specified by [implicit_handle] or [auto_handle].
  • If no ACF present, default to use of [auto_handle].

Default mode

DCE IDL compilers look for an explicit binding handle as the first parameter. When the first parameter is not a binding handle and one or more context handles are specified, the leftmost context handle is used as the binding handle. When the first parameter is not a handle and there are no context handles, the procedure uses implicit binding using the ACF attribute [implicit_handle] or [auto_handle].

The Microsoft extensions to the IDL allow the binding handle to be in a position other than the first parameter. The leftmost [in] explicit-handle parameter–whether it is a primitive, programmer-defined, or context handle–is the binding handle. When there are no handle parameters, the procedure uses implicit binding using the ACF attribute [implicit_handle] or [auto_handle].

The following rules apply to both DCE-compatibility (/osf) mode and default mode:

  • Auto-handle binding is used when no ACF is present.
  • Explicit [in] or [in, out] handles for an individual function preempt any implicit binding specified for the interface.
  • Multiple [in] or [in, out] primitive handles are not supported.
  • Multiple [in] or [in, out] explicit context handles are allowed.
  • All programmer-defined handle parameters except the binding-handle parameter are treated as transmissible data.

The following table contains examples and describes how binding handles are assigned in each compiler mode.

Example Description 
void proc1( void );
 No explicit handle is specified. The implicit binding handle, specified by [ implicit_handle] or [ auto_handle], is used. When no ACF is present, an auto handle is used. 
void proc2([in] handle_t H,           [in] short s );
 An explicit handle of type handle_t is specified. The parameter H is the binding handle for the procedure. 
void proc3([in] short s,           [in] handle_t H );
 The first parameter is not a handle. In default mode, the leftmost handle parameter, H, is the binding handle. In /osf mode, implicit binding is used. An error is reported because the second parameter is expected to be transmissible, and handle_t cannot be transmitted. 
typedef [handle] short * MY_HDL;void proc1([in] short s,           [in] MY_HDL H );
 The first parameter is not a handle. In default mode, the leftmost handle parameter, H, is the binding handle. The stubs call the user-supplied routines MY_HDL_bind and MY_HDL_unbind. In/osf mode, implicit binding is used. The programmer-defined handle parameter H is treated as transmissible data. 
Typedef [handle] short * MY_HDL;void proc1([in] MY_HDL H,            [in] MY_HDL p );
 The first parameter is a binding handle. The parameter H is the binding-handle parameter. The second programmer-defined handle parameter is treated as transmissible data. 
Typedef [context_handle] void * CTXT_HDL;void proc1([in] short s,           [in] long l,           [in] CTXT_HDL H ,           [in] char c);
 The binding handle is a context handle. The parameter H is the binding handle.