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


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

Создает и инициализирует по умолчанию один объект класса , связанный с указанным ИДЕНТИФИКАТОРом 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

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

CoCreateInstanceEx

CoGetClassObject

IClassFactory::CreateInstance

Вспомогательные функции создания экземпляра