Metode IDataObject::D Advise (objidl.h)

Artikel
03/15/2023

Dipanggil oleh objek yang mendukung sink saran untuk membuat koneksi antara objek data dan sink saran. Ini memungkinkan sink saran untuk diberi tahu tentang perubahan dalam data objek.

Sintaks

HRESULT DAdvise(
  [in]  FORMATETC   *pformatetc,
  [in]  DWORD       advf,
  [in]  IAdviseSink *pAdvSink,
  [out] DWORD       *pdwConnection
);

Parameter

[in] pformatetc

Penunjuk ke struktur FORMATETC yang menentukan format, perangkat target, aspek, dan media yang akan digunakan untuk pemberitahuan di masa mendatang. Misalnya, satu sink mungkin ingin mengetahui hanya ketika representasi bitmap data dalam objek data berubah. Sink lain mungkin hanya tertarik pada format metafile dari objek yang sama. Setiap sink saran diberi tahu ketika data minat berubah. Data ini diteruskan kembali ke sink saran saat pemberitahuan terjadi.

[in] advf

Sekelompok bendera untuk mengontrol koneksi penasihat. Nilai yang mungkin berasal dari enumerasi ADVF . Namun, hanya beberapa nilai ADVF yang mungkin relevan untuk metode ini. Tabel berikut ini menjelaskan secara singkat nilai yang relevan.

Nilai ADVF	Deskripsi
ADVF_NODATA	Meminta objek data untuk menghindari pengiriman data dengan pemberitahuan. Biasanya data dikirim. Bendera ini adalah cara untuk mengambil alih perilaku default. Ketika ADVF_NODATA digunakan, anggota tymed struktur STGMEDIUM yang diteruskan ke OnDataChange biasanya akan berisi TYMED_NULL. Pemanggil kemudian dapat mengambil data dengan panggilan IDataObject::GetData berikutnya.
ADVF_ONLYONCE	Menyebabkan koneksi penasihat dihancurkan setelah pemberitahuan perubahan pertama dikirim. Panggilan implisit ke IDataObject::D Unadvise dilakukan atas nama pemanggil untuk menghapus koneksi.
ADVF_PRIMEFIRST	Meminta pemberitahuan awal tambahan. Kombinasi ADVF_ONLYONCE dan ADVF_PRIMEFIRST menyediakan, berlaku, panggilan IDataObject::GetData asinkron.
ADVF_DATAONSTOP	Ketika ditentukan dengan ADVF_NODATA, bendera ini menyebabkan pemberitahuan terakhir dengan data yang disertakan dikirim sebelum objek data dihancurkan. Jika digunakan tanpa ADVF_NODATA, DAdvise dapat diimplementasikan dengan salah satu cara berikut: ADVF_DATAONSTOP dapat diabaikan. Objek dapat berulah seolah-olah ADVF_NODATA ditentukan. Pemberitahuan perubahan hanya dikirim dalam kasus penonaktifan. Perubahan data sebelum dimatikan tidak menyebabkan pemberitahuan dikirim.

[in] pAdvSink

Penunjuk ke antarmuka IAdviseSink pada sink penasihat yang akan menerima pemberitahuan perubahan.

[out] pdwConnection

Token yang mengidentifikasi koneksi ini. Anda dapat menggunakan token ini nanti untuk menghapus koneksi penasihat (dengan meneruskannya ke IDataObject::D Unadvise). Jika nilai ini adalah 0, koneksi tidak dibuat.

Nilai kembali

Metode ini mengembalikan S_OK pada keberhasilan. Nilai lain yang mungkin termasuk yang berikut ini.

Menampilkan kode	Deskripsi
E_NOTIMPL	Metode ini tidak diimplementasikan pada objek data.
DV_E_LINDEX	Nilai untuk lindex tidak valid; saat ini, hanya -1 yang didukung.
DV_E_FORMATETC	Nilai untuk pformatetc tidak valid.
OLE_E_ADVISENOTSUPPORTED	Objek data tidak mendukung pemberitahuan perubahan.

Keterangan

DAdvise membuat koneksi pemberitahuan perubahan antara objek data dan pemanggil. Pemanggil menyediakan sink penasihat tempat pemberitahuan dapat dikirim saat data objek berubah.

Objek yang digunakan hanya untuk transfer data biasanya tidak mendukung pemberitahuan saran dan mengembalikan OLE_E_ADVISENOTSUPPORTED dari DAdvise.

Catatan untuk Penelepon

Objek yang mendukung sink saran memanggil DAdvise untuk menyiapkan koneksi, menentukan format, aspek, sedang, dan/atau perangkat target yang menarik dalam struktur FORMATETC yang diteruskan. Jika objek data tidak mendukung satu atau beberapa atribut yang diminta atau pengiriman pemberitahuan sama sekali, objek data dapat menolak koneksi dengan mengembalikan OLE_E_ADVISENOTSUPPORTED.

Kontainer objek tertaut dapat mengatur koneksi saran secara langsung dengan sumber tautan terikat atau secara tidak langsung melalui objek tautan OLE standar yang mengelola koneksi. Connections disiapkan dengan sumber tautan terikat tidak dihapus secara otomatis. Kontainer harus secara eksplisit memanggil IDataObject::D Unadvise pada sumber tautan terikat untuk menghapus koneksi saran. Objek tautan OLE, dimanipulasi melalui antarmuka IOleLink , diimplementasikan dalam handler default. Connections disiapkan melalui objek tautan OLE dihancurkan saat objek tautan dihapus.

Objek tautan default OLE membuat "saran kartubebas" dengan sumber tautan sehingga OLE dapat mempertahankan waktu perubahan terakhir. Saran ini secara khusus digunakan untuk mencatat waktu bahwa apa pun berubah. OLE mengabaikan semua format data yang mungkin telah berubah, bukan hanya waktu perubahan terakhir. Untuk mengizinkan saran kartubebas, atur anggota FORMATETC sebagai berikut sebelum memanggil DAdvise:

cf == 0; 
ptd == NULL; 
dwAspect == -1; 
lindex == -1 
tymed == -1;

Bendera saran juga harus menyertakan ADVF_NODATA. Wildcard menyarankan dari OLE harus selalu diterima oleh aplikasi.

Catatan untuk Pelaksana

Untuk menyederhanakan implementasi DAdvise dan metode pemberitahuan lainnya di IDataObject (DUnadvise dan EnumDAdvise) yang mendukung pemberitahuan, OLE menyediakan objek pemegang saran yang mengelola pendaftaran dan pengiriman pemberitahuan. Untuk mendapatkan penunjuk ke objek ini, panggil fungsi pembantu CreateDataAdviseHolder pada pemanggilan pertama DAdvise. Ini memasok pointer ke antarmuka IDataAdviseHolder objek. Kemudian, delegasikan panggilan ke metode IDataAdviseHolder::Advise di pemegang saran data, yang membuat, dan kemudian mengelola, koneksi yang diminta.

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