CoInitializeEx (Compact 2013)

3/26/2014

This function initializes the Component Object Model (COM) for use by the current thread. Applications are required to use CoInitializeEx before they make any other COM library calls except for memory allocation functions.

Syntax

HRESULT CoInitializeEx(
  LPVOID pvReserved, 
  DWORD dwCoInit
); 

Parameters

• pvReserved
  [in] Reserved; set to NULL.

• dwCoInit
  [in] Specifies the concurrency model and initialization options for the thread. This parameter can be set to COINIT_MULTITHREADED or COINIT_APARTMENTTHREADED.

Return Value

S_OK indicates that the COM library was initialized successfully. S_FALSE indicates that the COM library is already initialized. The standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED are also supported.

Remarks

A thread must call CoInitializeEx before calling any other COM library function except CoGetMalloc function and other memory allocation calls, such as CoTaskMemAlloc, CoTaskMemFree, CoTaskMemRealloc, and the IMalloc methods on the task allocation supplied by CoGetMalloc.

Once the concurrency model for a thread is set, it cannot be changed. A call to CoInitializeEx on a thread that was previously initialized with a different concurrency model will fail and return RPC_E_CHANGED_MODE.

CoInitializeEx must be called at least once, and is usually called only once, for each thread that uses the COM library. Multiple calls to CoInitializeEx by the same thread are allowed as long as they pass the same concurrency flag, but subsequent valid calls return S_FALSE. To close the COM library gracefully on a thread, each successful call to CoInitializeEx, including any call that returns S_FALSE, must be balanced by a corresponding call to CoUninitialize.

If neither concurrency model is specified by the dwCoInit parameter, the default is COINIT_MULTITHREADED.

Objects created in a single-threaded apartment (STA) receive method calls only from their apartment's thread, so calls are serialized and arrive only at message-queue boundaries when the Microsoft Win32 function PeekMessage or SendMessage is called.

Objects created on a COM thread in a multithread apartment (MTA) must be able to receive method calls from other threads at any time. You would typically implement some form of concurrency control in a multithreaded object's code using Win32 synchronization primitives such as critical sections, semaphores, or mutexes to help protect the object's data.

CoInitializeEx provides the same functionality as CoInitialize and also provides a parameter to explicitly specify the thread's concurrency model. The current implementation of CoInitialize calls CoInitializeEx and specifies the concurrency model as single-thread apartment. Applications developed today should call CoInitializeEx rather than CoInitialize.

Because OLE technologies are not thread-safe, the OleInitialize function calls CoInitializeEx with the COINIT_APARTMENTTHREADED flag. As a result, an apartment that is initialized for multithreaded object concurrency cannot use the features enabled by OleInitialize.

Because there is no way to control the order in which in-process servers are loaded or unloaded, it is not safe to call CoInitialize, CoInitializeEx, or CoUninitialize from the DllMain function.

To determine whether the platform supports this function, see Determining Supported COM APIs.

Requirements

Header	objbase.h
Library	ole32.lib

See Also

Reference

COM Functions
CoGetMalloc
CoTaskMemAlloc
CoTaskMemFree
CoTaskMemRealloc
CoUninitialize