Metode IOleObject::D oVerb (oleidl.h)

Artikel
03/15/2023

Meminta agar objek melakukan tindakan sebagai respons terhadap tindakan pengguna akhir. Tindakan yang mungkin dijumlahkan untuk objek di IOleObject::EnumVerbs.

Sintaks

HRESULT DoVerb(
  [in] LONG           iVerb,
  [in] LPMSG          lpmsg,
  [in] IOleClientSite *pActiveSite,
  [in] LONG           lindex,
  [in] HWND           hwndParent,
  [in] LPCRECT        lprcPosRect
);

Parameter

[in] iVerb

Angka yang ditetapkan ke kata kerja dalam struktur OLEVERB yang dikembalikan oleh IOleObject::EnumVerbs.

[in] lpmsg

Penunjuk ke struktur MSG yang menjelaskan peristiwa (seperti klik ganda) yang memanggil kata kerja. Penelepon harus melewati struktur MSG yang tidak dimodifikasi, tanpa mencoba menafsirkan atau mengubah nilai anggota struktur mana pun.

[in] pActiveSite

Arahkan ke antarmuka IOleClientSite di situs klien aktif objek, tempat peristiwa terjadi yang memanggil kata kerja.

[in] lindex

Parameter ini dicadangkan dan harus nol.

[in] hwndParent

Handel jendela dokumen yang berisi objek . Ini dan lprcPosRect bersama-sama memungkinkan untuk membuka jendela sementara untuk objek, di mana hwndParent adalah jendela induk di mana jendela objek akan ditampilkan, dan lprcPosRect menentukan area yang tersedia untuk menampilkan jendela objek dalam induk tersebut. Jendela sementara berguna, misalnya, ke objek multimedia yang terbuka sendiri untuk pemutaran tetapi tidak untuk pengeditan.

[in] lprcPosRect

Arahkan ke struktur RECT yang berisi koordinat, dalam piksel, yang menentukan persegi panjang pembatas objek di hwndParent. Ini dan hwndParent bersama-sama memungkinkan pembukaan objek multimedia untuk pemutaran tetapi tidak untuk pengeditan.

Nilai kembali

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

Menampilkan kode	Deskripsi
OLE_E_NOT_INPLACEACTIVE	iVerb diatur ke OLEIVERB_UIACTIVATE atau OLEIVERB_INPLACEACTIVATE dan objek belum terlihat.
OLE_E_CANT_BINDTOSOURCE	Penangan objek atau objek tautan tidak dapat tersambung ke sumber tautan.
DV_E_LINDEX	Lindex tidak valid.
OLEOBJ_S_CANNOT_DOVERB_NOW	Kata kerja valid, tetapi dalam status objek saat ini tidak dapat melakukan tindakan yang sesuai.
OLEOBJ_S_INVALIDHWND	DoVerb berhasil tetapi hwndParent tidak valid.
OLEOBJ_E_NOVERBS	Objek tidak mendukung kata kerja apa pun.
OLEOBJ_S_INVALIDVERB	Sumber tautan berada di seluruh jaringan yang tidak tersambung ke kandar pada komputer ini.
MK_E_CONNECT	Sumber tautan berada di seluruh jaringan yang tidak tersambung ke kandar pada komputer ini.
OLE_E_CLASSDIFF	Kelas untuk sumber tautan telah mengalami konversi.
E_NOTIMPL	Objek tidak mendukung aktivasi di tempat atau tidak mengenali angka kata kerja negatif.

Keterangan

"Kata kerja" adalah tindakan yang diambil objek OLE sebagai respons terhadap pesan dari kontainernya. Kontainer objek, atau klien yang ditautkan ke objek, biasanya memanggil IOleObject::D oVerb sebagai respons terhadap beberapa tindakan pengguna akhir, seperti mengklik dua kali pada objek. Berbagai tindakan yang tersedia untuk objek tertentu dijumlahkan dalam struktur OLEVERB , yang diperoleh kontainer dengan memanggil IOleObject::EnumVerbs. IOleObject::D oVerb cocok dengan nilai iVerb dengan anggota iVerb struktur untuk menentukan kata kerja mana yang akan dipanggil.

