Metode ILockBytes::LockRegion (objidl.h)

Artikel
03/05/2024

Metode LockRegion membatasi akses ke rentang byte tertentu dalam array byte.

Sintaks

HRESULT LockRegion(
  [in] ULARGE_INTEGER libOffset,
  [in] ULARGE_INTEGER cb,
  [in] DWORD          dwLockType
);

Parameter

[in] libOffset

Menentukan offset byte untuk awal rentang.

[in] cb

Menentukan, dalam byte, panjang rentang yang akan dibatasi.

[in] dwLockType

Menentukan jenis pembatasan yang diminta untuk mengakses rentang. Parameter ini menggunakan salah satu nilai dari enumerasi LOCKTYPE .

Nilai kembali

Metode ini dapat mengembalikan salah satu nilai ini.

Menampilkan kode	Deskripsi
S_OK	Rentang byte yang ditentukan dikunci.
STG_E_INVALIDFUNCTION	Penguncian tidak didukung sama sekali atau jenis kunci tertentu yang diminta tidak didukung.
STG_E_ACCESSDENIED	Akses ditolak karena penelepon tidak memiliki izin yang cukup, atau pemanggil lain membuka dan mengunci file.
STG_E_LOCKVIOLATION	Akses ditolak karena penelepon lain membuka dan mengunci file.
STG_E_INVALIDHANDLE	File yang mendasarinya telah ditutup sebelum waktunya, atau disket yang benar telah digantikan oleh disket yang tidak valid.

Keterangan

ILockBytes::LockRegion membatasi akses ke rentang byte yang ditentukan. Setelah wilayah dikunci, upaya orang lain untuk mendapatkan akses ke rentang terbatas harus gagal dengan kesalahan STG_E_ACCESSDENIED.

Rentang byte dapat meluas melewati akhir array byte saat ini. Penguncian di luar akhir array berguna sebagai metode komunikasi antara instans yang berbeda dari objek array byte tanpa mengubah data yang sebenarnya merupakan bagian dari array byte. Misalnya, implementasi ILockBytes untuk file campuran dapat mengandalkan penguncian melewati akhir array saat ini sebagai sarana kontrol akses, menggunakan wilayah terkunci tertentu untuk menunjukkan izin yang saat ini diberikan.

Parameter dwLockType menentukan salah satu dari tiga jenis penguncian, menggunakan nilai dari enumerasi LOCKTYPE . Jenisnya adalah sebagai berikut: mengunci untuk mengecualikan penulis lain, mengunci untuk mengecualikan pembaca atau penulis lain, dan penguncian yang hanya memungkinkan satu pemohon untuk mendapatkan kunci pada rentang yang diberikan. Jenis penguncian ketiga ini biasanya merupakan alias untuk salah satu dari dua jenis kunci lainnya, dan mengizinkan Pelaksana untuk menambahkan perilaku lain juga. Array byte tertentu mungkin mendukung salah satu dari dua jenis pertama, atau keduanya.

Untuk menentukan jenis kunci yang didukung oleh implementasi ILockBytes tertentu, Anda dapat memeriksa anggota struktur STATSTGyang didukung grfLocksSupported yang dikembalikan oleh panggilan ke ILockBytes::Stat.

Setiap wilayah yang dikunci dengan ILockBytes::LockRegion nantinya harus dibuka secara eksplisit dengan memanggil ILockBytes::UnlockRegion dengan nilai yang sama persis untuk parameter libOffset, cb, dan dwLockType . Wilayah harus dibuka kuncinya sebelum aliran dirilis. Dua wilayah yang berdekatan tidak dapat dikunci secara terpisah dan kemudian dibuka dengan satu panggilan buka kunci.

Catatan untuk Penelepon

Karena jenis penguncian yang didukung bersifat opsional dan dapat bervariasi dalam implementasi ILockBytes yang berbeda, Anda harus memberikan kode untuk menangani kesalahan STG_E_INVALIDFUNCTION.

Catatan untuk Pelaksana

Dukungan untuk metode ini tergantung pada bagaimana objek penyimpanan yang dibangun di atas implementasi ILockBytes digunakan. Jika Anda tahu bahwa hanya satu objek penyimpanan pada waktu tertentu yang dapat dibuka pada perangkat penyimpanan yang mendasar array byte, maka implementasi ILockBytes Anda tidak perlu mendukung penguncian. Namun, jika beberapa bukaan simultan objek penyimpanan dimungkinkan, maka penguncian wilayah diperlukan untuk mengoordinasikannya.

Implementasi LockRegion dapat memilih untuk mendukung semua, beberapa, atau tidak ada jenis kunci. Untuk jenis kunci yang tidak didukung, implementasi harus mengembalikan STG_E_INVALIDFUNCTION.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows 2000 Server [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	objidl.h
Pustaka	Uuid.lib
DLL	Ole32.dll