OleCreateEx, fonction (ole2.h)
Étend la fonctionnalité OleCreate en prenant en charge une instanciation plus efficace des objets dans des conteneurs nécessitant la mise en cache de plusieurs formats de présentation ou données, au lieu du format unique pris en charge par OleCreate.
Syntaxe
HRESULT OleCreateEx(
[in] REFCLSID rclsid,
[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
Identifie la classe de l’objet à créer.
[in] riid
Référence à l’identificateur de l’interface de l’objet à retourner.
[in] dwFlags
Cette valeur 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 cFormats, 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 cFormats. 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. Dans tous les autres cas, ce paramètre doit avoir la valeur NULL.
[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. Dans tous les autres cas, ce paramètre doit avoir la valeur NULL.
[out] rgdwConnection
Emplacement pour renvoyer le tableau des valeurs dwConnection retournées lorsque l’interface pAdviseSink est inscrite pour chaque connexion d’avis à l’aide de IDataObject ::D Advise, ou NULL si les connexions d’avis retournées ne sont pas nécessaires. 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 ê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. Ce paramètre n’est peut-être pas NULL.
[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 |
|---|---|
|
L’identificateur d’interface fourni n’est pas valide. |
Remarques
L’appel suivant à OleCreate :
OleCreate(rclsid, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);
équivaut à l’appel suivant à OleCreateEx :
DWORD advf = ADVF_PRIMEFIRST;
OleCreateEx(rclsid, riid, renderopt, 1, &advf, pFormatEtc, 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 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 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 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 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 (non gestionnaire par défaut) est nécessaire, rgdwConnection pour renvoyer les cookies IDataObject ::D Advise et pFormatEtc, 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 pFormatEtc. 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 |