Fungsi WdfWaitLockAcquire (wdfsync.h)

Artikel
02/27/2024

[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.

Waktu kedaluwarsa relatif tidak dipengaruhi oleh perubahan apa pun pada waktu sistem yang mungkin terjadi dalam periode waktu habis yang ditentukan. Waktu kedaluwarsa absolut mencerminkan perubahan waktu sistem.

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
STATUS_SUCCESS	Penelepon telah memperoleh kunci tunggu.
STATUS_TIMEOUT	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)

Lihat juga

KeEnterCriticalRegion

WdfWaitLockBuat

WdfWaitLockRelease

Share via