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

Статья
08/22/2023

Предоставляет указатель на интерфейс объекта класса, связанного с указанным идентификатором CLSID. CoGetClassObject находит и при необходимости динамически загружает исполняемый код, необходимый для этого.

Вызовите Метод CoGetClassObject напрямую, чтобы создать несколько объектов с помощью объекта класса, для которого в системном реестре есть идентификатор CLSID. Вы также можете получить объект класса с определенного удаленного компьютера. Большинство объектов класса реализуют интерфейс IClassFactory . Затем вызовите CreateInstance , чтобы создать неинициализированный объект. Однако не всегда необходимо пройти через этот процесс. Чтобы создать один объект, вызовите функцию CoCreateInstanceEx , которая позволяет создать экземпляр на удаленном компьютере. Это заменяет функцию CoCreateInstance , которая по-прежнему может использоваться для создания экземпляра на локальном компьютере. Обе функции инкапсулируют подключение к объекту класса, создание экземпляра и освобождение объекта класса. Две другие функции, CoGetInstanceFromFile и CoGetInstanceFromIStorage, обеспечивают как создание экземпляра в удаленной системе, так и активацию объекта. Существует множество функций и методов интерфейса, целью которых является создание объектов одного типа и предоставление указателя на интерфейс этого объекта.

Синтаксис

HRESULT CoGetClassObject(
  [in]           REFCLSID rclsid,
  [in]           DWORD    dwClsContext,
  [in, optional] LPVOID   pvReserved,
  [in]           REFIID   riid,
  [out]          LPVOID   *ppv
);

Параметры

[in] rclsid

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

[in] dwClsContext

Контекст, в котором выполняется исполняемый код. Чтобы включить удаленную активацию, включите CLSCTX_REMOTE_SERVER. Дополнительные сведения о значениях контекста и их использовании см. в разделе Перечисление CLSCTX .

[in, optional] pvReserved

Указатель на компьютер, на котором создается экземпляр объекта класса. Если этот параметр имеет значение NULL, экземпляр объекта класса создается на текущем компьютере или на компьютере, указанном в ключе RemoteServerName класса, в соответствии с интерпретацией параметра dwClsCtx . См . раздел COSERVERINFO.

[in] riid

Ссылка на идентификатор интерфейса, который будет предоставлен в ppv при успешном возврате. Этот интерфейс будет использоваться для взаимодействия с объектом класса . Обычно это значение IID_IClassFactory, хотя разрешены другие значения, такие как IID_IClassFactory2, поддерживающие форму лицензирования. Все идентификаторы IID интерфейса, определяемые OLE, определяются в файлах заголовков OLE как IID_interfacename, где interfacename — это имя интерфейса.

[out] ppv

Адрес переменной указателя, которая получает указатель интерфейса, запрошенный в riid. После успешного возврата *ppv содержит запрошенный указатель интерфейса.

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

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

Код возврата	Описание
S_OK	Расположение и подключение к указанному объекту класса выполнено успешно.
REGDB_E_CLASSNOTREG	CLSID не зарегистрирован должным образом. Эта ошибка также может указывать на то, что значение, указанное в dwClsContext , отсутствует в реестре.
E_NOINTERFACE	Объект, на который указывает ppv , не поддерживает интерфейс, идентифицируемый riid, или операцию QueryInterface в объекте класса, возвращенном E_NOINTERFACE.
REGDB_E_READREGDB	Произошла ошибка при чтении базы данных регистрации.
CO_E_DLLNOTFOUND	Не найдена внутрипроцессная библиотека DLL или библиотека DLL обработчика (в зависимости от контекста).
CO_E_APPNOTFOUND	Исполняемый файл (.exe) не найден (только CLSCTX_LOCAL_SERVER).
E_ACCESSDENIED	При загрузке произошел общий сбой доступа.
CO_E_ERRORINDLL	В исполняемом образе возникает ошибка.
CO_E_APPDIDNTREG	Исполняемый файл был запущен, но он не зарегистрировал объект класса (и он мог завершить работу).

Объект класса в OLE — это промежуточный объект, поддерживающий интерфейс, который разрешает операции, общие для группы объектов. Объекты в этой группе являются экземплярами, производными от одного определения объекта, представленного одним идентификатором CLSID. Как правило, интерфейсом, реализованным в объекте класса, является IClassFactory, с помощью которого можно создавать экземпляры объектов заданного определения (класса).

Вызов CoGetClassObject создает, инициализирует и предоставляет вызывающей объекту доступ (через указатель на интерфейс, указанный параметром riid ) к объекту класса. Объект класса связан с идентификатором CLSID, указанным в параметре rclsid . Сведения о том, как система находит связанный код и данные на компьютере, прозрачны для вызывающего объекта, как и динамическая загрузка любого кода, который еще не загружен.

Если контекст класса CLSCTX_REMOTE_SERVER, указывающий на необходимость удаленной активации, структура COSERVERINFO , указанная в параметре pServerInfo , позволяет указать компьютер, на котором расположен сервер. Сведения об алгоритме, используемом для поиска удаленного сервера, когда pServerInfo имеет значение NULL, см. в перечислении CLSCTX .

ClSID для класса можно найти в двух местах:

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

Для создания и инициализации внедренных или связанных объектов документа OLE не требуется напрямую вызывать CoGetClassObject . Вместо этого вызовите функцию OleCreate или OleCreateXXX . Эти функции инкапсулируют весь процесс создания и инициализации объекта и вызывают, среди прочего, CoGetClassObject.

Параметр riid указывает интерфейс, который клиент будет использовать для взаимодействия с объектом класса. В большинстве случаев это интерфейс IClassFactory. Это обеспечивает доступ к методу CreateInstance , с помощью которого вызывающий объект может затем создать неинициализированный объект типа, указанного в его реализации. Все классы, зарегистрированные в системе с идентификатором CLSID, должны реализовывать IClassFactory.

Однако в редких случаях может потребоваться указать другой интерфейс, определяющий операции, общие для набора объектов. Например, так как OLE реализует моникеры, интерфейс объекта класса — IParseDisplayName, используемый для преобразования отображаемого имени объекта в моникер.

Параметр dwClsContext указывает контекст выполнения, позволяя связать один ИДЕНТИФИКАТОР CLSID с разными фрагментами кода в разных контекстах выполнения. Перечисление CLSCTX указывает доступные флаги контекста. CoGetClassObject консультируется (в соответствии с указанным контекстом) как с реестром, так и с объектами класса, которые в настоящее время зарегистрированы путем вызова функции CoRegisterClassObject .

Чтобы освободить объект класса, используйте метод Release объекта класса. Функция CoRevokeClassObject используется только для удаления CLSID объекта класса из системного реестра.

Требования


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