CoGetInstanceFromFile, fonction (objbase.h)

  • Article

Crée un objet et l’initialise à partir d’un fichier à l’aide de IPersistFile ::Load.

Syntaxe

HRESULT CoGetInstanceFromFile(
  [in, optional] COSERVERINFO *pServerInfo,
  [in, optional] CLSID        *pClsid,
  [in, optional] IUnknown     *punkOuter,
  [in]           DWORD        dwClsCtx,
  [in]           DWORD        grfMode,
  [in]           OLECHAR      *pwszName,
  [in]           DWORD        dwCount,
  [in, out]      MULTI_QI     *pResults
);

Paramètres

[in, optional] pServerInfo

Pointeur vers une structure COSERVERINFO qui spécifie l’ordinateur sur lequel instancier l’objet et le paramètre d’authentification à utiliser. Ce paramètre peut être NULL, auquel cas l’objet est instancié sur l’ordinateur actuel, sur l’ordinateur spécifié sous la valeur de Registre RemoteServerName pour la classe, ou sur l’ordinateur où réside le fichier pwszName si la valeur ActivateAtStorage est spécifiée pour la classe ou s’il n’existe aucune information de Registre local.

[in, optional] pClsid

Pointeur vers l’identificateur de classe de l’objet à créer. Ce paramètre peut être NULL, auquel cas il existe un appel à GetClassFile, en utilisant pwszName comme paramètre pour obtenir la classe de l’objet à instancier.

[in, optional] punkOuter

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

[in] dwClsCtx

Valeurs de l’énumération CLSCTX .

[in] grfMode

Spécifie la façon dont le fichier doit être ouvert. Consultez Constantes STGM.

[in] pwszName

Fichier utilisé pour initialiser l’objet avec IPersistFile ::Load. Ce paramètre ne peut pas être NULL.

[in] dwCount

Nombre de structures dans pResults. Ce paramètre doit être supérieur à 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
 La fonction a récupéré toutes les interfaces avec succès.
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 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

CoGetInstanceFromFile crée un objet et l’initialise à partir d’un fichier à l’aide de IPersistFile ::Load. Le résultat de cette fonction est similaire à la création d’un instance avec un appel à CoCreateInstanceEx, suivi d’un appel d’initialisation à IPersistFile ::Load, avec les distinctions importantes suivantes :

  • Moins d’allers-retours réseau sont requis par cette fonction lors de l’instanciation d’un objet sur un ordinateur distant.
  • Dans le cas où dwClsCtx est défini sur CLSCTX_REMOTE_SERVER et que pServerInfo a la valeur NULL, si la classe est inscrite avec la sous-clé ActivateAtStorage ou n’a aucune information de Registre associée, cette fonction instancie un objet sur l’ordinateur où se trouve pwszName , ce qui fournit le moins de trafic réseau possible.

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 objbase.h
Bibliothèque Ole32.lib
DLL ComBase.dll

Voir aussi

CLSCTX

CoCreateInstanceEx

CoGetInstanceFromIStorage