Melalui IOleObject::EnumVerbs, objek, bukan kontainernya, menentukan kata kerja mana (yaitu, tindakan) yang didukungnya. OLE 2 mendefinisikan tujuh kata kerja yang tersedia, tetapi tidak selalu berguna, untuk semua objek. Selain itu, setiap objek dapat menentukan kata kerja tambahan yang unik untuk itu. Tabel berikut ini menjelaskan kata kerja yang ditentukan oleh OLE.

Kata kerja	Deskripsi
OLEIVERB_PRIMARY (0L)	Menentukan tindakan yang terjadi ketika pengguna akhir mengklik dua kali objek dalam kontainernya. Objek, bukan kontainer, menentukan tindakan ini. Jika objek mendukung aktivasi di tempat, kata kerja utama biasanya mengaktifkan objek di tempatnya.
OLEIVERB_SHOW (-1)	Menginstruksikan objek untuk menampilkan dirinya sendiri untuk pengeditan atau tampilan. Dipanggil untuk menampilkan objek yang baru disisipkan untuk pengeditan awal dan untuk memperlihatkan sumber tautan. Biasanya alias untuk beberapa kata kerja lain yang ditentukan objek.
OLEIVERB_OPEN (-2)	Menginstruksikan objek, termasuk objek yang mendukung aktivasi di tempat, untuk membuka dirinya sendiri untuk pengeditan di jendela yang terpisah dari kontainernya. Jika objek tidak mendukung aktivasi di tempat, kata kerja ini memiliki semantik yang sama dengan OLEIVERB_SHOW.
OLEIVERB_HIDE (-3)	Menyebabkan objek menghapus antarmuka penggunanya dari tampilan. Hanya berlaku untuk objek yang diaktifkan di tempat.
OLEIVERB_UIACTIVATE (-4)	Mengaktifkan objek di tempat, bersama dengan set lengkap alat antarmuka pengguna, termasuk menu, toolbar, dan namanya di bilah judul jendela kontainer. Jika objek tidak mendukung aktivasi di tempat, objek harus mengembalikan E_NOTIMPL.
OLEIVERB_INPLACEACTIVATE (-5)	Mengaktifkan objek di tempat tanpa menampilkan alat, seperti menu dan toolbar, yang diperlukan pengguna akhir untuk mengubah perilaku atau tampilan objek. Mengklik tunggal objek seperti itu menyebabkannya menegosiasikan tampilan alat antarmuka penggunanya dengan kontainernya. Jika kontainer menolak, objek tetap aktif tetapi tanpa alatnya ditampilkan.
OLEIVERB_DISCARDUNDOSTATE (-6)	Digunakan untuk memberi tahu objek untuk membuang status batalkan yang mungkin mereka pertahankan tanpa menonaktifkan objek.

Catatan untuk Penelepon

Kontainer memanggil IOleObject::D oVerb sebagai bagian dari menginisialisasi objek yang baru dibuat. Sebelum melakukan panggilan, kontainer harus terlebih dahulu memanggil IOleObject::SetClientSite untuk memberi tahu objek lokasi tampilannya dan IOleObject::SetHostNames untuk memperingatkan objek bahwa itu adalah objek yang disematkan dan untuk memicu perubahan yang sesuai pada antarmuka pengguna aplikasi objek sebagai persiapan untuk membuka jendela pengeditan.

IOleObject::D oVerb secara otomatis menjalankan aplikasi server OLE. Jika terjadi kesalahan selama eksekusi kata kerja, aplikasi objek dimatikan.

Jika pengguna akhir memanggil kata kerja dengan beberapa cara selain memilih perintah dari menu (misalnya, dengan mengklik dua kali atau, lebih jarang, mengklik satu objek), kontainer objek harus meneruskan penunjuk ke struktur MSG Windows yang berisi pesan yang sesuai. Misalnya, jika pengguna akhir memanggil kata kerja dengan mengklik dua kali objek, kontainer harus melewati struktur MSG yang berisi WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, atau WM_RBUTTONDBLCLK. Jika kontainer tidak meneruskan pesan, lpmsg harus diatur ke NULL. Objek harus mengabaikan anggota hwnd dari struktur MSG yang dilewatkan, tetapi dapat menggunakan semua anggota MSG lainnya.

