During a series of remote procedure calls, the client may need to refer to a context maintained by a specific server instance. Server application code can maintain information it needs for a particular client (such as the state of RPC the client is using) as a context. To provide a client with a means of referring to its context, the client and server pass back and forth an RPC-specific parameter called a context handle. A context handle is a reference (a pointer) to the server instance and the context of a particular client. A context handle ensures that subsequent remote procedure calls from the client can reach the server instance that is maintaining context for the client.
On completing the first procedure in a series, the server passes a context handle to the client. The context handle identifies the context that the server uses for subsequent operations. The client is not supposed to do anything with the context handle; it merely passes it to subsequent calls as needed, and it is used internally by the remote calls. This allows applications to have such things as remote calls that handle file operations much as local calls would; that is, a client application can remotely open a file, get back a handle to it, and then perform various other remote operations on it, passing the context handle as an argument to the calls. A context handle can be used across interfaces (where a single server offers the multiple interfaces), but a context handle belongs only to the client that caused it to be activated.
The server maintains the context for a client until the client calls a remote procedure that terminates use of the context or communications are lost. In the latter case, the server's runtime can invoke a context rundown procedure. This application-specific routine is called by the server stub automatically to reclaim (rundown) the pointed-to resource in the event of a communications break between the server and client. For example, in the case of the remote file pointer just mentioned, the context rundown routine would simply close the file.
As usual with RPC, you need to apply indirection operators in a variety of ways to maintain the correct [in] and [out] semantics. Typical declarations for a context handle are as follows. In the .idl file, declare a named type such as
typedef [context_handle] void* my_handle_t;
A manager routine that returns a context handle as an out parameter declares it as
my_handle_t *h;
The routine then sets the value of the handle as follows:
*h = &context_data;
A routine that refers to a context handle as an in parameter declares it as
my_handle_t h;
and dereferences the handle as follows:
context_data = (my_handle_t*)h;
For the in,out case, the routine uses the same declaration as in the out case, and dereferences the handle as follows:
context_data = (my_handle_t*)*h;
The following extensive example shows a simple use of context handles. In the sample code, the client requests a unit of storage from the server, using the store_open( ) call, and receives a handle to the allocated storage. The store_read( ), store_write( ), and store_set_ptr( ) routines allow the client to read from and write to specific locations in the allocated storage. The store_close( ) routine releases the server resources.
More:
Context Handles in the Interface
Context Handles in a Server Manager
Binding and Security Information