OleCreateFromFileEx, fonction (ole2.h)

Article
03/04/2024

Étend la fonctionnalité OleCreateFromFile en prenant en charge l’instanciation plus efficace des objets dans les conteneurs nécessitant la mise en cache de plusieurs formats ou données de présentation, au lieu du format unique pris en charge par OleCreateFromFile.

Syntaxe

HRESULT OleCreateFromFileEx(
  [in]  REFCLSID        rclsid,
  [in]  LPCOLESTR       lpszFileName,
  [in]  REFIID          riid,
  [in]  DWORD           dwFlags,
  [in]  DWORD           renderopt,
  [in]  ULONG           cFormats,
  [in]  DWORD           *rgAdvf,
  [in]  LPFORMATETC     rgFormatEtc,
  [in]  IAdviseSink     *lpAdviseSink,
  [out] DWORD           *rgdwConnection,
  [in]  LPOLECLIENTSITE pClientSite,
  [in]  LPSTORAGE       pStg,
  [out] LPVOID          *ppvObj
);

Paramètres

[in] rclsid

Ce paramètre est réservé et doit être CLSID_NULL.

[in] lpszFileName

Pointeur vers le nom du fichier à partir duquel le nouvel objet doit être initialisé.

[in] riid

Référence à l’identificateur de l’interface de l’objet à retourner.

[in] dwFlags

Ce paramètre peut être 0 ou OLECREATE_LEAVERUNNING (0x00000001).

[in] renderopt

Valeur extraite de l’énumération OLERENDER .

[in] cFormats

Lorsque renderopt est OLERENDER_FORMAT, indique le nombre de structures FORMATETC dans le tableau rgFormatEtc , qui doit être au moins une. Dans tous les autres cas, ce paramètre doit être égal à zéro.

[in] rgAdvf

Lorsque renderopt est OLERENDER_FORMAT, pointe vers un tableau d’éléments DWORD , chacun d’eux étant une combinaison de valeurs de l’énumération ADVF . Chaque élément de ce tableau est passé en tant que paramètre advf à un appel à IOleCache ::Cache ou IDataObject ::D Advise, selon que pAdviseSink a la valeur NULL ou non NULL (voir ci-dessous). Dans tous les autres cas, ce paramètre doit être NULL.

[in] rgFormatEtc

Lorsque renderopt est OLERENDER_FORMAT, pointe vers un tableau de structures FORMATETC . Lorsque pAdviseSink a la valeur NULL, chaque élément de ce tableau est passé en tant que paramètre pFormatEtc à un appel à IOleCache ::Cache de l’objet. Cette opération remplit le cache de données et de présentation géré par le gestionnaire d’objets in-process (généralement le gestionnaire par défaut) avec des données de présentation ou d’autres données pouvant être mises en cache. Lorsque pAdviseSink n’a pas la valeur NULL, chaque élément de ce tableau est passé en tant que paramètre pFormatEtc à un appel à IDataObject ::D Advise. Cela permet à l’appelant (généralement un conteneur OLE) d’effectuer sa propre mise en cache ou traitement des données reçues de l’objet.

[in] lpAdviseSink

Lorsque renderopt est OLERENDER_FORMAT, peut être un pointeur IAdviseSink valide, indiquant la mise en cache personnalisée ou le traitement des conseils de données, ou NULL, indiquant la mise en cache par défaut des formats de données.

[out] rgdwConnection

Emplacement pour retourner le tableau des valeurs dwConnection retournées lorsque l’interface pAdviseSink est inscrite pour chaque connexion de conseil à l’aide de IDataObject ::D Advise, ou NULL si les connexions de conseil retournées ne sont pas nécessaires. Ce paramètre doit être NULL si pAdviseSink a la valeur NULL.

[in] pClientSite

Pointeur vers l’interface principale via laquelle l’objet demande des services à partir de son conteneur. Ce paramètre peut être NULL, auquel cas il incombe à l’appelant d’établir le site client dès que possible à l’aide de IOleObject ::SetClientSite.

