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

Статья
11/12/2024

Инициализирует 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 указал несовместимую модель параллелизма для этого потока. Это также может указывать на то, что произошло изменение с нейтральной потоковой квартиры на однопотоковую квартиру.

Замечания

CoInitializeEx должен вызываться по крайней мере один раз и обычно вызывается только один раз для каждого потока, использующего библиотеку COM. Несколько вызовов CoInitializeEx одним потоком разрешены, пока они передают один и тот же флаг параллелизма, но последующие допустимые вызовы возвращают S_FALSE. Если флаг параллелизма не соответствует, вызов завершается ошибкой и возвращает RPC_E_CHANGED_MODE. (В целях этого правила вызов CoInitialize эквивалентен вызову CoInitializeEx с флагом COINIT_APARTMENTTHREADED.) Чтобы неинициализировать библиотеку COM в потоке, каждый успешный вызов CoInitialize или CoInitializeEx, включая любой вызов, возвращающий S_FALSE, должен быть сбалансирован соответствующим вызовом для CoUninitialize. После неинициализации COM в потоке вы можете повторно инициализировать его в любом режиме, при условии указанных выше ограничений.

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

Объекты, созданные в однопоточной квартире (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]
целевая платформа	Виндоус
заголовка	combaseapi.h (include Objbase.h)
библиотеки	Ole32.lib
DLL	Ole32.dll

См. также

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

Поделиться через