Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function initializes the Component Object Model (COM) for use by the current thread. Applications are required to use CoInitializeExbefore 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 CoInitializeExbefore calling any other COM library function except CoGetMallocfunction and other memory allocation calls, such as CoTaskMemAlloc, CoTaskMemFree, CoTaskMemRealloc, and the IMallocmethods on the task allocation supplied by CoGetMalloc.

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

CoInitializeExmust be called at least once, and is usually called only once, for each thread that uses the COM library. Multiple calls to CoInitializeExby 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 dwCoInitparameter, 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 PeekMessageor SendMessageis 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.

CoInitializeExprovides the same functionality as CoInitializeand also provides a parameter to explicitly specify the thread's concurrency model. The current implementation of CoInitializecalls CoInitializeExand specifies the concurrency model as single-thread apartment. Applications developed today should call CoInitializeExrather than CoInitialize.

Because OLE technologies are not thread-safe, the OleInitializefunction calls CoInitializeExwith 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 CoUninitializefrom the DllMainfunction.

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

Requirements

Header objbase.h
Library ole32.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also