Jika kontainer penyematan objek memanggil IOleObject::D oVerb, penunjuk situs klien (pClientSite) yang diteruskan ke IOleObject::D oVerb sama dengan situs penyematan. Jika objek yang disematkan adalah sumber tautan, penunjuk yang diteruskan ke IOleObject::D oVerb adalah dari situs klien klien penautan.

Ketika IOleObject::D oVerb dipanggil pada tautan OLE, IOleObject dapat mengembalikan OLE_E_CLASSDIFF atau MK_CONNECTMANUALLY. Objek tautan mengembalikan kesalahan sebelumnya ketika sumber tautan telah mengalami semacam konversi saat tautan pasif. Objek tautan mengembalikan kesalahan terakhir ketika sumber tautan terletak di drive jaringan yang saat ini tidak tersambung ke komputer pemanggil. Satu-satunya cara untuk menyambungkan tautan dalam kondisi ini adalah dengan terlebih dahulu memanggil IUnknown::QueryInterface, meminta IOleLink, mengalokasikan konteks ikatan, dan menjalankan sumber tautan dengan memanggil IOleLink::BindToSource.

Aplikasi kontainer yang tidak mendukung aktivasi di tempat umum masih dapat menggunakan parameter hwndParent dan lprcPosRect untuk mendukung pemutaran file multimedia di tempat. Kontainer harus meneruskan parameter hwndParent dan lprcPosRect yang valid ke IOleObject::D oVerb.

Beberapa sampel kode meneruskan nilai lindex -1, bukan nol. Nilai -1 berfungsi tetapi harus dihindari demi nol. Parameter lindex adalah parameter yang dipesan, dan karena alasan konsistensi, Microsoft merekomendasikan untuk menetapkan nilai nol ke semua parameter yang dipesan.

Catatan untuk Pelaksana

Selain kata kerja di atas, objek dapat menentukan dalam struktur OLEVERB kata kerja tambahan yang khusus untuk dirinya sendiri. Angka positif menunjuk kata kerja khusus objek ini. Objek harus memperlakukan nomor kata kerja positif yang tidak diketahui seolah-olah itu adalah kata kerja utama dan mengembalikan OLEOBJ_S_INVALIDVERB ke fungsi panggilan. Objek harus mengabaikan kata kerja dengan angka negatif yang tidak dikenali dan mengembalikan E_NOTIMPL.

Jika kata kerja yang dijalankan menempatkan objek dalam status berjalan, Anda harus mendaftarkan objek dalam tabel objek yang sedang berjalan (ROT) bahkan jika aplikasi servernya tidak mendukung penautan. Pendaftaran penting karena objek pada titik tertentu dapat berfungsi sebagai sumber tautan dalam kontainer yang mendukung tautan ke penyematan. Mendaftarkan objek dengan ROT memungkinkan klien tautan untuk mendapatkan penunjuk ke objek secara langsung, alih-alih harus melalui kontainer objek. Untuk melakukan pendaftaran, panggil IOleClientSite::GetMoniker untuk mendapatkan moniker penuh objek, panggil fungsi GetRunningObjectTable untuk mendapatkan penunjuk ke ROT, lalu panggil IRunningObjectTable::Register.

Catatan Ketika objek meninggalkan status berjalan, ingatlah untuk mencabut pendaftaran objek dengan ROT dengan memanggil IOleObject::Close. Jika dokumen kontainer objek diganti namanya saat objek sedang berjalan, Anda harus mencabut pendaftaran objek dan mendaftarkannya kembali dengan ROT, menggunakan nama barunya. Kontainer harus menginformasikan objek moniker barunya baik dengan memanggil IOleObject::SetMoniker atau dengan menanggapi panggilan objek IOleClientSite::GetMoniker.

Saat menampilkan jendela sebagai hasil dari IOleObject::D oVerb, sangat penting bagi objek untuk secara eksplisit memanggil SetForegroundWindow pada jendela pengeditannya. Ini memastikan bahwa jendela objek akan terlihat oleh pengguna bahkan jika proses lain awalnya mengaburkannya. Untuk informasi selengkapnya, lihat SetForegroundWindow dan SetActiveWindow.

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	oleidl.h