Metodo IDataObject::GetCanonicalFormatEtc (objidl.h)

  • Articolo

Fornisce una struttura FORMATETC potenzialmente diversa ma logicamente equivalente. Questo metodo consente di determinare se due strutture FORMATETC diverse restituiscono gli stessi dati, eliminando la necessità di eseguire il rendering duplicato.

Sintassi

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

Parametri

[in] pformatectIn

Puntatore alla struttura FORMATETC che definisce il formato, il supporto e il dispositivo di destinazione che il chiamante desidera utilizzare per recuperare i dati in una chiamata successiva, ad esempio IDataObject::GetData. Il membro tymed non è significativo in questo caso e deve essere ignorato.

[out] pformatetcOut

Puntatore a una struttura FORMATETC che contiene le informazioni più generali possibili per un rendering specifico, rendendolo in modo canonico equivalente a pformatetcIn. Il chiamante deve allocare questa struttura e il metodo GetCanonicalFormatEtc deve compilare i dati. Per recuperare i dati in una chiamata successiva, ad esempio IDataObject::GetData, il chiamante usa il valore specificato di pformatetcOut, a meno che il valore specificato non sia NULL. Questo valore è NULL se il metodo restituisce DATA_S_SAMEFORMATETC. Il membro tymed non è significativo in questo caso e deve essere ignorato.

Valore restituito

Questo metodo può restituire i valori seguenti.

Codice restituito Descrizione
S_OK
 La struttura FORMATETC restituita è diversa da quella passata.
DATA_S_SAMEFORMATETC
 Le strutture FORMATETC sono uguali e NULL viene restituito in pformatetcOut.
DV_E_LINDEX
 Il valore per lindex non è valido; attualmente è supportato solo -1.
DV_E_FORMATETC
 Il valore per pformatetc non è valido.
OLE_E_NOTRUNNING
 L'applicazione oggetto non è in esecuzione.
E_UNEXPECTED
 Si è verificato un errore imprevisto.
E_INVALIDARG
 Il parametro dwDirection non è valido.
E_OUTOFMEMORY
 Memoria insufficiente disponibile per questa operazione.

Commenti

Se un oggetto dati può fornire esattamente gli stessi dati per più di una struttura FORMATETC richiesta, GetCanonicalFormatEtc può fornire un oggetto FORMATETC "canonico" o standard che fornisce lo stesso rendering di un set di strutture FORMATETC più complesse. Ad esempio, è comune che i dati restituiti non siano sensibili al dispositivo di destinazione specificato in uno qualsiasi di un set di strutture FORMATETC altrimenti simili.

Note ai chiamanti

Una chiamata a questo metodo può determinare se due chiamate a IDataObject::GetData su un oggetto dati, specificando due strutture FORMATETC diverse, produrrebbero effettivamente gli stessi rendering, eliminando così la necessità della seconda chiamata e migliorando le prestazioni. Se la chiamata a GetCanonicalFormatEtc restituisce un formato canonico scritto nel parametro pformatetcOut , il chiamante usa tale struttura in una chiamata successiva a IDataObject::GetData.

Note per gli implementatori

Concettualmente, è possibile considerare le strutture FORMATETC in gruppi definiti da un FORMATETC canonico che fornisce gli stessi risultati di ognuno dei membri del gruppo. Nella costruzione del formato canonico FORMATETC, è necessario assicurarsi che contenga le informazioni più generali possibili che producono comunque un rendering specifico.

Per gli oggetti dati che non forniscono mai rendering specifici del dispositivo, l'implementazione più semplice di questo metodo consiste nel copiare l'input FORMATETC nell'output FORMATETC, archiviare un valore NULL nel membro ptd dell'output FORMATETC e restituire DATA_S_SAMEFORMATETC.

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

Vedi anche

Idataobject