Función CoGetClassObject (combaseapi.h)

Artículo
08/22/2023

Proporciona un puntero a una interfaz en un objeto de clase asociado a un CLSID especificado. CoGetClassObject busca y, si es necesario, carga dinámicamente el código ejecutable necesario para hacerlo.

Llame a CoGetClassObject directamente para crear varios objetos a través de un objeto de clase para el que hay un CLSID en el registro del sistema. También puede recuperar un objeto de clase de un equipo remoto específico. La mayoría de los objetos de clase implementan la interfaz IClassFactory . A continuación, llamaría a CreateInstance para crear un objeto no inicializado. Sin embargo, no siempre es necesario pasar por este proceso. Para crear un solo objeto, llame a la función CoCreateInstanceEx , que permite crear una instancia en un equipo remoto. Esto reemplaza la función CoCreateInstance , que todavía se puede usar para crear una instancia en un equipo local. Ambas funciones encapsulan la conexión al objeto de clase, la creación de la instancia y la liberación del objeto de clase. Otras dos funciones, CoGetInstanceFromFile y CoGetInstanceFromIStorage, proporcionan la creación de instancias en un sistema remoto y la activación de objetos. Hay numerosas funciones y métodos de interfaz cuyo propósito es crear objetos de un solo tipo y proporcionar un puntero a una interfaz en ese objeto.

Sintaxis

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

Parámetros

[in] rclsid

CLSID asociado a los datos y el código que usará para crear los objetos.

[in] dwClsContext

Contexto en el que se va a ejecutar el código ejecutable. Para habilitar una activación remota, incluya CLSCTX_REMOTE_SERVER. Para obtener más información sobre los valores de contexto y su uso, vea la enumeración CLSCTX .

[in, optional] pvReserved

Puntero al equipo en el que se va a crear una instancia del objeto de clase. Si este parámetro es NULL, se crea una instancia del objeto de clase en el equipo actual o en el equipo especificado en la clave RemoteServerName de la clase, según la interpretación del parámetro dwClsCtx . Consulte COSERVERINFO.

[in] riid

Referencia al identificador de la interfaz, que se proporcionará en ppv al devolverse correctamente. Esta interfaz se usará para comunicarse con el objeto de clase. Normalmente, este valor es IID_IClassFactory, aunque se permiten otros valores como IID_IClassFactory2 que admiten una forma de licencia. Todos los IID de interfaz definidos por OLE se definen en los archivos de encabezado OLE como IID_interfacename, donde interfacename es el nombre de la interfaz.

[out] ppv

Dirección de la variable de puntero que recibe el puntero de interfaz solicitado en riid. Tras la devolución correcta, *ppv contiene el puntero de interfaz solicitado.

Valor devuelto

Esta función puede devolver los valores siguientes.

Código devuelto	Descripción
S_OK	La ubicación y la conexión con el objeto de clase especificado se han realizado correctamente.
REGDB_E_CLASSNOTREG	El CLSID no está registrado correctamente. Este error también puede indicar que el valor especificado en dwClsContext no está en el Registro.
E_NOINTERFACE	El objeto al que apunta ppv no admite la interfaz identificada por riid o la operación QueryInterface en el objeto de clase devuelto E_NOINTERFACE.
REGDB_E_READREGDB	Error al leer la base de datos de registro.
CO_E_DLLNOTFOUND	No se encontró la DLL en proceso o la DLL del controlador (según el contexto).
CO_E_APPNOTFOUND	No se encontró el ejecutable (.exe) (solo CLSCTX_LOCAL_SERVER).
E_ACCESSDENIED	Se produjo un error de acceso general al cargarse.
CO_E_ERRORINDLL	Hay un error en la imagen ejecutable.
CO_E_APPDIDNTREG	El ejecutable se inició, pero no registró el objeto de clase (y puede que se haya apagado).

Comentarios

Un objeto de clase en OLE es un objeto intermedio que admite una interfaz que permite operaciones comunes a un grupo de objetos. Los objetos de este grupo son instancias derivadas de la misma definición de objeto representada por un único CLSID. Normalmente, la interfaz implementada en un objeto de clase es IClassFactory, a través de la cual se pueden crear instancias de objeto de una definición determinada (clase).

Una llamada a CoGetClassObject crea, inicializa y proporciona al autor de la llamada acceso (a través de un puntero a una interfaz especificada con el parámetro riid ) al objeto de clase. El objeto de clase es el asociado al CLSID que se especifica en el parámetro rclsid . Los detalles de cómo el sistema localiza el código asociado y los datos dentro de un equipo son transparentes para el autor de la llamada, como es la carga dinámica de cualquier código que aún no se haya cargado.

Si el contexto de clase es CLSCTX_REMOTE_SERVER, lo que indica que se requiere la activación remota, la estructura COSERVERINFO proporcionada en el parámetro pServerInfo permite especificar el equipo en el que se encuentra el servidor. Para obtener información sobre el algoritmo utilizado para buscar un servidor remoto cuando pServerInfo es NULL, consulte la enumeración CLSCTX .

Hay dos lugares para buscar un CLSID para una clase:

El registro contiene una asociación entre CLSID y sufijos de archivo, y entre CLSID y firmas de archivo para determinar la clase de un objeto.
Cuando un objeto se guarda en el almacenamiento persistente, su CLSID se almacena con sus datos.

Para crear e inicializar objetos de documento OLE incrustados o vinculados, no es necesario llamar directamente a CoGetClassObject . En su lugar, llame a la función OleCreate o OleCreateXXX . Estas funciones encapsulan todo el proceso de creación de instancias e inicialización del objeto, y llaman a, entre otras funciones, CoGetClassObject.

El parámetro riid especifica la interfaz que usará el cliente para comunicarse con el objeto de clase. En la mayoría de los casos, esta interfaz es IClassFactory. Esto proporciona acceso al método CreateInstance , a través del cual el autor de la llamada puede crear un objeto sin inicializar del tipo especificado en su implementación. Todas las clases registradas en el sistema con un CLSID deben implementar IClassFactory.

Sin embargo, en raras ocasiones, es posible que desee especificar alguna otra interfaz que defina las operaciones comunes a un conjunto de objetos. Por ejemplo, en la forma en que OLE implementa monikers, la interfaz del objeto de clase es IParseDisplayName, que se usa para transformar el nombre para mostrar de un objeto en un moniker.

El parámetro dwClsContext especifica el contexto de ejecución, lo que permite asociar un CLSID a diferentes fragmentos de código en contextos de ejecución diferentes. La enumeración CLSCTX especifica las marcas de contexto disponibles. CoGetClassObject consulta (según corresponda para el contexto indicado) tanto el registro como los objetos de clase que están registrados actualmente mediante una llamada a la función CoRegisterClassObject .

Para liberar un objeto de clase, use el método Release del objeto de clase. La función CoRevokeClassObject solo se usa para quitar el CLSID de un objeto de clase del registro del sistema.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	combaseapi.h (incluya Objbase.h)
Library	Ole32.lib
Archivo DLL	Ole32.dll