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

Статья
02/28/2024

Создает и инициализирует по умолчанию один объект класса , связанный с указанным ИДЕНТИФИКАТОРом CLSID.

Вызовите CoCreateInstance , если требуется создать только один объект в локальной системе. Чтобы создать один объект в удаленной системе, вызовите функцию CoCreateInstanceEx . Чтобы создать несколько объектов на основе одного идентификатора CLSID, вызовите функцию CoGetClassObject .

Синтаксис

HRESULT CoCreateInstance(
  [in]  REFCLSID  rclsid,
  [in]  LPUNKNOWN pUnkOuter,
  [in]  DWORD     dwClsContext,
  [in]  REFIID    riid,
  [out] LPVOID    *ppv
);

Параметры

[in] rclsid

ИДЕНТИФИКАТОР CLSID, связанный с данными и кодом, которые будут использоваться для создания объекта .

[in] pUnkOuter

Значение NULL означает, что объект не создается как часть статистического выражения. Если значение не равно NULL, указатель на интерфейс IUnknown объекта агрегата (управляющий IUnknown).

[in] dwClsContext

Контекст, в котором будет выполняться код, который управляет вновь созданным объектом. Значения взяты из перечисления CLSCTX.

[in] riid

Ссылка на идентификатор интерфейса, используемого для взаимодействия с объектом .

[out] ppv

Адрес переменной указателя, получающей указатель интерфейса, запрошенный в riid. После успешного возврата *ppv содержит запрошенный указатель интерфейса. При сбое *ppv содержит ЗНАЧЕНИЕ NULL.

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

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

Код возврата	Описание
S_OK	Экземпляр указанного класса объектов успешно создан.
REGDB_E_CLASSNOTREG	Указанный класс не зарегистрирован в базе данных регистрации. Также может указывать на то, что тип сервера, запрошенный в перечислении CLSCTX , не зарегистрирован или значения для типов серверов в реестре повреждены.
CLASS_E_NOAGGREGATION	Этот класс не может быть создан как часть статистического выражения.
E_NOINTERFACE	Указанный класс не реализует запрошенный интерфейс, или управляющий IUnknown не предоставляет запрошенный интерфейс.
E_POINTER	Параметр ppv имеет значение NULL.

Функция CoCreateInstance предоставляет удобный ярлык, подключаясь к объекту класса, связанному с указанным ИДЕНТИФИКАТОРом CLSID, создавая инициализированный экземпляр по умолчанию и освобождая объект класса. Таким образом, он инкапсулирует следующие функции:

CoGetClassObject(rclsid, dwClsContext, NULL, IID_IClassFactory, &pCF); 
hresult = pCF->CreateInstance(pUnkOuter, riid, ppvObj);
pCF->Release();

CoCreateInstance удобно использовать, если необходимо создать только один экземпляр объекта на локальном компьютере. Если вы создаете экземпляр на удаленном компьютере, вызовите CoCreateInstanceEx. При создании нескольких экземпляров эффективнее получить указатель на интерфейс IClassFactory объекта класса и использовать его методы по мере необходимости. В последнем случае следует использовать функцию CoGetClassObject .

В перечислении CLSCTX можно указать тип сервера, используемого для управления объектом . Константы могут быть CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER, CLSCTX_REMOTE_SERVER или любое сочетание этих значений. Константная CLSCTX_ALL определяется как сочетание всех четырех. Дополнительные сведения об использовании одной или комбинации этих констант см. в разделе CLSCTX.

Приложения UWP

Несмотря на отсутствие ограничений, которые clSID может передавать приложение UWP в CoCreateInstance, многие объекты завершатся сбоем с E_ACCESSDENIED по соображениям безопасности, особенно если они не выполняются в процессе. Кроме того, даже если вы сможете успешно создать объект, он может завершиться ошибкой позже из-за ограничений безопасности UWP, различий в модели приложений и т. д. В частности, фоновые задачи должны ограничивать объекты, с которыми они взаимодействуют, чтобы избежать зависаний или других осложнений из-за подключения к режиму автономного взаимодействия.

Примеры

// Create WIC factory
hr = CoCreateInstance(
    CLSID_WICImagingFactory,
    NULL,
    CLSCTX_INPROC_SERVER,
    IID_PPV_ARGS(&m_pIWICFactory)
    );

Требования

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