Функция CoInitializeEx (combaseapi.h)

Статья
08/22/2023

Инициализирует библиотеку COM для использования вызывающим потоком, задает модель параллелизма потока и при необходимости создает новое подразделение для потока.

Следует вызвать Windows::Foundation::Initialize для инициализации потока вместо CoInitializeEx, если вы хотите использовать API среда выполнения Windows или если вы хотите использовать как COM, так и среда выполнения Windows компоненты. Windows::Foundation::Initialize достаточно для использования для com-компонентов.

Синтаксис

HRESULT CoInitializeEx(
  [in, optional] LPVOID pvReserved,
  [in]           DWORD  dwCoInit
);

Параметры

[in, optional] pvReserved

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

[in] dwCoInit

Модель параллелизма и параметры инициализации для потока. Значения для этого параметра взяты из перечисления COINIT . Можно использовать любое сочетание значений из COINIT , за исключением того, что нельзя одновременно задать флаги COINIT_APARTMENTTHREADED и COINIT_MULTITHREADED. Значение по умолчанию — COINIT_MULTITHREADED.

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

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

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

CoInitializeEx должен вызываться по крайней мере один раз и обычно вызывается только один раз для каждого потока, использующего библиотеку COM. Несколько вызовов CoInitializeEx одним потоком разрешены, если они передают один и тот же флаг параллелизма, но последующие допустимые вызовы возвращают S_FALSE. Чтобы корректно закрыть библиотеку COM в потоке, каждый успешный вызов CoInitialize или CoInitializeEx, включая любой вызов, возвращающий S_FALSE, должен быть сбалансирован соответствующим вызовом CoUninitialize.

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

В противном случае функция COM вернет CO_E_NOTINITIALIZED.

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

Объекты, созданные в однопотоковом объекте (STA), получают вызовы методов только из потока своего подразделения, поэтому вызовы сериализуются и поступают только в пределах очереди сообщений (при вызове функции PeekMessage или SendMessage ).

Объекты, созданные в потоке COM в многопоточности (MTA), должны иметь возможность принимать вызовы методов из других потоков в любое время. Обычно в коде многопоточного объекта реализуется определенная форма управления параллелизмом с помощью примитивов синхронизации, таких как критические разделы, семафоры или мьютексы, для защиты данных объекта.

Когда объект, настроенный для выполнения в нейтральном потоке (NTA), вызывается потоком, который находится в STA или MTA, этот поток передается в NTA. Если этот поток впоследствии вызывает CoInitializeEx, вызов завершается ошибкой и возвращает RPC_E_CHANGED_MODE.

Так как технологии OLE не являются потокобезопасными, функция OleInitialize вызывает CoInitializeEx с флагом COINIT_APARTMENTTHREADED. В результате подразделение, инициализируемое для параллелизма многопоточных объектов, не может использовать функции, включенные OleInitialize.

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Профессиональная [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows 2000 Server [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	combaseapi.h (включая Objbase.h)
Библиотека	Ole32.lib
DLL	Ole32.dll

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

Процессы, потоки и квартиры