Fungsi CmCallbackGetKeyObjectIDEx (wdm.h)

Artikel
03/08/2023

Rutinitas CmCallbackGetKeyObjectIDEx mengambil pengidentifikasi unik dan nama objek yang terkait dengan objek kunci registri tertentu.

Rutinitas ini tersedia dimulai dengan Windows 8. Di versi Windows yang lebih lama, gunakan rutinitas CmCallbackGetKeyObjectID sebagai gantinya. Untuk informasi selengkapnya, lihat bagian Keterangan di bawah ini.

Sintaks

NTSTATUS CmCallbackGetKeyObjectIDEx(
  [in]            PLARGE_INTEGER   Cookie,
  [in]            PVOID            Object,
  [out, optional] PULONG_PTR       ObjectID,
  [out, optional] PCUNICODE_STRING *ObjectName,
  [in]            ULONG            Flags
);

Parameter

[in] Cookie

Nilai cookie yang mewakili pendaftaran penelepon untuk menerima panggilan balik filter registri. Driver sebelumnya mendapatkan nilai cookie ini dari rutinitas CmRegisterCallback atau CmRegisterCallbackEx .

[in] Object

Penunjuk ke objek kunci registri. Parameter ini adalah nilai pointer yang diterima rutinitas panggilan balik RegistryCallback driver di anggota Object dari salah satu struktur REG_XXX_KEY_INFORMATION .

Peringatan

Dalam keadaan tertentu, struktur pemberitahuan panggilan balik registri mungkin berisi penunjuk objek non-NULL yang tidak valid. Driver pemfilteran registri tidak boleh meneruskan penunjuk tersebut ke rutinitas ini. Untuk informasi selengkapnya, lihat Penunjuk Objek Kunci Tidak Valid di Pemberitahuan Registri.

[out, optional] ObjectID

Penunjuk ke lokasi yang menerima penunjuk ke pengidentifikasi kunci untuk kunci registri yang diwakili Objek . Pengidentifikasi ini unik di semua kunci dalam registri. Parameter ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya, lihat bagian Keterangan di bawah ini..

[out, optional] ObjectName

Penunjuk ke lokasi yang menerima penunjuk ke struktur UNICODE_STRING . Struktur ini berisi nama objek objek kunci registri yang ditentukan Objek . Nama objek sebenarnya adalah nama jalur lengkap dari kunci registri yang diwakili objek. Pemanggil bertanggung jawab untuk membebaskan struktur ini dengan memanggil rutinitas CmCallbackReleaseKeyObjectIDEx . Parameter ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya, lihat Keterangan.

[in] Flags

Dicadangkan. Atur ke nol.

Nilai kembali

CmCallbackGetKeyObjectIDEx mengembalikan STATUS_SUCCESS jika operasi berhasil. Kemungkinan nilai pengembalian kesalahan mencakup kode status berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter Cookie, Objek, atau Bendera tidak valid.

Keterangan

Driver dapat menggunakan CmCallbackGetKeyObjectIDEx untuk mendapatkan pengidentifikasi kunci registri, nama objek, atau keduanya, dengan menyediakan nilai non-NULL untuk parameter ObjectID atau ObjectName .

Pemanggil dapat memperoleh pengidentifikasi kunci melalui parameter ObjectID . Jika dua objek kunci registri mewakili kunci registri yang sama, pengidentifikasi kunci yang diperoleh dari CmCallbackGetKeyObjectIDEx untuk dua objek tersebut identik. Jika nama kunci registri berubah, pengidentifikasi kunci yang diperoleh dari CmCallbackGetKeyObjectIDEx tidak berubah. Pemanggil dapat menggunakan pengidentifikasi kunci untuk melacak akses yang dibuat dengan andal ke kunci registri tertentu melalui beberapa objek kunci, dan bahkan di seluruh perubahan pada nama kunci registri.

Pemanggil dapat memperoleh nama objek melalui parameter ObjectName . Penyimpanan untuk struktur UNICODE_STRING yang berisi nama objek tetap valid sampai pemanggil memanggil CmCallbackReleaseKeyObjectIDEx untuk membebaskan struktur.

CmCallbackGetKeyObjectIDEx adalah versi yang ditingkatkan dari rutinitas CmCallbackGetKeyObjectID , yang tersedia dimulai dengan Windows Vista. Driver yang berjalan di versi Windows yang lebih lama dari Windows 8 harus memanggil CmCallbackGetKeyObjectID alih-alih CmCallbackGetKeyObjectIDEx. Driver yang hanya berjalan di Windows 8 dan versi Windows yang lebih baru harus memanggil CmCallbackGetKeyObjectIDEx alih-alih CmCallbackGetKeyObjectID.

CmCallbackGetKeyObjectIDEx memiliki dua fitur penting yang tidak tersedia dari CmCallbackGetKeyObjectID.

Pertama, CmCallbackGetKeyObjectIDEx memungkinkan driver filter registri untuk secara eksplisit mengontrol masa pakai struktur ObjectName . Driver dapat memanggil CmCallbackReleaseKeyObjectIDEx kapan saja untuk membebaskan struktur ini. Sebaliknya, driver tidak dapat secara eksplisit membebaskan struktur ObjectName yang diterima dari CmCallbackGetKeyObjectID. Struktur ini secara otomatis dirilis ketika semua handel ke kunci ditutup.

Kedua, jika driver filter registri memanggil CmCallbackReleaseKeyObjectID untuk mendapatkan penunjuk struktur ObjectName , dan, setelah panggilan ini, nama kunci registri berubah, panggilan berikutnya ke CmCallbackGetKeyObjectID mendapatkan penunjuk ke salinan basi struktur ObjectName , yang berisi nama kunci lama. Salinan kedaluarsa struktur ini bertahan sampai semua handel ke kunci ditutup. Sebaliknya, struktur ObjectName yang diperoleh dari CmCallbackGetKeyObjectIDEx selalu berisi nama kunci terbaru.

Untuk informasi selengkapnya tentang driver filter registri, lihat Memfilter Panggilan Registri.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 8.
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL