Initializes the COM library for use by the current apartment and specifies the apartment's concurrency model.
HRESULT CoInitializeEx(
void * pvReserved, //Reserved
DWORD dwCoInit //COINIT value
);
This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:
If neither concurrency model is specified by the dwCoInit parameter, the default is COINIT_APARTMENTTHREADED.
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 protect the object's data.
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 (PeekMessage, SendMessage).
Apartments must call CoInitializeEx or CoInitialize before calling any other COM library functions except CoGetMalloc function and other memory allocation calls (CoTaskMemAlloc, CoTaskMemFree, CoTaskMemReAlloc, and the IMalloc methods on the task allocator supplied by CoGetMalloc).
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.
Typically, CoInitializeEx is called only once by each apartment in the process that uses the COM library. For a multithread apartment, one call is sufficient for all threads in the apartment.
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 library gracefully, each successful call to CoInitialize or CoInitializeEx, including calls that return S_FALSE, must be balanced by a corresponding call to CoUninitialize.
Once the concurrency model for an apartment is set, it cannot be changed. A call to CoInitializeEx on an apartment that was previously initialized with a different concurrency model will fail and return RPC_E_CHANGED_MODE.
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.
Windows CE: The CoInitializeEx function initializes the Component Object Model (COM), including the OLE library, for use by the current thread. The dwCoInit parameter specifies the type of concurrency control required by objects created by this thread. Windows CE supports only the multi-threaded concurrency control. Thus, COINIT_MULTITHREADED is the only option permitted for the dwCoInit parameter.
Compound document applications must call CoInitializeEx before calling any other function in the OLE library.
Windows CE does not support the CoInitialize(NULL) or OleInitialize function. Use CoInitializeEx instead.
Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application. For more information about handling exceptions, see Programming Considerations.
Windows NT: Use version 4.0 or later.
Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Use version 2.0 or later.
Header: Declared in objbase.h.
Import Library: Included as a resource in ole32.dll.
COINIT, CoInitialize, Processes and Threads