Функция CoInitialize (objbase.h)

Статья
08/25/2023

Инициализирует библиотеку COM в текущем потоке и определяет модель параллелизма как однопотоковый объект (STA).

Новые приложения должны вызывать CoInitializeEx вместо CoInitialize.

Если вы хотите использовать среда выполнения Windows, необходимо вызвать RoInitialize или Windows::Foundation::Initialize.

Синтаксис

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

Параметры

[in, optional] pvReserved

Этот параметр зарезервирован и должен иметь значение NULL.

Возвращаемое значение

Эта функция может возвращать стандартные возвращаемые значения E_INVALIDARG, E_OUTOFMEMORY и E_UNEXPECTED, а также следующие значения.

Код возврата	Описание
S_OK	Библиотека COM успешно инициализирована в этом потоке.
S_FALSE	Библиотека COM уже инициализирована в этом потоке.
RPC_E_CHANGED_MODE	При предыдущем вызове CoInitializeEx модель параллелизма для этого потока была указана как многопоточный объект (MTA). Это также может означать, что произошла смена квартиры с нейтральным потоком на однопотоковый.

Необходимо инициализировать библиотеку COM в потоке перед вызовом любой из функций библиотеки, кроме CoGetMalloc, чтобы получить указатель на стандартный распределитель и функции выделения памяти.

После установки модели параллелизма для потока ее нельзя изменить. Вызов CoInitialize в квартире, которая ранее была инициализирована как многопоточная, завершится ошибкой и возвратит RPC_E_CHANGED_MODE.

CoInitializeEx предоставляет те же функции, что и CoInitialize , а также параметр для явного указания модели параллелизма потока. CoInitialize вызывает CoInitializeEx и задает модель параллелизма как однопотоковый объект. Приложения, разработанные сегодня, должны вызывать CoInitializeEx , а не CoInitialize.

Как правило, библиотека COM инициализируется в потоке только один раз. Последующие вызовы CoInitialize или CoInitializeEx в том же потоке будут успешными, если они не будут пытаться изменить модель параллелизма, но будут возвращать S_FALSE. Чтобы корректно закрыть библиотеку COM, каждый успешный вызов CoInitialize или CoInitializeEx, включая те, которые возвращают S_FALSE, должен быть сбалансирован соответствующим вызовом CoUninitialize. Однако первый поток в приложении, вызывающий CoInitialize с 0 (или CoInitializeEx с COINIT_APARTMENTTHREADED), должен быть последним потоком, вызывающим CoUninitialize. В противном случае последующие вызовы CoInitialize в STA завершатся ошибкой, и приложение не будет работать.

Так как невозможно управлять порядком загрузки или выгрузки внутрипроцессных серверов, не вызывайте CoInitialize, CoInitializeEx или CoUninitialize из функции DllMain .

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	objbase.h
Библиотека	Ole32.lib
DLL	Ole32.dll
Набор API	ext-ms-win-com-sta-l1-1-0 (появилось в Windows 10 версии 10.0.20166)

См. также раздел

CoInitializeEx