OleCreateLinkEx, fonction (ole2.h)

Article
02/29/2024

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

Syntaxe

HRESULT OleCreateLinkEx(
  [in]  LPMONIKER       pmkLinkSrc,
  [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] pmkLinkSrc

Pointeur vers un moniker vers l’objet vers lequel créer un lien.

[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 avoir la valeur NULL.

[in] rgFormatEtc

Lorsque le rendu 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. Cela remplit le cache de données et de présentation géré par le gestionnaire d’objets en cours de processus (généralement le gestionnaire par défaut) avec la 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, il peut s’agir d’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 renvoyer le tableau de valeurs dwConnection retournées lorsque l’interface IAdviseSink est inscrite pour chaque connexion de conseil à l’aide de IDataObject ::D Advise, ou NULL si les connexions d’avis retournées ne sont pas nécessaires. Ce paramètre doit avoir la valeur 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 avoir la valeur 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. Une fois le 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 à OleCreateLink :

OleCreateLink(pmkLinkSrc, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

équivaut à l’appel suivant à OleCreateLinkEx :

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

Les fonctions d’instanciation existantes (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile et OleCreateLinkFromData) créent un seul cache de présentation ou de format de données dans l’emplacement de cache par défaut (dans les flux « \001OlePresXXX » du IStorage transmis) pendant l’instanciation. De plus, ces caches doivent être créés lorsque l’objet entre ensuite dans l’état en cours d’exécution. Étant donné que la plupart des applications nécessitent une mise en cache dans au moins deux présentations (écran et imprimante) et qu’elles peuvent nécessiter la mise en cache des données dans un autre format ou emplacement à partir 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 d’un objet, par exemple Insérer un objet, Insérer un objet à partir d’un fichier, et Collage de l’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 de conseil 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 (autre que le gestionnaire par défaut) est nécessaire, rgdwConnection pour renvoyer les cookies IDataObject ::D Advise , 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 de 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ésentation 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, même s’ils ne sont 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 de lancement et d’initialisation répétées requises par les fonctions actuelles. Ils ciblent les applications conteneur OLE Compound Document qui utilisent la mise en cache des données et de la présentation 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