Fungsi CoLockObjectExternal (combaseapi.h)

  • Artikel

Dipanggil untuk mengunci objek untuk memastikan bahwa objek tetap dalam memori, atau untuk melepaskan kunci seperti itu.

Sintaks

HRESULT CoLockObjectExternal(
  [in] LPUNKNOWN pUnk,
  [in] BOOL      fLock,
  [in] BOOL      fLastUnlockReleases
);

Parameter

[in] pUnk

Penunjuk ke antarmuka IUnknown pada objek yang akan dikunci atau dibuka kuncinya.

[in] fLock

Menunjukkan apakah objek akan dikunci atau dilepaskan. Jika parameter ini TRUE, objek disimpan dalam memori, terlepas dari operasiRilisAddRef/, pendaftaran, atau pencabutan. Jika parameter ini FALSE, kunci yang sebelumnya diatur dengan panggilan ke fungsi ini dirilis.

[in] fLastUnlockReleases

Jika kunci adalah referensi terakhir yang seharusnya menjaga objek tetap hidup, tentukan TRUE untuk melepaskan semua pointer ke objek (mungkin ada referensi lain yang seharusnya tidak membuatnya tetap hidup). Jika tidak, tentukan FALSE.

Jika fLockTRUE, parameter ini diabaikan.

Nilai kembali

Fungsi ini dapat mengembalikan nilai pengembalian standar E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, dan S_OK.

Keterangan

Fungsi CoLockObjectExternal harus dipanggil dalam proses di mana objek benar-benar berada (proses EXE, bukan proses di mana handler dapat dimuat).

Fungsi CoLockObjectExternal mencegah jumlah referensi objek masuk ke nol, sehingga "mengunci" ke keberadaannya sampai kunci dilepaskan. Fungsi yang sama (dengan parameter yang berbeda) melepaskan kunci. Kunci diimplementasikan dengan meminta sistem memanggil IUnknown::AddRef pada objek . Sistem kemudian menunggu untuk memanggil IUnknown::Release pada objek hingga panggilan selanjutnya ke CoLockObjectExternal dengan fLock diatur ke FALSE. Fungsi ini dapat digunakan untuk mempertahankan jumlah referensi pada objek atas nama pengguna akhir, karena bertindak di luar objek, seperti halnya pengguna.

Pengguna akhir memiliki kontrol eksplisit selama masa pakai aplikasi, bahkan jika ada kunci eksternal di dalamnya. Artinya, jika pengguna memutuskan untuk menutup aplikasi, aplikasi harus dimatikan. Di hadapan kunci eksternal (seperti kunci yang diatur oleh CoLockObjectExternal), aplikasi dapat memanggil fungsi CoDisconnectObject untuk memaksa koneksi ini ditutup sebelum dimatikan.

Memanggil CoLockObjectExternal menetapkan kunci yang kuat pada objek. Kunci yang kuat menyimpan objek dalam memori, sementara kunci yang lemah tidak. Kunci yang kuat diperlukan, misalnya, selama pembaruan senyap ke penyematan OLE. Kontainer objek yang disematkan harus tetap berada dalam memori hingga proses pembaruan selesai. Juga harus ada kunci yang kuat pada objek aplikasi untuk memastikan bahwa aplikasi tetap hidup sampai selesai memberikan layanan kepada kliennya. Semua referensi eksternal menempatkan kunci referensi yang kuat pada objek.

Fungsi CoLockObjectExternal biasanya dipanggil dalam situasi berikut:

  • Server objek harus memanggil CoLockObjectExternal dengan fLock dan fLastLockReleases diatur ke TRUE saat terlihat. Panggilan ini menciptakan kunci yang kuat atas nama pengguna. Ketika aplikasi ditutup, kosongkan kunci dengan panggilan ke CoLockObjectExternal, atur fLock ke FALSE dan fLastLockReleases ke TRUE.
  • Panggilan ke CoLockObjectExternal di server juga dapat digunakan dalam implementasi IOleContainer::LockContainer.
Ada beberapa hal yang perlu diperhatikan ketika Anda menggunakan CoLockObjectExternal dalam implementasi LockContainer. Objek yang disematkan akan memanggil LockContainer pada kontainernya untuk membuatnya tetap berjalan (untuk menguncinya) tanpa adanya alasan lain untuk membuatnya tetap berjalan. Ketika objek yang disematkan menjadi terlihat, kontainer harus melemahkan koneksinya ke objek yang disematkan dengan panggilan ke fungsi OleSetContainedObject , sehingga koneksi lain dapat memengaruhi objek.

Kecuali aplikasi mengelola semua aspek aplikasi dan pematian dokumennya sepenuhnya dengan panggilan ke CoLockObjectExternal, kontainer harus menyimpan jumlah kunci privat di LockContainer sehingga keluar ketika jumlah kunci mencapai nol dan kontainer tidak terlihat. Mempertahankan semua aspek pematian, dan dengan demikian menghindari jumlah kunci privat, berarti bahwa CoLockObjectExternal harus dipanggil setiap kali salah satu kondisi berikut terjadi:

  • Dokumen dibuat dan dihancurkan atau dibuat terlihat atau tidak terlihat.
  • Aplikasi dimulai dan dimatikan oleh pengguna.
  • Objek pseudo dibuat dan dihancurkan.
Untuk tujuan penelusuran kesalahan, mungkin berguna untuk menyimpan hitungan jumlah kunci eksternal (dan membuka kunci) yang diatur pada aplikasi.

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 combaseapi.h (termasuk Objbase.h)
Pustaka Ole32.lib
DLL Ole32.dll

Lihat juga

IOleContainer::LockContainer

OleSetContainedObject