[in] pStg

Pointeur vers le stockage à utiliser pour l’objet et toute mise en cache de données ou de présentation par défaut établie pour celui-ci.

[out] ppvObj

Adresse de la variable pointeur de sortie qui reçoit le pointeur d’interface demandé dans riid. En cas de retour réussi, *ppvObj contient le pointeur d’interface demandé sur l’objet nouvellement créé.

Valeur retournée

Cette fonction retourne S_OK en cas de réussite. Les autres valeurs possibles sont les suivantes.

Code de retour	Description
E_NOINTERFACE	L’identificateur d’interface fourni n’est pas valide.
E_INVALIDARG	Un ou plusieurs paramètres ne sont pas valides.

Remarques

L’appel suivant à OleCreateFromFile :

OleCreateFromFile(rclsid, lpszFileName, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

équivaut à l’appel suivant à OleCreateFromFileEx :

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateFromFileEx(rclsid, lpszFileName, riid, renderopt, 1, &advf, pFormatEtc, NULL, pClientSite, pStg, ppvObj);

Les fonctions d’instanciation existantes (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLinkToFile et OleCreateLinkFromData) créent un seul cache de présentation ou de format de données à l’emplacement du cache par défaut (dans les flux « \001OlePresXXX » de l’IStorage passé), pendant l’instanciation. De plus, ces caches doivent être créés lorsque l’objet passe ensuite à l’état d’exécution. Étant donné que la plupart des applications nécessitent la mise en cache d’au moins deux présentations (écran et imprimante) et qu’elles peuvent nécessiter la mise en cache des données dans un format ou un emplacement différent du gestionnaire, les applications doivent généralement lancer et arrêter le serveur d’objets plusieurs fois afin d’amorcer leurs caches de données lors de la création de l’objet, c’est-à-dire Insérer un objet, Insérer un objet à partir d’un fichier et Coller un objet.

Les versions étendues de ces fonctions de création résolvent ce problème. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx et OleCreateLinkFromDataEx, contiennent les nouveaux paramètres suivants : dwFlags pour indiquer des options supplémentaires, cFormats pour indiquer le nombre de formats à mettre en cache, rgAdvf, à partir de l’énumération ADVF , pour spécifier les indicateurs conseillés pour chaque format à mettre en cache, pAdviseSink pour indiquer si la mise en cache de présentation (gestionnaire par défaut) ou de données (non gestionnaire par défaut) est requise, rgdwConnection pour renvoyer IDataObject ::D Advise cookies et rgFormatEtc, un tableau de formats plutôt qu’un format unique.

Les conteneurs nécessitant que plusieurs présentations soient mises en cache en leur nom par le gestionnaire de l’objet peuvent simplement appeler ces fonctions et spécifier le nombre de formats dans cFormats, les indicateurs ADVF pour chaque format dans rgAdvf et l’ensemble des formats dans rgFormatEtc. Ces conteneurs passent la valeur NULL pour pAdviseSink.

Les conteneurs effectuant toutes leurs propres mises en cache de données ou de présentations effectuent ces mêmes étapes, mais passent un pAdviseSink non NULL. Ils effectuent leur propre mise en cache ou manipulation de l’objet ou des données pendant IAdviseSink ::OnDataChange. En règle générale, ces conteneurs n’établissent jamais les connexions de conseil avec ADVF_NODATA, bien qu’ils ne soient pas empêchés de le faire.

Ces nouvelles fonctions sont destinées aux documents composés OLE. À l’aide de ces fonctions, les applications peuvent éviter les étapes répétées de lancement et d’initialisation requises par les fonctions actuelles. Ils ciblent les applications conteneur OLE Compound Document qui utilisent la mise en cache des données et des présentations par défaut, ainsi que les applications qui fournissent leur propre mise en cache et transfert de données à partir de la prise en charge IDataObject ::D Advise sous-jacente.

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