OleCreateFromData, fonction (ole2.h)

Article
02/29/2024

Crée un objet incorporé à partir d’un objet de transfert de données récupéré dans le Presse-papiers ou dans le cadre d’une opération de glisser-déplacer OLE. Il est destiné à être utilisé pour implémenter un collage à partir d’une opération de glisser-déplacer OLE.

Syntaxe

HRESULT OleCreateFromData(
  [in]  LPDATAOBJECT    pSrcDataObj,
  [in]  REFIID          riid,
  [in]  DWORD           renderopt,
  [in]  LPFORMATETC     pFormatEtc,
  [in]  LPOLECLIENTSITE pClientSite,
  [in]  LPSTORAGE       pStg,
  [out] LPVOID          *ppvObj
);

Paramètres

[in] pSrcDataObj

Pointeur vers l’interface IDataObject sur l’objet de transfert de données qui contient les données à partir de laquelle l’objet est créé.

[in] riid

Référence à l’identificateur de l’interface que l’appelant utilise ultérieurement pour communiquer avec le nouvel objet (généralement IID_IOleObject, défini dans les en-têtes OLE comme identificateur d’interface pour IOleObject).

[in] renderopt

Valeur de l’énumération OLERENDER qui indique les fonctionnalités de dessin ou de récupération de données mises en cache localement que l’objet nouvellement créé doit avoir. D’autres considérations sont décrites dans la section Remarques suivante.

[in] pFormatEtc

Pointeur vers une valeur de l’énumération OLERENDER qui indique les fonctionnalités de dessin ou de récupération des données mises en cache localement que l’objet nouvellement créé doit avoir. La valeur OLERENDER choisie affecte les valeurs possibles pour le paramètre pFormatEtc .

[in] pClientSite

Pointeur vers un instance de IOleClientSite, l’interface principale via laquelle l’objet demande des services à partir de son conteneur. Ce paramètre peut être NULL.

[in] pStg

Pointeur vers l’interface IStorage sur l’objet de stockage. Ce paramètre peut ne pas avoir la valeur NULL.

[out] ppvObj

Adresse de la variable pointeur 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
OLE_E_STATIC	Indique qu’OLE peut créer uniquement un objet statique.
DV_E_FORMATETC	Aucun format acceptable n’est disponible pour la création d’objets.

Remarques

La fonction OleCreateFromData crée un objet incorporé à partir d’un objet de transfert de données prenant en charge l’interface IDataObject . Dans ce cas, l’objet de données est soit le type récupéré dans le Presse-papiers avec un appel à la fonction OleGetClipboard , soit fait partie d’une opération de glisser-déplacer OLE (l’objet de données est passé à un appel à IDropTarget ::D rop).

Si le format de Presse-papiers FileName ou FileNameW (CF_FILENAME) est présent dans l’objet de transfert de données et que CF_EMBEDDEDOBJECT ou CF_EMBEDSOURCE n’existe pas, OleCreateFromData tente d’abord de créer un package contenant le fichier indiqué. En règle générale, il prend le premier format disponible.

Si OleCreateFromData ne peut pas créer de package, il tente de créer un objet à l’aide du format CF_EMBEDDEDOBJECT. Si ce format n’est pas disponible, OleCreateFromData tente de le créer avec le format CF_EMBEDSOURCE. Si aucun de ces formats n’est disponible et que l’objet de transfert de données prend en charge l’interface IPersistStorage , OleCreateFromData appelle IPersistStorage ::Save de l’objet pour que l’objet s’enregistre lui-même.

Si un objet lié existant est sélectionné, puis copié, il apparaît dans le Presse-papiers comme un autre objet incorporable. Par conséquent, une opération de collage qui appelle OleCreateFromData peut créer un objet lié. Après l’opération de collage, le conteneur doit appeler la fonction QueryInterface , en demandant IID_IOleLink (défini dans les en-têtes OLE comme identificateur d’interface pour IOleLink), afin de déterminer si un objet lié a été créé.

Utilisez les paramètres renderopt et pFormatetc pour contrôler la fonctionnalité de mise en cache de l’objet nouvellement créé. Pour obtenir des informations générales sur l’utilisation de l’interaction de ces paramètres pour déterminer ce qui doit être mis en cache, reportez-vous à l’énumération OLERENDER . Toutefois, il existe des effets spécifiques supplémentaires de ces paramètres sur la façon dont OleCreateFromData initialise le cache.

Lorsque OleCreateFromData utilise le format CF_EMBEDDEDOBJECT ou CF_EMBEDSOURCE presse-papiers pour créer l’objet incorporé, la différence main entre les deux est l’emplacement où les données d’initialisation du cache sont stockées :

CF_EMBEDDEDOBJECT indique que la source est un objet incorporé existant. Il a déjà dans son cache les données appropriées, et OLE utilise ces données pour initialiser le cache du nouvel objet.
CF_EMBEDSOURCE indique que l’objet de données source contient les informations d’initialisation du cache dans des formats autres que CF_EMBEDSOURCE. OleCreateFromData les utilise pour initialiser le cache de l’objet nouvellement incorporé.

Les valeurs renderopt affectent l’initialisation du cache comme suit.

Valeur	Description
OLERENDER_DRAW & OLERENDER_FORMAT	Si les informations de présentation à mettre en cache sont actuellement présentes dans le pool d’initialisation du cache approprié, elles sont utilisées. (Les emplacements appropriés se trouvent dans le cache d’objets de données sources pour CF_EMBEDDEDOBJECT et dans les autres formats de l’objet de données source pour CF_EMBEDSOURCE.) Si les informations ne sont pas présentes, le cache est initialement vide, mais est rempli la première fois que l’objet est exécuté. Aucun autre format n’est mis en cache dans l’objet nouvellement créé.
OLERENDER_NONE	Rien ne doit être mis en cache dans l’objet nouvellement créé. Si la source a le format CF_EMBEDDEDOBJECT, toutes les données mises en cache existantes qui ont été copiées sont supprimées.
OLERENDER_ASIS	Si la source a le format CF_EMBEDDEDOBJECT, le cache du nouvel objet doit contenir les mêmes données de cache que l’objet source. Par CF_EMBEDSOURCE, rien ne doit être mis en cache dans l’objet nouvellement créé. Cette option doit être utilisée par des conteneurs plus sophistiqués. Après cet appel, ces conteneurs appellent IOleCache ::Cache et IOleCache ::Uncache pour configurer exactement ce qui doit être mis en cache. Par CF_EMBEDSOURCE, ils appellent également IOleCache ::InitCache.

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
Ensemble d’API	ext-ms-win-com-ole32-l1-1-3 (introduit dans Windows 10, version 10.0.10240)

Voir aussi

Idataobject

OleCreate