CoGetClassObject, fonction (combaseapi.h)

Article
08/22/2023

Fournit un pointeur vers une interface sur un objet de classe associé à un CLSID spécifié. CoGetClassObject localise et, si nécessaire, charge dynamiquement le code exécutable requis pour cela.

Appelez directement CoGetClassObject pour créer plusieurs objets via un objet de classe pour lequel il existe un CLSID dans le registre système. Vous pouvez également récupérer un objet de classe à partir d’un ordinateur distant spécifique. La plupart des objets de classe implémentent l’interface IClassFactory . Vous devez ensuite appeler CreateInstance pour créer un objet non initialisé. Toutefois, il n’est pas toujours nécessaire de passer par ce processus. Pour créer un objet unique, appelez la fonction CoCreateInstanceEx, qui vous permet de créer un instance sur un ordinateur distant. Cela remplace la fonction CoCreateInstance, qui peut toujours être utilisée pour créer un instance sur un ordinateur local. Les deux fonctions encapsulent la connexion à l’objet de classe, la création de l’instance et la libération de l’objet de classe. Deux autres fonctions, CoGetInstanceFromFile et CoGetInstanceFromIStorage, fournissent à la fois la création instance sur un système distant et l’activation d’objets. Il existe de nombreuses fonctions et méthodes d’interface dont l’objectif est de créer des objets d’un type unique et de fournir un pointeur vers une interface sur cet objet.

Syntaxe

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

Paramètres

[in] rclsid

CLSID associé aux données et au code que vous utiliserez pour créer les objets.

[in] dwClsContext

Contexte dans lequel le code exécutable doit être exécuté. Pour activer une activation à distance, incluez CLSCTX_REMOTE_SERVER. Pour plus d’informations sur les valeurs de contexte et leur utilisation, consultez l’énumération CLSCTX .

[in, optional] pvReserved

Pointeur vers l’ordinateur sur lequel instancier l’objet de classe. Si ce paramètre a la valeur NULL, l’objet de classe est instancié sur l’ordinateur actuel ou sur l’ordinateur spécifié sous la clé RemoteServerName de la classe, en fonction de l’interprétation du paramètre dwClsCtx . Consultez COSERVERINFO.

[in] riid

Référence à l’identificateur de l’interface, qui sera fourni dans ppv en cas de retour réussi. Cette interface sera utilisée pour communiquer avec l’objet de classe. En règle générale, cette valeur est IID_IClassFactory, bien que d’autres valeurs telles que IID_IClassFactory2 qui prend en charge une forme de licence soient autorisées. Tous les IID d’interface définis par OLE sont définis dans les fichiers d’en-tête OLE en tant que IID_interfacename, où interfacename est le nom de l’interface.

[out] ppv

Adresse de la variable pointeur qui reçoit le pointeur d’interface demandé dans riid. Une fois le retour réussi, *ppv contient le pointeur d’interface demandé.

Valeur retournée

Cette fonction peut retourner les valeurs suivantes.

Code de retour	Description
S_OK	L’emplacement et la connexion à l’objet de classe spécifié ont réussi.
REGDB_E_CLASSNOTREG	Le CLSID n’est pas correctement inscrit. Cette erreur peut également indiquer que la valeur que vous avez spécifiée dans dwClsContext n’est pas dans le Registre.
E_NOINTERFACE	L’objet pointé par ppv ne prend pas en charge l’interface identifiée par riid, ou l’opération QueryInterface sur l’objet de classe retourné E_NOINTERFACE.
REGDB_E_READREGDB	Une erreur s’est produite lors de la lecture de la base de données d’inscription.
CO_E_DLLNOTFOUND	La DLL in-process ou la DLL de gestionnaire est introuvable (selon le contexte).
CO_E_APPNOTFOUND	L’exécutable (.exe) est introuvable (CLSCTX_LOCAL_SERVER uniquement).
E_ACCESSDENIED	Il y a eu un échec d’accès général lors du chargement.
CO_E_ERRORINDLL	Une erreur s’affiche dans l’image exécutable.
CO_E_APPDIDNTREG	L’exécutable a été lancé, mais il n’a pas inscrit l’objet de classe (et il a peut-être été arrêté).

Remarques

Un objet de classe dans OLE est un objet intermédiaire qui prend en charge une interface qui autorise les opérations communes à un groupe d’objets. Les objets de ce groupe sont des instances dérivées de la même définition d’objet représentée par un SEUL CLSID. En règle générale, l’interface implémentée sur un objet de classe est IClassFactory, par le biais de laquelle vous pouvez créer des instances d’objet d’une définition donnée (classe).

Un appel à CoGetClassObject crée, initialise et donne à l’appelant un accès (via un pointeur vers une interface spécifiée avec le paramètre riid ) à l’objet de classe. L’objet de classe est celui associé au CLSID que vous spécifiez dans le paramètre rclsid . Les détails de la façon dont le système localise le code et les données associés dans un ordinateur sont transparents pour l’appelant, tout comme le chargement dynamique de tout code qui n’est pas déjà chargé.

Si le contexte de classe est CLSCTX_REMOTE_SERVER, indiquant que l’activation à distance est requise, la structure COSERVERINFO fournie dans le paramètre pServerInfo vous permet de spécifier l’ordinateur sur lequel se trouve le serveur. Pour plus d’informations sur l’algorithme utilisé pour localiser un serveur distant lorsque pServerInfo a la valeur NULL, reportez-vous à l’énumération CLSCTX .

Il existe deux emplacements pour trouver un CLSID pour une classe :

Le Registre contient une association entre les CLSID et les suffixes de fichier, et entre les CLSID et les signatures de fichier pour déterminer la classe d’un objet.
Lorsqu’un objet est enregistré dans un stockage persistant, son CLSID est stocké avec ses données.

Pour créer et initialiser des objets de document OLE incorporés ou liés, il n’est pas nécessaire d’appeler Directement CoGetClassObject . Appelez plutôt la fonction OleCreate ou OleCreateXXX . Ces fonctions encapsulent l’intégralité du processus d’instanciation et d’initialisation de l’objet, et appellent, entre autres fonctions, CoGetClassObject.

Le paramètre riid spécifie l’interface que le client utilisera pour communiquer avec l’objet de classe. Dans la plupart des cas, cette interface est IClassFactory. Cela permet d’accéder à la méthode CreateInstance , par le biais de laquelle l’appelant peut ensuite créer un objet non initialisé du type spécifié dans son implémentation. Toutes les classes inscrites dans le système avec un CLSID doivent implémenter IClassFactory.

Toutefois, dans de rares cas, vous pouvez spécifier une autre interface qui définit des opérations communes à un ensemble d’objets. Par exemple, dans la façon dont OLE implémente les monikers, l’interface sur l’objet de classe est IParseDisplayName, utilisée pour transformer le nom complet d’un objet en moniker.

Le paramètre dwClsContext spécifie le contexte d’exécution, ce qui permet à un CLSID d’être associé à différents éléments de code dans différents contextes d’exécution. L’énumération CLSCTX spécifie les indicateurs de contexte disponibles. CoGetClassObject consulte (en fonction du contexte indiqué) à la fois le registre et les objets de classe qui sont actuellement inscrits en appelant la fonction CoRegisterClassObject .

Pour libérer un objet de classe, utilisez la méthode Release de l’objet de classe. La fonction CoRevokeClassObject doit être utilisée uniquement pour supprimer le CLSID d’un objet de classe du registre système.

Configuration requise


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	combaseapi.h (inclure Objbase.h)
Bibliothèque	Ole32.lib
DLL	Ole32.dll