Fonction CoGetInstanceFromIStorage (objbase.h)

Article
02/29/2024

Crée un objet et l’initialise à partir d’un objet de stockage via un appel interne à IPersistFile ::Load.

Syntaxe

HRESULT CoGetInstanceFromIStorage(
  [in, optional] COSERVERINFO *pServerInfo,
  [in, optional] CLSID        *pClsid,
  [in, optional] IUnknown     *punkOuter,
  [in]           DWORD        dwClsCtx,
  [in]           IStorage     *pstg,
  [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 actif, sur l’ordinateur spécifié sous la valeur de Registre RemoteServerName pour la classe, ou sur l’ordinateur où réside l’objet de stockage pstg si la valeur ActivateAtStorage est spécifiée pour la classe ou qu’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 à IStorage ::Stat pour rechercher la classe de l’objet.

[in, optional] punkOuter

Si la valeur 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 pointeur vers IUnknown de contrôle 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 sera retourné si punkOuter n’a pas la valeur NULL.

[in] dwClsCtx

Valeurs de l’énumération CLSCTX .

[in] pstg

Pointeur vers l’objet de stockage utilisé pour initialiser l’objet avec IPersistFile ::Load. Ce paramètre ne peut pas avoir la valeur 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

CoGetInstanceFromIStorage crée un objet et l’initialise à partir d’un objet de stockage à 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 :

Cette fonction exige moins d’allers-retours réseau 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 valeur ActivateAtStorage ou n’a pas d’informations de Registre associées, cette fonction instancie un objet sur l’ordinateur où se trouve pstg , fournissant le moins possible de trafic réseau.

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	Ole32.dll

Voir aussi

CLSCTX

CoCreateInstanceEx

CoGetInstanceFromFile

Partager via