IDataObject::GetCanonicalFormatEtc-Methode (objidl.h)

Stellt eine potenziell andere, aber logisch gleichwertige FORMATTC-Struktur bereit. Sie verwenden diese Methode, um zu bestimmen, ob zwei unterschiedliche FORMATETC-Strukturen dieselben Daten zurückgeben würden, sodass keine duplizierten Renderings erforderlich sind.

Syntax

HRESULT GetCanonicalFormatEtc(
  [in]  FORMATETC *pformatectIn,
  [out] FORMATETC *pformatetcOut
);

Parameter

[in] pformatectIn

Ein Zeiger auf die FORMATETC-Struktur , die das Format, das Medium und das Zielgerät definiert, das der Aufrufer verwenden möchte, um Daten in einem nachfolgenden Aufruf wie IDataObject::GetData abzurufen. Das tymed-Element ist in diesem Fall nicht signifikant und sollte ignoriert werden.

[out] pformatetcOut

Ein Zeiger auf eine FORMATETC-Struktur , die die allgemeinsten Informationen enthält, die für ein bestimmtes Rendering möglich sind, wodurch sie kanonisch äquivalent zu pformatetcIn ist. Der Aufrufer muss diese Struktur zuordnen, und die GetCanonicalFormatEtc-Methode muss die Daten ausfüllen. Um Daten in einem nachfolgenden Aufruf wie IDataObject::GetData abzurufen, verwendet der Aufrufer den angegebenen Wert von pformatetcOut, es sei denn, der angegebene Wert ist NULL. Dieser Wert ist NULL , wenn die Methode DATA_S_SAMEFORMATETC zurückgibt. Das tymed-Element ist in diesem Fall nicht signifikant und sollte ignoriert werden.

Rückgabewert

Diese Methode kann die folgenden Werte zurückgeben.

Rückgabecode BESCHREIBUNG
S_OK
Die zurückgegebene FORMATTC-Struktur unterscheidet sich von der, die übergeben wurde.
DATA_S_SAMEFORMATETC
Die FORMATETC-Strukturen sind identisch, und NULL wird in pformatetcOut zurückgegeben.
DV_E_LINDEX
Der Wert für lindex ist ungültig. derzeit wird nur -1 unterstützt.
DV_E_FORMATETC
Der Wert für pformatetc ist ungültig.
OLE_E_NOTRUNNING
Die Objektanwendung wird nicht ausgeführt.
E_UNEXPECTED
Ein unerwarteter Fehler ist aufgetreten.
E_INVALIDARG
Der dwDirection-Parameter ist ungültig.
E_OUTOFMEMORY
Für diesen Vorgang war nicht genügend Arbeitsspeicher verfügbar.

Hinweise

Wenn ein Datenobjekt genau die gleichen Daten für mehrere angeforderte FORMATETC-Strukturen bereitstellen kann, kann GetCanonicalFormatEtc eine "kanonische" oder standardmäßige FORMATTC-Instanz bereitstellen, die das gleiche Rendering wie eine Reihe komplizierter FORMATETC-Strukturen bereitstellt. Beispielsweise ist es üblich, dass die zurückgegebenen Daten nicht für das Zielgerät, das in einer der anderen ähnlichen FORMATETC-Strukturen angegeben ist , nicht empfindlich sind.

Hinweise für Anrufer

Ein Aufruf dieser Methode kann bestimmen, ob zwei Aufrufe von IDataObject::GetData für ein Datenobjekt, bei denen zwei verschiedene FORMATETC-Strukturen angegeben werden, tatsächlich dieselben Renderings erzeugen würden, sodass der zweite Aufruf nicht mehr erforderlich ist und die Leistung verbessert wird. Wenn der Aufruf von GetCanonicalFormatEtc dazu führt, dass ein kanonisches Format in den pformatetcOut-Parameter geschrieben wird, verwendet der Aufrufer diese Struktur in einem nachfolgenden Aufruf von IDataObject::GetData.

Hinweise zu Implementierern

Konzeptionell ist es möglich, FORMATETC-Strukturen in Gruppen vorzudenken, die durch ein kanonisches FORMATTC definiert werden, die die gleichen Ergebnisse wie die einzelnen Gruppenmitglieder liefern. Beim Erstellen des kanonischen FORMATETC sollten Sie sicherstellen, dass es die möglichst allgemeinen Informationen enthält, die weiterhin ein bestimmtes Rendering erzeugen.

Für Datenobjekte, die nie gerätespezifische Renderings bereitstellen, besteht die einfachste Implementierung dieser Methode darin, die Eingabe FORMATTC in die Ausgabe FORMATTC zu kopieren, einen NULL-Wert im PTD-Member der Ausgabe FORMATETC zu speichern und DATA_S_SAMEFORMATETC zurückzugeben.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile objidl.h

Weitere Informationen

Idataobject