CoCreateInstance, fonction (combaseapi.h)

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.

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

Voir aussi

CoCreateInstanceEx

CoGetClassObject

IClassFactory ::CreateInstance

Fonctions d’assistance à la création d’instance