Fungsi WdfWaitLockAcquire (wdfsync.h)
[Berlaku untuk KMDF dan UMDF]
Metode WdfWaitLockAcquire memperoleh kunci tunggu yang ditentukan.
Sintaks
NTSTATUS WdfWaitLockAcquire(
[in] WDFWAITLOCK Lock,
[in, optional] PLONGLONG Timeout
);
Parameter
[in] Lock
Handel ke objek kunci tunggu kerangka kerja, yang diperoleh oleh panggilan sebelumnya ke WdfWaitLockCreate.
[in, optional] Timeout
Penunjuk opsional ke nilai waktu habis. Nilai waktu habis ditentukan dalam unit waktu sistem (interval 100 nanodetik).
Jika penunjuk bukan NULL, kerangka kerja membatalkan upaya untuk mendapatkan kunci jika tidak selesai dalam periode waktu habis yang ditentukan. Nilai waktu habis bisa negatif, positif, atau nol, sebagai berikut:
- Jika nilai waktu habis negatif, waktu kedaluwarsa relatif terhadap waktu sistem saat ini.
- Jika nilai waktu habis positif, waktu kedaluwarsa ditentukan sebagai waktu absolut (yang sebenarnya relatif terhadap 1 Januari 1601).
- Jika nilai waktu habis adalah nol, WdfWaitLockAcquire mencoba memperoleh kunci dan kemudian segera kembali, apakah telah memperoleh kunci atau tidak.
Kerangka kerja menyediakan fungsi konversi waktu yang mengonversi nilai waktu menjadi unit waktu sistem.
Jika penelepon memasok pointer NULL , metode menunggu tanpa batas waktu sampai memperoleh kunci.
Nilai kembali
WdfWaitLockAcquire dapat mengembalikan nilai NTSTATUS berikut:
Menampilkan kode | Deskripsi |
---|---|
|
Penelepon telah memperoleh kunci tunggu. |
|
Interval Batas waktu yang ditentukan kedaluwarsa sebelum kunci diperoleh. |
Perhatikan bahwa NT_SUCCESS(status) sama dengan TRUE untuk semua nilai status ini.
Pemanggil tidak perlu memeriksa nilai yang dikembalikan jika pointer Timeout adalah NULL, karena dalam hal ini WdfWaitLockAcquire hanya mengembalikan setelah memperoleh kunci.
Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.
Keterangan
Metode WdfWaitLockAcquire tidak kembali sampai memperoleh kunci tunggu atau sampai periode waktu habis berakhir.
WdfWaitLockAcquire memanggil KeEnterCriticalRegion sebelum memperoleh kunci tunggu. Akibatnya, ketika metode kembali, APC kernel normal dinonaktifkan. WdfWaitLockAcquire tidak mengubah IRQL penelepon.
Jika penunjuk Timeout adalah NULL, atau jika nilai waktu habis bukan nol, WdfWaitLockAcquire harus dipanggil di IRQL = PASSIVE_LEVEL.
Jika nilai waktu habis adalah nol, WdfWaitLockAcquire harus dipanggil di IRQL < DISPATCH_LEVEL. Perhatikan bahwa ini tidak setuju dengan file header (wdfsync.h), yang menunjukkan bahwa metode ini dapat dipanggil pada DISPATCH_LEVEL.
Untuk informasi selengkapnya tentang kunci tunggu, lihat Teknik Sinkronisasi untuk driver Framework-Based.
Contoh
Contoh kode berikut memperoleh kunci tunggu, menambahkan objek perangkat ke koleksi objek, dan melepaskan kunci tunggu.
WdfWaitLockAcquire(
FilterDeviceCollectionLock,
NULL
);
status = WdfCollectionAdd(
FilterDeviceCollection,
deviceHandle
);
if (!NT_SUCCESS(status)) {
addFailed = TRUE;
}
WdfWaitLockRelease(FilterDeviceCollectionLock);
Persyaratan
Persyaratan | Nilai |
---|---|
Target Platform | Universal |
Versi KMDF minimum | 1,0 |
Versi UMDF minimum | 2.0 |
Header | wdfsync.h (termasuk Wdf.h) |
Pustaka | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
IRQL | Lihat bagian Keterangan. |
Aturan kepatuhan DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), WdfWaitlock(kmdf), WdfWaitlockRelease(kmdf) |