Функция CoGetClassObject (combaseapi.h)
Предоставляет указатель на интерфейс объекта класса, связанного с указанным идентификатором 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 содержит запрошенный указатель интерфейса.
Возвращаемое значение
Эта функция может возвращать следующие значения.
Код возврата | Описание |
---|---|
|
Расположение и подключение к указанному объекту класса выполнено успешно. |
|
CLSID не зарегистрирован должным образом. Эта ошибка также может указывать на то, что значение, указанное в dwClsContext , отсутствует в реестре. |
|
Объект, на который указывает ppv , не поддерживает интерфейс, идентифицируемый riid, или операцию QueryInterface в объекте класса, возвращенном E_NOINTERFACE. |
|
Произошла ошибка при чтении базы данных регистрации. |
|
Не найдена внутрипроцессная библиотека DLL или библиотека DLL обработчика (в зависимости от контекста). |
|
Исполняемый файл (.exe) не найден (только CLSCTX_LOCAL_SERVER). |
|
При загрузке произошел общий сбой доступа. |
|
В исполняемом образе возникает ошибка. |
|
Исполняемый файл был запущен, но он не зарегистрировал объект класса (и он мог завершить работу). |
Комментарии
Объект класса в OLE — это промежуточный объект, поддерживающий интерфейс, который разрешает операции, общие для группы объектов. Объекты в этой группе являются экземплярами, производными от одного определения объекта, представленного одним идентификатором CLSID. Как правило, интерфейсом, реализованным в объекте класса, является IClassFactory, с помощью которого можно создавать экземпляры объектов заданного определения (класса).
Вызов CoGetClassObject создает, инициализирует и предоставляет вызывающей объекту доступ (через указатель на интерфейс, указанный параметром riid ) к объекту класса. Объект класса связан с идентификатором CLSID, указанным в параметре rclsid . Сведения о том, как система находит связанный код и данные на компьютере, прозрачны для вызывающего объекта, как и динамическая загрузка любого кода, который еще не загружен.
Если контекст класса CLSCTX_REMOTE_SERVER, указывающий на необходимость удаленной активации, структура COSERVERINFO , указанная в параметре pServerInfo , позволяет указать компьютер, на котором расположен сервер. Сведения об алгоритме, используемом для поиска удаленного сервера, когда pServerInfo имеет значение NULL, см. в перечислении CLSCTX .
ClSID для класса можно найти в двух местах:
- Реестр содержит связь между идентификаторами CLSID и суффиксами файлов, а также между идентификаторами CLSID и сигнатурами файлов для определения класса объекта.
- При сохранении объекта в постоянное хранилище его ИДЕНТИФИКАТОР CLSID сохраняется вместе с его данными.
Параметр 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 |