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 |
|---|---|
|
Die zurückgegebene FORMATTC-Struktur unterscheidet sich von der, die übergeben wurde. |
|
Die FORMATETC-Strukturen sind identisch, und NULL wird in pformatetcOut zurückgegeben. |
|
Der Wert für lindex ist ungültig. derzeit wird nur -1 unterstützt. |
|
Der Wert für pformatetc ist ungültig. |
|
Die Objektanwendung wird nicht ausgeführt. |
|
Ein unerwarteter Fehler ist aufgetreten. |
|
Der dwDirection-Parameter ist ungültig. |
|
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 |