Méthode IClassFactory::CreateInstance (unknwn.h)

Article
08/26/2023

Crée un objet non initialisé.

Syntaxe

HRESULT CreateInstance(
  [in]  IUnknown *pUnkOuter,
  [in]  REFIID   riid,
  [out] void     **ppvObject
);

Paramètres

[in] pUnkOuter

Si l’objet est créé dans le cadre d’un agrégat, spécifiez un pointeur vers l’interface IUnknown de contrôle de l’agrégat. Sinon, ce paramètre doit être NULL.

[in] riid

Référence à l’identificateur de l’interface à utiliser pour communiquer avec l’objet nouvellement créé. Si pUnkOuter a la valeur NULL, ce paramètre est généralement l’IID de l’interface d’initialisation ; si pUnkOuter n’a pas la valeur NULL, riid doit être IID_IUnknown.

[out] ppvObject

Adresse de la variable pointeur qui reçoit le pointeur d’interface demandé dans riid. En cas de retour réussi, *ppvObject contient le pointeur d’interface demandé. Si l’objet ne prend pas en charge l’interface spécifiée dans riid, l’implémentation doit définir *ppvObject sur NULL.

Valeur retournée

Cette méthode peut retourner les valeurs de retour standard E_INVALIDARG, E_OUTOFMEMORY et E_UNEXPECTED, ainsi que les valeurs suivantes.

Code de retour	Description
S_OK	L’objet spécifié a été créé.
CLASS_E_NOAGGREGATION	Le paramètre pUnkOuter n’était pas NULL et l’objet ne prend pas en charge l’agrégation.
E_NOINTERFACE	L’objet vers lequel ppvObject pointe ne prend pas en charge l’interface identifiée par riid.

Remarques

L’implémentation de CreateInstance d’un serveur COM doit retourner une référence à un objet contenu dans un appartement qui appartient au programme de résolution DCOM du serveur. Il ne doit pas retourner une référence à un objet contenu dans un appartement distant.

L’interface IClassFactory est toujours sur un objet de classe. La méthode CreateInstance crée un objet non initialisé de la classe identifiée avec le CLSID spécifié. Lorsqu’un objet est créé de cette façon, le CLSID doit être inscrit dans le registre système avec la fonction CoRegisterClassObject .

Le paramètre pUnkOuter indique si l’objet est créé dans le cadre d’un agrégat. Les définitions d’objets ne sont pas requises pour prendre en charge l’agrégation : elles doivent être spécifiquement conçues et implémentées pour la prendre en charge.

Le paramètre riid spécifie l’IID (identificateur d’interface) de l’interface via laquelle vous allez communiquer avec le nouvel objet. Si pUnkOuter n’a pas la valeur NULL (indiquant l’agrégation), la valeur du paramètre riid doit être IID_IUnknown. Si l’objet ne fait pas partie d’un agrégat, riid spécifie souvent l’interface par laquelle l’objet sera initialisé.

Pour les incorporations OLE, l’interface d’initialisation est IPersistStorage, mais dans d’autres situations, d’autres interfaces sont utilisées. Pour initialiser l’objet, il doit y avoir un appel ultérieur à une méthode appropriée dans l’interface d’initialisation. Les fonctions d’initialisation courantes incluent IPersistStorage::InitNew (pour les nouveaux composants incorporables vides), IPersistStorage::Load (pour les composants incorporés rechargés), IPersistStream::Load (pour les objets stockés dans un objet de flux) ou IPersistFile::Load (pour les objets stockés dans un fichier).

En général, si une application ne prend en charge qu’une seule classe d’objets et que l’objet de classe est inscrit pour une utilisation unique, un seul objet peut être créé. L’application ne doit pas créer d’autres objets, et une demande doit retourner une erreur à partir de IClassFactory::CreateInstance. Il en va de même pour les applications qui prennent en charge plusieurs classes, chacune avec un objet de classe inscrit pour une utilisation unique ; un appel à CreateInstance pour une classe suivi d’un appel à CreateInstance pour l’une des classes qui doivent retourner une erreur.

Pour éviter de renvoyer une erreur, les applications qui prennent en charge plusieurs classes avec des objets de classe à usage unique peuvent révoquer l’objet de classe inscrit de la première classe en appelant CoRevokeClassObject lorsqu’une demande d’instanciation d’une seconde est reçue. Par exemple, supposons qu’il existe deux classes, A et B. Lorsque CreateInstance est appelé pour la classe A, révoquez l’objet de classe pour B. Lorsque B est créé, révoquez l’objet de classe pour A. Cette solution complique l’arrêt, car l’un des objets de classe a peut-être déjà été révoqué (et ne peut pas être révoqué deux fois).

Configuration requise


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	unknwn.h

Voir aussi

CoCreateInstance

CoGetClassObject

CoRegisterClassObject

CoRevokeClassObject

IClassFactory