Fonction CoCreateInstanceEx (combaseapi.h)

Article
08/22/2023

Crée une instance d’une classe spécifique sur un ordinateur spécifique.

Syntaxe

HRESULT CoCreateInstanceEx(
  [in]      REFCLSID     Clsid,
  [in]      IUnknown     *punkOuter,
  [in]      DWORD        dwClsCtx,
  [in]      COSERVERINFO *pServerInfo,
  [in]      DWORD        dwCount,
  [in, out] MULTI_QI     *pResults
);

Paramètres

[in] Clsid

CLSID de l’objet à créer.

[in] punkOuter

Si ce paramètre n’est pas NULL, indique que le instance est en cours de création dans le cadre d’un agrégat, et que punkOuter doit être utilisé comme IUnknown de contrôle de la nouvelle instance. L’agrégation n’est actuellement pas prise en charge entre les processus ou les ordinateurs. Lors de l’instanciation d’un objet hors processus, CLASS_E_NOAGGREGATION sera retourné si punkOuter n’a pas la valeur NULL.

[in] dwClsCtx

Valeur de l’énumération CLSCTX .

[in] pServerInfo

Informations sur l’ordinateur sur lequel instancier l’objet. Consultez COSERVERINFO. Ce paramètre peut être NULL, auquel cas l’objet est instancié sur l’ordinateur local ou sur l’ordinateur spécifié dans le Registre sous la valeur RemoteServerName de la classe, en fonction de l’interprétation du paramètre dwClsCtx .

[in] dwCount

Nombre de structures dans pResults. Cette valeur doit être supérieure à 0.

[in, out] pResults

Tableau de structures MULTI_QI . Chaque structure a trois membres : l’identificateur d’une interface demandée (pIID), l’emplacement où retourner le pointeur d’interface (pItf) et la valeur de retour de l’appel à QueryInterface (hr).

Valeur retournée

Cette fonction peut retourner la valeur de retour standard E_INVALIDARG, ainsi que les valeurs suivantes.

Code de retour	Description
S_OK	Indique la réussite de l’opération.
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 serveur dans le Registre sont endommagées.
CLASS_E_NOAGGREGATION	Cette classe ne peut pas être créée dans le cadre d’un agrégat.
CO_S_NOTALLINTERFACES	Au moins une, mais pas toutes les interfaces demandées dans le tableau pResults ont été récupérées avec succès. Le membre hr de chacune des structures MULTI_QI dans pResults indique avec S_OK ou E_NOINTERFACE si l’interface spécifique a été retournée.
E_NOINTERFACE	Aucune des interfaces demandées dans le tableau pResults n’a été récupérée.

Remarques

CoCreateInstanceEx crée un seul objet non initialisé associé au CLSID donné sur un ordinateur distant spécifié. Il s’agit d’une extension de la fonction CoCreateInstance, qui crée un objet sur l’ordinateur local uniquement. En outre, au lieu de demander une seule interface et d’obtenir un pointeur unique vers cette interface, CoCreateInstanceEx permet de spécifier un tableau de structures, chacune pointant vers un identificateur d’interface (IID) en entrée et, au retour, contenant (si disponible) un pointeur vers l’interface demandée et la valeur de retour de l’appel QueryInterface pour cette interface. Cela permet moins d’allers-retours entre ordinateurs.

Cette fonction encapsule trois appels : premièrement, à CoGetClassObject pour se connecter à l’objet de classe associé au CLSID spécifié, en spécifiant l’emplacement de la classe ; ensuite, À IClassFactory ::CreateInstance pour créer un instance non initialisé, et enfin, à IClassFactory ::Release, pour libérer l’objet de classe.

L’objet ainsi créé doit toujours être initialisé via un appel à l’une des interfaces d’initialisation (par exemple , IPersistStorage ::Load). Deux fonctions, CoGetInstanceFromFile et CoGetInstanceFromIStorage encapsulent les instance création et l’initialisation à partir des sources évidentes.

La structure COSERVERINFO passée en tant que paramètre pServerInfo contient les paramètres de sécurité que COM utilisera lors de la création d’un instance de l’objet spécifié. Notez que ce paramètre n’influence pas les paramètres de sécurité utilisés lors des appels de méthode sur l’objet instancié. Ces paramètres de sécurité sont configurables, par interface, avec la fonction CoSetProxyBlanket . Consultez également IClientSecurity ::SetBlanket.

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

Voir aussi

CoGetInstanceFromFile

CoGetInstanceFromIStorage