context_handle_serialize attribute
The [context_handle_serialize] ACF attribute guarantees that a context handle will always be serialized, regardless of the application's default behavior.
typedef [context_handle_serialize [ , type-acf-attribute-list ] ] context-handle-type;
[context_handle_serialize [, function-acf-attribute-list ] ] function-name( );
function-name(
[context_handle_serialize [ , parameter-acf-attribute-list ] ] param-name );
Parameters
-
type-acf-attribute-list
-
Any other ACF attributes that apply to the type.
-
context-handle-type
-
The identifier that specifies the context handle type, as defined in a typedef declaration. This is the type that receives the [context_handle_serialize] attribute in the IDL file.
-
function-acf-attribute-list
-
Any additional ACF attributes that apply to the function.
-
function-name
-
The name of the function as defined in the IDL file.
-
parameter-acf-attribute-list
-
Any other ACF attributes that apply to the parameter.
-
param-name
-
The name of the parameter as defined in the IDL file.
Remarks
The [context_handle_serialize] attribute identifies a binding handle that maintains context or state information on the server between remote procedure calls. The attribute can appear as an IDL typedef type attribute, as a function return type attribute, or as a parameter attribute.
By default, calls on context handles are serialized, but an application can call RpcSsDontSerializeContext to override this default behavior. Using the [context_handle_serialize] attribute in an ACF file guarantees that calls on this particular context handle will be serialized, even if the calling application has overridden the default serialization. A context rundown routine is optional.
This attribute is available in MIDL version 5.0.
Windows Server 2003 and Windows XP or later: A single interface can accommodate both serialized and nonserialized context handles, enabling one method on an interface to access a context handle exclusively (serialized), while other methods access that context handle in shared mode (nonserialized). These access capabilities are comparable to read/write locking mechanisms; methods using a serialized context handle are exclusive users (writers), whereas methods using a nonserialized context handle are shared users (readers). Methods that destroy or modify the state of a context handle must be serialized. Methods that do not modify the state of a context handle, such as those methods that simply read from a context handle, can be nonserialized. Note that creation methods are implicitly serialized.
Examples
typedef [context_handle_serialize] PCONTEXT_HANDLE_TYPE;
HRESULT RemoteFunc([context_handle_serialize] pCxHandle);
See also