Düzenle

Aracılığıyla paylaş

CoInitialize function (objbase.h)

  • Makale

Initializes the COM library on the current thread and identifies the concurrency model as single-thread apartment (STA).

New applications should call CoInitializeEx instead of CoInitialize.

If you want to use the Windows Runtime, you must call RoInitialize or Windows::Foundation::Initialize instead.

Syntax

HRESULT CoInitialize(
  [in, optional] LPVOID pvReserved
);

Parameters

[in, optional] pvReserved

This parameter is reserved and must be NULL.

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.
S_FALSE
 The COM library is already initialized on this thread.
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.

Remarks

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.

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.

CoInitializeEx provides the same functionality as CoInitialize and also provides a parameter to explicitly specify the thread's concurrency model. CoInitialize calls CoInitializeEx and specifies the concurrency model as single-thread apartment. Applications developed today should call CoInitializeEx rather than CoInitialize.

Typically, the COM library is initialized on a thread only once. Subsequent calls to CoInitialize or CoInitializeEx on 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 CoInitialize or 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 with 0 (or CoInitializeEx with COINIT_APARTMENTTHREADED) must be the last thread to call CoUninitialize. Otherwise, subsequent calls to CoInitialize on 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, do not call CoInitialize, CoInitializeEx, or CoUninitialize 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 objbase.h
Library Ole32.lib
DLL Ole32.dll
API set ext-ms-win-com-sta-l1-1-0 (introduced in Windows 10, version 10.0.20166)

See also

CoInitializeEx