IDataObject ::EnumFormatEtc, méthode (objidl.h)

Article
08/25/2023

Crée un objet pour énumérer les formats pris en charge par un objet de données.

Syntaxe

HRESULT EnumFormatEtc(
  [in]  DWORD          dwDirection,
  [out] IEnumFORMATETC **ppenumFormatEtc
);

Paramètres

[in] dwDirection

Direction des données. Les valeurs possibles proviennent de l’énumération DATADIR .

La valeur DATADIR_GET énumère les formats qui peuvent être passés à un appel à IDataObject ::GetData. La valeur DATADIR_SET énumère les formats qui peuvent être passés à un appel à IDataObject ::SetData.

[out] ppenumFormatEtc

Pointeur vers une variable de pointeur IEnumFORMATETC qui reçoit le pointeur d’interface vers le nouvel objet énumérateur.

Valeur retournée

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

Code de retour	Description
E_INVALIDARG	Le dwDirection fourni n’est pas valide.
E_OUTOFMEMORY	Mémoire insuffisante disponible pour cette opération.
E_NOTIMPL	La direction spécifiée par dwDirection n’est pas prise en charge.
OLE_S_USEREG	Demande qu'OLE énumère les formats à partir du Registre.

Remarques

EnumFormatEtc crée un objet énumérateur qui peut être utilisé pour déterminer toutes les façons dont l’objet de données peut décrire des données dans une structure FORMATETC et fournit un pointeur vers son interface IEnumFORMATETC . Il s’agit de l’une des interfaces d’énumérateur standard.

Remarques aux appelants

Après avoir obtenu le pointeur, l’appelant peut énumérer les structures FORMATETC en appelant les méthodes d’énumération de IEnumFORMATETC. Étant donné que les formats peuvent changer au fil du temps, il n’existe aucune garantie qu’un format énuméré est actuellement pris en charge, car les formats peuvent changer au fil du temps. En conséquence, les applications doivent traiter l’énumération comme un indicateur des types de format qui peuvent être transmis. L’appelant est chargé d’appeler Release lorsqu’il a terminé avec l’énumérateur.

EnumFormatEtc est appelé lorsque l’une des actions suivantes se produit :

Une application appelle OleSetClipboard. OLE doit déterminer les données à placer dans le Presse-papiers et s’il est nécessaire de placer des formats de compatibilité OLE 1 dans le Presse-papiers.
Les données sont collées dans le Presse-papiers ou supprimées. Une application utilise le premier format acceptable.
La boîte de dialogue Coller spécial s’affiche. L’application cible génère la liste des formats à partir des entrées FORMATETC .

Remarques aux implémenteurs

Les formats peuvent être inscrits de manière statique dans le registre ou dynamiquement pendant l’initialisation d’objet. Si un objet a une liste immuable de formats et que ces formats sont inscrits dans le Registre, OLE fournit une implémentation d’un objet d’énumération FORMATETC qui peut énumérer les formats inscrits sous un CLSID spécifique dans le Registre. Un pointeur vers son interface IEnumFORMATETC est disponible via un appel à la fonction d’assistance OleRegEnumFormatEtc. Dans ce cas, vous pouvez donc implémenter la méthode EnumFormatEtc simplement avec un appel à cette fonction.

Les applications EXE peuvent effectivement faire la même chose en implémentant la méthode pour retourner la valeur OLE_S_USEREG. Cette valeur de retour indique au gestionnaire d’objets par défaut d’appeler OleRegEnumFormatEtc. Les applications objet implémentées en tant qu’applications objet DLL ne peuvent pas retourner OLE_S_USEREG. Elles doivent donc appeler OleRegEnumFormatEtc directement.

Les formats privés peuvent être énumérés pour les objets OLE 1, s’ils sont inscrits avec les clés RequestDataFormats ou SetDataFormats dans le Registre. En outre, les formats privés peuvent être énumérés pour les objets OLE (toutes les versions après OLE 1), s’ils sont inscrits avec les clés GetDataFormats ou SetDataFormats.

Pour les objets OLE 1 dont les serveurs ne disposent pas d’informations RequestDataFormats ou SetDataFormats inscrites dans le Registre, un appel à EnumFormatEtc passant DATADIR_GET énumère uniquement les formats natifs et métafichiers, qu’ils prennent en charge ces formats ou d’autres formats. L’appel d’EnumFormatEtc en passant des DATADIR_SET sur ces objets énumère uniquement en mode natif, que l’objet prenne ou non en charge la définition avec d’autres formats.

La structure FORMATETC retournée par l’énumération indique généralement un appareil cible NULL (ptd). Cela est approprié, car, contrairement aux autres membres de FORMATETC, l’appareil cible ne participe pas à la décision de l’objet quant à savoir s’il peut accepter ou fournir les données dans un appel SetData ou GetData.

Le membre lié de FORMATETC indique souvent que plusieurs types de support de stockage sont acceptables. Vous devez toujours masquer et tester cela à l’aide d’un opérateur BOOlean OR.

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	objidl.h