CoCreateInstance, fonction (combaseapi.h)

Article
08/22/2023

Crée et initialise par défaut un objet unique de la classe associée à un CLSID spécifié.

Appelez CoCreateInstance lorsque vous souhaitez créer un seul objet sur le système local. Pour créer un seul objet sur un système distant, appelez la fonction CoCreateInstanceEx . Pour créer plusieurs objets basés sur un SEUL CLSID, appelez la fonction CoGetClassObject .

Syntaxe

HRESULT CoCreateInstance(
  [in]  REFCLSID  rclsid,
  [in]  LPUNKNOWN pUnkOuter,
  [in]  DWORD     dwClsContext,
  [in]  REFIID    riid,
  [out] LPVOID    *ppv
);

Paramètres

[in] rclsid

CLSID associé aux données et au code qui seront utilisés pour créer l’objet.

[in] pUnkOuter

Si la valeur est NULL, indique que l’objet n’est pas créé dans le cadre d’un agrégat. Si la valeur n’est pas NULL, pointez vers l’interface IUnknown de l’objet d’agrégation ( IUnknown de contrôle).

[in] dwClsContext

Contexte dans lequel le code qui gère l’objet nouvellement créé s’exécutera. Les valeurs proviennent de l’énumération CLSCTX.

[in] riid

Référence à l’identificateur de l’interface à utiliser pour communiquer avec l’objet .

[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é. En cas d’échec, *ppv contient NULL.

Valeur retournée

Cette fonction peut retourner les valeurs suivantes.

Code de retour	Description
S_OK	Une instance de la classe d’objet spécifiée a été créée avec succès.
REGDB_E_CLASSNOTREG	Une classe spécifiée n’est pas inscrite dans la base de données d’inscription. Peut également indiquer que le type de serveur que vous avez demandé dans l’énumération CLSCTX n’est pas inscrit ou que les valeurs des types de serveurs dans le Registre sont endommagées.
CLASS_E_NOAGGREGATION	Cette classe ne peut pas être créée dans le cadre d’un agrégat.
E_NOINTERFACE	La classe spécifiée n’implémente pas l’interface demandée, ou le contrôle IUnknown n’expose pas l’interface demandée.
E_POINTER	Le paramètre ppv est NULL.

Remarques

La fonction CoCreateInstance fournit un raccourci pratique en se connectant à l’objet de classe associé au CLSID spécifié, en créant un instance initialisé par défaut et en libérant l’objet de classe. Par conséquent, il encapsule les fonctionnalités suivantes :

CoGetClassObject(rclsid, dwClsContext, NULL, IID_IClassFactory, &pCF); 
hresult = pCF->CreateInstance(pUnkOuter, riid, ppvObj);
pCF->Release();

Il est pratique d’utiliser CoCreateInstance lorsque vous devez créer une seule instance d’un objet sur l’ordinateur local. Si vous créez un instance sur un ordinateur distant, appelez CoCreateInstanceEx. Lorsque vous créez plusieurs instances, il est plus efficace d’obtenir un pointeur vers l’interface IClassFactory de l’objet de classe et d’utiliser ses méthodes si nécessaire. Dans ce dernier cas, vous devez utiliser la fonction CoGetClassObject .

Dans l’énumération CLSCTX , vous pouvez spécifier le type de serveur utilisé pour gérer l’objet. Les constantes peuvent être CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER, CLSCTX_REMOTE_SERVER ou n’importe quelle combinaison de ces valeurs. La constante CLSCTX_ALL est définie comme la combinaison des quatre. Pour plus d’informations sur l’utilisation d’une ou d’une combinaison de ces constantes, consultez CLSCTX.

Applications UWP

Bien qu’il n’existe aucune restriction sur les CLSID qu’une application UWP peut passer à CoCreateInstance, de nombreux objets échouent avec E_ACCESSDENIED pour des raisons de sécurité, en particulier s’ils ne s’exécutent pas dans le processus. En outre, même si vous pouvez créer un objet, il peut échouer ultérieurement en raison de contraintes de sécurité UWP, de différences de modèle d’application, etc. En particulier, les tâches en arrière-plan doivent limiter les objets avec lesquels elles communiquent pour éviter les blocages ou autres complications dues à la connexion en mode veille.

Exemples

// Create WIC factory
hr = CoCreateInstance(
    CLSID_WICImagingFactory,
    NULL,
    CLSCTX_INPROC_SERVER,
    IID_PPV_ARGS(&m_pIWICFactory)
    );

Configuration requise

Condition requise	Valeur
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