Metodo IDataObject::EnumFormatEtc (objidl.h)

Articolo
03/05/2024

Crea un oggetto per enumerare i formati supportati da un oggetto dati.

Sintassi

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

Parametri

[in] dwDirection

Direzione dei dati. I valori possibili provengono dall'enumerazione DATADIR .

Il valore DATADIR_GET enumera i formati che possono essere passati a una chiamata a IDataObject::GetData. Il valore DATADIR_SET enumera i formati che possono essere passati a una chiamata a IDataObject::SetData.

[out] ppenumFormatEtc

Puntatore a una variabile di puntatore IEnumFORMATETC che riceve il puntatore di interfaccia al nuovo oggetto enumeratore.

Valore restituito

Questo metodo restituisce S_OK se l'operazione ha esito positivo. Altri valori possibili includono quanto segue.

Codice restituito	Descrizione
E_INVALIDARG	DwDirection specificato non è valido.
E_OUTOFMEMORY	Memoria insufficiente disponibile per questa operazione.
E_NOTIMPL	La direzione specificata da dwDirection non è supportata.
OLE_S_USEREG	Richiede l'enumerazione OLE dei formati dal Registro di sistema.

Commenti

EnumFormatEtc crea un oggetto enumeratore che può essere utilizzato per determinare tutti i modi in cui l'oggetto dati può descrivere i dati in una struttura FORMATETC e fornisce un puntatore alla relativa interfaccia IEnumFORMATETC . Si tratta di una delle interfacce dell'enumeratore standard.

Note ai chiamanti

Dopo aver ottenuto il puntatore, il chiamante può enumerare le strutture FORMATETC chiamando i metodi di enumerazione di IEnumFORMATETC. Poiché i formati possono cambiare nel tempo, non esiste alcuna garanzia che un formato enumerato sia attualmente supportato perché i formati possono cambiare nel tempo. Di conseguenza, le applicazioni devono considerare l'enumerazione come hint dei tipi di formato che possono essere passati. Il chiamante è responsabile della chiamata a Release al termine dell'enumeratore.

EnumFormatEtc viene chiamato quando si verifica una delle azioni seguenti:

Un'applicazione chiama OleSetClipboard. OLE deve determinare quali dati inserire negli Appunti e se è necessario inserire i formati di compatibilità OLE 1 negli Appunti.
I dati vengono incollati dagli Appunti o eliminati. Un'applicazione usa il primo formato accettabile.
Verrà visualizzata la finestra di dialogo Incolla speciale . L'applicazione di destinazione compila l'elenco di formati dalle voci FORMATETC .

Note per gli implementatori

I formati possono essere registrati in modo statico nel Registro di sistema o in modo dinamico durante l'inizializzazione degli oggetti. Se un oggetto include un elenco di formati non modificabile e questi formati vengono registrati nel Registro di sistema, OLE fornisce un'implementazione di un oggetto di enumerazione FORMATETC in grado di enumerare i formati registrati in un CLSID specifico nel Registro di sistema. Un puntatore all'interfaccia IEnumFORMATETC è disponibile tramite una chiamata alla funzione helper OleRegEnumFormatEtc. In questo caso, pertanto, è possibile implementare il metodo EnumFormatEtc semplicemente con una chiamata a questa funzione.

Le applicazioni EXE possono eseguire la stessa operazione implementando il metodo per restituire il valore OLE_S_USEREG. Questo valore restituito indica al gestore dell'oggetto predefinito di chiamare OleRegEnumFormatEtc. Le applicazioni oggetto implementate come applicazioni oggetto DLL non possono restituire OLE_S_USEREG, pertanto è necessario chiamare direttamente OleRegEnumFormatEtc .

I formati privati possono essere enumerati per gli oggetti OLE 1, se sono registrati con le chiavi RequestDataFormats o SetDataFormats nel Registro di sistema. Inoltre, i formati privati possono essere enumerati per gli oggetti OLE (tutte le versioni successive a OLE 1), se vengono registrati con le chiavi GetDataFormats o SetDataFormats.

Per gli oggetti OLE 1 i cui server non dispongono di informazioni RequestDataFormats o SetDataFormats registrate nel Registro di sistema, una chiamata a EnumFormatEtc passando DATADIR_GET enumera solo i formati nativi e metafile, indipendentemente dal fatto che supportino questi formati o altri. Chiamando EnumFormatEtc passando DATADIR_SET su tali oggetti enumera solo il codice nativo, indipendentemente dal fatto che l'oggetto supporti l'impostazione con altri formati.

La struttura FORMATETC restituita dall'enumerazione indica in genere un dispositivo di destinazione NULL (ptd). Ciò è appropriato perché, a differenza degli altri membri di FORMATETC, il dispositivo di destinazione non partecipa alla decisione dell'oggetto se può accettare o fornire i dati in una chiamata SetData o GetData.

Il membro tymed di FORMATETC spesso indica che più di un tipo di supporto di archiviazione è accettabile. È sempre consigliabile mascherare e testarlo usando un operatore OR booleano.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	objidl.h