handle attribute
The [handle] attribute specifies a user-defined or "customized" handle type.
typedef [handle] typename;
handle_t __RPC_USER typename_bind (typename);
void __RPC_USER typename_unbind (typename, handle_t);
Parameters
-
typename
-
Specifies the name of the user-defined binding-handle type.
Remarks
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.
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);
See also