OSF DCE Application Development Guide--Core Components

Interface Definition Language
A customized handle can be coded either in a parameter list as an explicit handle or in an
interface header as an implicit handle.
17.14.9 Context Handles
Manager code often maintains state information for a client. A handle to this state
information is passed to the client in an output parameter or as an operation result. The
client passes the unchanged handle-to-the-state information as an input or input/output
parameter of a subsequent manager operation that the client calls to manipulate that data
structure. This handle-to-the-state information is called a context handle. A context
handle is implemented as an untyped pointer or a pointer to a structure by tag name.
The manager causes the untyped pointer or the structure pointer to point to the state
information it will need the next time the client asks the manager to manipulate the
context. For the client, the context handle is an opaque pointer (idl_void_p_t or an
opaque structure tag). The client receives or supplies the context handle by means of the
parameter list but does not perform any transformations on it.
The RPC runtime maintains the context handle, providing an association between the
client and the address space running the manager and the state information within that
address space.
If a manager supports multiple interfaces, and a client obtains a context handle by
performing an operation from one of these interfaces, the client can then supply the
context handle to an operation from another of these interfaces.
A context handle can only be exchanged between the server process that created it and
the client process for which it was created. No other client except the one that obtained
the context handle can use it without causing an application error.
17.14.9.1 The context_handle Attribute
Specify a context handle by one of the following methods:
• Use the context_handle attribute on a parameter of type void *.
• Use the context_handle attribute on a type that is defined as void *.
• Use the context_handle attribute on a type that is defined as a pointer to a structure
by tag name.
For example, in the IDL file, you can define a context handle within a type declaration as
follows:
typedef [context_handle] void * my_context;
or within a parameter declaration as follows:
[in, context_handle] void * my_context;
124245 Tandem Computers Incorporated 17− 59