handle

typedef [handle] typename;
handle_t __RPC_USER typename_bind (typename);
void __RPC_USER typename_unbind (typename, handle_t);

typename

Specifies the name of the user-defined binding-handle type.

Examples

typedef [handle] struct { 

    char machine[8];

    char nmpipe[256];

 } h_service;

handle_t __RPC_USER h_service_bind(h_service);

void __RPC_USER h_service_unbind(h_service, handle_t);

Remarks

The handle attribute specifies a user-defined or  customized  handle type. User-defined handles permit developers to design handles that are meaningful to the application.

A user-defined handle can only be defined in a type declaration, not in a function declarator.

A parameter of a type defined by the handle attribute is used to determine the binding for the call and is transmitted to the called procedure.

The user must provide binding and unbinding routines to convert between primitive and user-defined handle types. Given a user-defined handle of type typename, the user must supply the routines typename_bind and typename_unbind. For example, if the user-defined handle type is named MYHANDLE, the routines are named MYHANDLE_bind and MYHANDLE_unbind.

If successful, the typename_bind routine should return a valid primitive binding handle. If unsuccessful, the routine should return a NULL. If the routine returns NULL, the typename_unbind routine will not be called. If the binding routine returns an invalid binding handle different from NULL, the stub behavior is undefined.

When the remote procedure has a user-defined handle as a parameter or as an implicit handle, the client stubs call the binding routine before calling the remote procedure. The client stubs call the unbinding routine after the remote call.

In DCE IDL, a parameter with the handle attribute must appear as the first parameter in the remote procedure argument list. Subsequent parameters, including other handle attributes, are treated as ordinary parameters. Microsoft supports an extension to DCE IDL that allows the user-defined handle parameter to appear in positions other than the first parameter.

See Also