Metode IDataObject::GetCanonicalFormatEtc (objidl.h)

  • Artikel

Menyediakan struktur FORMATETC yang berpotensi berbeda tetapi setara secara logis. Anda menggunakan metode ini untuk menentukan apakah dua struktur FORMATETC yang berbeda akan mengembalikan data yang sama, menghapus kebutuhan akan penyajian duplikat.

Sintaks

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

Parameter

[in] pformatectIn

Penunjuk ke struktur FORMATETC yang menentukan format, sedang, dan perangkat target yang ingin digunakan pemanggil untuk mengambil data dalam panggilan berikutnya seperti IDataObject::GetData. Anggota tymed tidak signifikan dalam kasus ini dan harus diabaikan.

[out] pformatetcOut

Penunjuk ke struktur FORMATETC yang berisi informasi paling umum yang mungkin untuk penyajian tertentu, membuatnya secara kanonis setara dengan pformatetcIn. Pemanggil harus mengalokasikan struktur ini dan metode GetCanonicalFormatEtc harus mengisi data. Untuk mengambil data dalam panggilan berikutnya seperti IDataObject::GetData, pemanggil menggunakan nilai pformatetcOut yang ditentukan, kecuali nilai yang ditentukan adalah NULL. Nilai ini adalah NULL jika metode mengembalikan DATA_S_SAMEFORMATETC. Anggota tymed tidak signifikan dalam kasus ini dan harus diabaikan.

Nilai kembali

Metode ini dapat mengembalikan nilai berikut.

Menampilkan kode Deskripsi
S_OK
 Struktur FORMATETC yang dikembalikan berbeda dari struktur yang diteruskan.
DATA_S_SAMEFORMATETC
 Struktur FORMATETC sama dan NULL dikembalikan dalam pformatetcOut.
DV_E_LINDEX
 Nilai untuk lindex tidak valid; saat ini, hanya -1 yang didukung.
DV_E_FORMATETC
 Nilai untuk pformatetc tidak valid.
OLE_E_NOTRUNNING
 Aplikasi objek tidak berjalan.
E_UNEXPECTED
 Terjadi kesalahan tidak terduga.
E_INVALIDARG
 Parameter dwDirection tidak valid.
E_OUTOFMEMORY
 Tidak tersedia cukup memori untuk operasi ini.

Keterangan

Jika objek data dapat menyediakan data yang sama persis untuk lebih dari satu struktur FORMATETC yang diminta, GetCanonicalFormatEtc dapat menyediakan "kanonis", atau FORMATETC standar yang memberikan penyajian yang sama dengan sekumpulan struktur FORMATETC yang lebih rumit. Misalnya, biasanya data yang dikembalikan tidak sensitif terhadap perangkat target yang ditentukan dalam salah satu set struktur FORMATETC yang serupa.

Catatan untuk Penelepon

Panggilan ke metode ini dapat menentukan apakah dua panggilan ke IDataObject::GetData pada objek data, menentukan dua struktur FORMATETC yang berbeda, sebenarnya akan menghasilkan penyajian yang sama, sehingga menghilangkan kebutuhan untuk panggilan kedua dan meningkatkan performa. Jika panggilan ke GetCanonicalFormatEtc menghasilkan format kanonis yang ditulis ke parameter pformatetcOut , pemanggil kemudian menggunakan struktur tersebut dalam panggilan berikutnya ke IDataObject::GetData.

Catatan untuk Pelaksana

Secara konseptual, dimungkinkan untuk memikirkan struktur FORMATETC dalam grup yang ditentukan oleh FORMATETC kanonis yang memberikan hasil yang sama dengan masing-masing anggota grup. Dalam membangun FORMATETC kanonis, Anda harus memastikannya berisi informasi paling umum yang masih menghasilkan penyajian tertentu.

Untuk objek data yang tidak pernah menyediakan penyajian khusus perangkat, implementasi paling sederhana dari metode ini adalah menyalin FORMATETC input ke FORMATETC output, menyimpan NULL di anggota ptd dari FORMATETC output, dan mengembalikan DATA_S_SAMEFORMATETC.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung Windows 2000 Server [hanya aplikasi desktop]
Target Platform Windows
Header objidl.h

Lihat juga

IDataObject