Edit

context_handle_serialize attribute

  • Article

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

Application Configuration File (ACF)

ACF Attributes

context_handle_noserialize

context_handle

Context Handles

RpcSsDontSerializeContext

Server Context Run-down Routine

Multithreaded Clients and Context Handles

typedef