The context_handle Attribute

· 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;

You can also define a context handle within a type declaration as a forward reference to a structure type by tag, as follows:

typedef [context_handle] struct opaque_struct * opaque_ch_t;

Note that you do not need to define the structure type in the IDL file; it is a forward reference to a structure whose definition can be included into the server code, either from a private .h file or from a server IDL file. As a result, the structure type is opaque to the client. This method of defining a context handle provides type checking and permits the server code to avoid extensive casting when manipulating the context handle.

A structure type in a context handle type definition must be referenced by tag name and not by type name. So, for example, the first of the following declarations is valid, while the second is not:

typedef [context_handle] struct struct_tag * valid_ch_t; / *valid */

typedef [context_handle] struct_type * invalid_ch_t; /* error */

The following example illustrates context handles defined as untyped pointers and as pointers to structures by tag name.

/* A context handle implemented as untyped pointer */

typedef [context_handle] void * void_ch_t;

/* A context handle implemented as a pointer to a structure by tag name */

typedef [context_handle] struct opaque_struct * opaque_ch_t;

/* Operations using both types of context handles */

void ch_oper(

[in] void_ch_t v1,

[in,out] void_ch_t *v2,

[out] void_ch_t *v3,

[in] opaque_ch_t *o2,

[out] opaque_ch_t *o3

);

void_ch_t void_ch_oper ([in] handle_t h);

opaque_ch_t opaque_ch_oper([in] handle_t h);

It is possible to define a structure type in a context handle in the IDL file; for example, the following structure definition

typedef struct struct_tag {long l;} struct_type;

can either precede or follow the definition of valid_ch_t in the example previously shown. However, this practice is not recommended, since it violates the opaqueness of the context handle type.

The type name in a context handle declaration must be no longer than 23 characters.

The first operation on a context creates a context handle that the server procedure passes to the client. The client then passes the unmodified handle back to the server in a subsequent remote call. The called procedure interprets the context handle. For example, to specify a procedure that a client can use to obtain a context handle, you can define the following:

typedef [context_handle] void * my_context;

void op1(

[in]handle_t h,

[out] my_context * this_object);

To specify a procedure that a client can call to make use of a previously obtained context handle, you can define the following:

void op2([in] my_context this_object);

To close a context, and to clean the context on the client side, you can define the following:

[in, out, context_handle] void * my_context;

The resources associated with a context handle are reclaimed when, and only when, the manager changes the value of the in,out context handle parameter from non-NULL to NULL.