CoCreateFreeThreadedMarshaler function (combaseapi.h)
Creates an aggregatable object capable of context-dependent marshaling.
HRESULT CoCreateFreeThreadedMarshaler( [in] LPUNKNOWN punkOuter, [out] LPUNKNOWN *ppunkMarshal );
A pointer to the aggregating object's controlling IUnknown.
Address of the pointer variable that receives the interface pointer to the aggregatable marshaler.
This function can return the standard return value E_OUTOFMEMORY, as well as the following value.
||The marshaler was created.|
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. It is intended for use by free-threaded DLL servers that must be accessed directly by all threads in a process, even those threads associated with single-threaded apartments. It custom-marshals the real memory pointer over into other apartments as a bogus "proxy" and thereby gives direct access to all callers, even if they are not free-threaded.
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.
- 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.
Great care should be exercised in using the CoCreateFreeThreadedMarshaler function. This is because the performance of objects which aggregate the free-threaded marshaler is obtained through a calculated violation of the rules of COM, with the ever-present risk of undefined behavior unless the object operates within certain restrictions. The most important restrictions are:
- A free-threaded marshaler object cannot hold direct pointers to interfaces on an object that does not aggregate the free-threaded marshaler as part of its state. If the object were to use direct references to ordinary single-threaded aggregate objects, it may break their single threaded property. If the object were to use direct references to ordinary multithreaded aggregate objects, these objects can behave in ways that show no sensitivity to the needs of direct single-threaded aggregate clients. For example, these objects can spin new threads and pass parameters to the threads that are references to ordinary single-threaded aggregate objects.
- A free-threaded marshaler object cannot hold references to proxies to objects in other apartments. Proxies are sensitive to the threading model and can return RPC_E_WRONG_THREAD if called by the wrong client.
|Minimum supported client||Windows 2000 Professional [desktop apps | UWP apps]|
|Minimum supported server||Windows 2000 Server [desktop apps | UWP apps]|
|Header||combaseapi.h (include Objbase.h)|