Функция 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.

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

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

Комментарии

Функция 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)
    );

Требования

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

CoCreateInstanceEx

CoGetClassObject

IClassFactory::CreateInstance

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