CoInitializeEx function

Initializes the COM library for use by the calling thread, sets the thread's concurrency model, and creates a new apartment for the thread if one is required.

You should call Windows::Foundation::Initialize to initialize the thread instead of CoInitializeEx if you want to use the Windows Runtime APIs or if you want to use both COM and Windows Runtime components. Windows::Foundation::Initialize is sufficient to use for COM components.

CoInitializeEx是 Windows提供的API函数，为当前线程初始化COM库并设置并发模式 。应用程序调用com库中的函数（除CoGetMalloc和内存分配函数）之前必须初始化com库。

Syntax

C++

HRESULT CoInitializeEx(
  _In_opt_ LPVOID pvReserved,
  _In_     DWORD  dwCoInit
);

Parameters

pvReserved [in, optional]

This parameter is reserved and must be NULL.

dwCoInit [in]

The concurrency model and initialization options for the thread. Values for this parameter are taken from the COINIT enumeration. Any combination of values from COINIT can be used, except that the COINIT_APARTMENTTHREADED and COINIT_MULTITHREADED flags cannot both be set. The default is COINIT_MULTITHREADED.

dwCoInit：线程的并发模型和初始化选项，这个参数的值是来自COINIT枚举，COINIT枚举值可以任意组合，除了COINIT_APARTMENTTHREADED和COINIT_MULTITHREADED不能同时组合，默认值为COINIT_MULTITHREADED。

Return value

This function can return the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following values.

Return code	Description
S_OK	The COM library was initialized successfully on this thread.  COM库线程初始化成功
S_FALSE	The COM library is already initialized on this thread.  COM库已经初始化
RPC_E_CHANGED_MODE	A previous call to CoInitializeEx specified the concurrency model for this thread as multithread apartment (MTA). This could also indicate that a change from neutral-threaded apartment to single-threaded apartment has occurred. COM库已经被初始化且传入参数设置的并发模式和本次不同。

 

Remarks

CoInitializeEx must 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 CoInitialize or CoInitializeEx, including any call that returns S_FALSE, must be balanced by a corresponding call to CoUninitialize.

You need to initialize the COM library on a thread before you call any of the library functions except CoGetMalloc, to get a pointer to the standard allocator, and the memory allocation functions. Otherwise, the COM function will return CO_E_NOTINITIALIZED.

After the concurrency model for a thread is set, it cannot be changed. A call to CoInitialize on an apartment that was previously initialized as multithreaded will fail and return RPC_E_CHANGED_MODE.

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 PeekMessage or SendMessage function 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 synchronization primitives such as critical sections, semaphores, or mutexes to help protect the object's data. When an object that is configured to run in the neutral threaded apartment (NTA) is called by a thread that is in either an STA or the MTA, that thread transfers to the NTA. If this thread subsequently calls CoInitializeEx, the call fails and returns 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.

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

Requirements

Minimum supported client	Windows 2000 Professional [desktop apps | Windows Store apps]
Minimum supported server	Windows 2000 Server [desktop apps | Windows Store apps]
Minimum supported phone	Windows Phone 8
Header	Objbase.h
Library	Ole32.lib
DLL	Ole32.dll