The handle attribute specifies that the type being declared is a user-defined, nonprimitive handle type, and is to be used in place of the predefined primitive handle type handle_t. The term customized handle is used to denote a nonprimitive handle.
The following example declares a customized handle type filehandle_t, a structure containing the textual representations of a host and a path name:
typedef [handle] struct {
char host[256];
char path[1024];
} filehandle_t;
If the handle parameter is the first parameter in the list then it is a customized handle that is used to determine the binding for the call, and it must have the in attribute or the in,out attributes. A handle parameter that is not the first parameter in the parameter list need not have the in or in,out attributes.
Note that a handle_t parameter that is the first parameter in the list must not have the transmit_as attribute.
To build an application that uses customized handles, you must write custom binding and unbinding routines, and you must link those routines with your application client code. At runtime, each time the client calls an operation that uses a customized handle, the client stub calls the custom binding routine before it sends the remote procedure call request, and the client stub calls the custom unbinding routine after it receives a response.
The following paragraphs specify C prototypes for customized binding and unbinding routines; in these prototypes, CUSTOM is the name of the customized handle type.
The custom binding routine CUSTOM_bind generates a primitive binding handle from a customized handle and returns the primitive binding handle:
handle_t CUSTOM_bind (CUSTOM c-handle)
The custom unbinding routine CUSTOM_unbind takes two inputs, a customized handle and the primitive binding handle that was generated from it, and has no outputs:
void CUSTOM_unbind (
CUSTOM c-handle,
handle_t rpc-handle)
A custom unbinding routine typically frees the primitive binding handle and any unneeded resources associated with the customized handle, but it is not required to do anything.
Because the handle attribute can occur only in a type declaration, a customized handle must have a named type. Because customized handle type names are used to construct custom binding and unbinding routine names, these names cannot exceed 24 characters.
A customized handle can be coded either in a parameter list as an explicit handle or in an interface header as an implicit handle.