OleInitialize function (ole2.h)

Initializes the COM library on the current apartment, identifies the concurrency model as single-thread apartment (STA), and enables additional functionality described in the Remarks section below. Applications must initialize the COM library before they can call COM library functions other than CoGetMalloc and memory allocation functions.

Syntax

HRESULT OleInitialize(
  [in] LPVOID pvReserved
);

Parameters

[in] pvReserved

This parameter is reserved and must be NULL.

Return value

This function returns S_OK on success. Other possible values include the following.

Return code Description
S_FALSE
The COM library is already initialized on this apartment.
OLE_E_WRONGCOMPOBJ
The versions of COMPOBJ.DLL and OLE2.DLL on your machine are incompatible with each other.
RPC_E_CHANGED_MODE
A previous call to CoInitializeEx specified the concurrency model for this apartment as multithread apartment (MTA). This could also mean that a change from neutral threaded apartment to single threaded apartment occurred.

Remarks

Applications that use the following functionality must call OleInitialize before calling any other function in the COM library:

  • Clipboard
  • Drag and Drop
  • Object linking and embedding (OLE)
  • In-place activation
OleInitialize calls CoInitializeEx internally to initialize the COM library on the current apartment. Because OLE operations are not thread-safe, OleInitialize specifies the concurrency model as single-thread apartment.

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

You need to initialize the COM library on an apartment before you call any of the library functions except CoGetMalloc, to get a pointer to the standard allocator, and the memory allocation functions.

Typically, the COM library is initialized on an apartment only once. Subsequent calls will succeed, as long as they do not attempt to change the concurrency model of the apartment, but will return S_FALSE. To close the COM library gracefully, each successful call to OleInitialize, including those that return S_FALSE, must be balanced by a corresponding call to OleUninitialize.

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

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header ole2.h
Library Ole32.lib
DLL Ole32.dll
API set ext-ms-win-com-ole32-l1-1-0 (introduced in Windows 8)

See also

CoInitializeEx

OleInitialize

OleUninitialize