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 |
|---|---|
|
The COM library is already initialized on this apartment. |
|
The versions of COMPOBJ.DLL and OLE2.DLL on your machine are incompatible with each other. |
|
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
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) |