CoInitialize

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.

This function initializes the COM library on the current thread and identifies the concurrency model as single-thread apartment (STA). Applications must initialize the COM library before they can call COM library functions other than CoGetMallocand memory allocation functions.

New applications should call CoInitializeExinstead of CoInitialize.

HRESULT CoInitialize(
LPVOID
pvReserved
);

Parameter

pvReserved

[in] Reserved; must be NULL.

Return Values

This function supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The COM library was initialized successfully on this thread.

S_FALSE

The COM library is already initialized on this thread.

RPC_E_CHANGED_MODE

A previous call to CoInitializeExspecified the concurrency model for this thread as multithread apartment (MTA).

Remarks

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

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.

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

Typically, the COM library is initialized on a thread only once. Subsequent calls to CoInitializeor CoInitializeExon the same thread will succeed, as long as they do not attempt to change the concurrency model, but will return S_FALSE. To close the COM library gracefully, each successful call to CoInitializeor CoInitializeEx, including those that return S_FALSE, must be balanced by a corresponding call to CoUninitialize. However, the first thread in the application that calls CoInitialize(0)or CoInitializeEx(COINIT_APARTMENTTHREADED)must be the last thread to call CoUninitialize(). If the call sequence is not in this order, then subsequent calls to CoInitializeon the STA will fail and the application will not work.

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.

Requirements

Runs On	Versions	Defined in	Include	Link to
Windows CE OS	3.0 and later	Objbase.h		Ole232.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.