CoCreateFreeThreadedMarshaler

Creates an aggregatable object capable of context-dependent marshaling.

HRESULT CoCreateFreeThreadedMarshaler(

LPUNKNOWN punkOuter,

// Pointer to object aggregating the marshaler object

LPUNKNOWN * ppunkMarshaler

// Indirect pointer to the marshaler object

);

Parameters

punkOuter: [in] Pointer to the aggregating object's controlling IUnknown.
ppunkMarshaler: [out] Indirect pointer to the aggregatable marshaler's IUnknown.

Return Values

This function supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK: The marshaler was created.

Remarks

The CoCreateFreeThreadedMarshaler function enables an object to efficiently marshal interface pointers between threads in the same process. If your objects do not support interthread marshaling, you have no need to call this function.

The CoCreateFreeThreadedMarshaler function performs the following tasks:

Creates a free-threaded marshaler object.
Aggregates this marshaler to the object specified by the punkOuter parameter. This object is normally the one whose interface pointers are to be marshaled.

The aggregating object's implementation of IMarshal should delegate QueryInterface calls for IID_IMarshal to the IUnknown of the free-threaded marshaler. Upon receiving a call, the free-threaded marshaler performs the following tasks:

Checks the destination context specified by the CoMarshalInterface function's dwDestContext parameter.
If the destination context is MSHCTX_INPROC, copies the interface pointer into the marshaling stream.
If the destination context is any other value, finds or creates an instance of COM's default (standard) marshaler and delegates marshaling to it.

Values for dwDestContext come from the MSHCTX enumeration. MSHCTX_INPROC indicates that the interface pointer is to be marshaled between different threads in the same process. Because both threads have access to the same address space, the client thread can dereference the pointer directly rather than having to direct calls to a proxy. In all other cases, a proxy is required, so CoCreateFreeThreadedMarshaler delegates the marshaling job to COM's default implementation.

LPUNKNOWN punkOuter,	// Pointer to object aggregating the marshaler object
LPUNKNOWN * ppunkMarshaler	// Indirect pointer to the marshaler object
);