Fungsi PcNewRegistryKey (portcls.h)
Fungsi PcNewRegistryKey membuka atau membuat kunci registri baru dan membuat objek IRegistryKey untuk mewakili kunci. Penelepon mengakses kunci melalui objek ini.
Sintaks
PORTCLASSAPI NTSTATUS PcNewRegistryKey(
[out] PREGISTRYKEY *OutRegistryKey,
[in, optional] PUNKNOWN OuterUnknown,
[in] ULONG RegistryKeyType,
[in] ACCESS_MASK DesiredAccess,
[in, optional] PVOID DeviceObject,
[in, optional] PVOID SubDevice,
[in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
[in, optional] ULONG CreateOptions,
[out, optional] PULONG Disposition
);
Parameter
[out] OutRegistryKey
Penunjuk output ke objek kunci registri yang dibuat oleh fungsi ini. Parameter ini menunjuk ke variabel penunjuk yang dialokasikan pemanggil tempat fungsi menghasilkan penunjuk ke objek IRegistryKey . Objek mewakili kunci registri yang sedang dibuka atau dibuat. Tentukan nilai pointer non-NULL yang valid untuk parameter ini.
[in, optional] OuterUnknown
Arahkan ke antarmuka IUnknown objek yang perlu mengagregasi objek OutRegistryKey . Kecuali agregasi diperlukan, atur parameter ini ke NULL.
[in] RegistryKeyType
Menentukan jenis kunci registri yang ingin dibuat atau dibuka oleh pemanggil. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
[in] DesiredAccess
Menentukan masker kontrol akses. Parameter ini adalah struktur jenis ACCESS_MASK. Ini menunjukkan jenis akses yang diminta pemanggil ke kunci registri yang akan dibuka atau dibuat. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
[in, optional] DeviceObject
Arahkan ke objek perangkat driver adaptor. Pointer ini dilemparkan untuk mengetik PVOID. Jika RegistryKeyType adalah nilai apa pun selain GeneralRegistryKey, parameter ini harus menunjuk ke struktur sistem yang valid dan diinisialisasi dari jenis DEVICE_OBJECT. Jika nilai RegistryKeyType adalah GeneralRegistryKey, fungsi PcNewRegistryKey tidak menggunakan parameter ini. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
[in, optional] SubDevice
Menentukan aspek perangkat yang akan ditawarkan kepada klien. Driver adaptor harus menetapkan nilai NULL ke parameter ini.
[in, optional] ObjectAttributes
Arahkan ke atribut objek kunci yang sedang dibuat atau dibuka. Jika RegistryKeyType memiliki nilai GeneralRegistryKey, parameter ini harus menunjuk ke struktur sistem tipe yang valid dan diinisialisasi OBJECT_ATTRIBUTES dengan string ObjectName yang valid untuk kunci; jika tidak, fungsi tidak menggunakan parameter ini. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
[in, optional] CreateOptions
Menentukan opsi buat. Bisa nol jika tidak ada yang diinginkan. Jika RegistryKeyType bukan GeneralRegistryKey, fungsi PcNewRegistryKey mengabaikan parameter ini. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
[out, optional] Disposition
Penunjuk ke variabel yang menerima nilai yang menunjukkan apakah kunci dibuat atau kunci yang ada dibuka. Parameter ini bersifat opsional dan dapat ditentukan sebagai NULL. Jika RegistryKeyType adalah nilai apa pun selain GeneralRegistryKey, fungsi PcNewRegistryKey mengabaikan parameter ini. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
Mengembalikan nilai
PcNewRegistryKey mengembalikan STATUS_SUCCESS jika panggilan berhasil. Jika tidak, kode kesalahan akan menampilkan kode kesalahan yang sesuai.
Keterangan
Jika nilai parameter RegistryKeyType adalah GeneralRegistryKey, maka fungsi PcNewRegistryKey membuka kunci yang ada atau membuat kunci baru di registri, seperti yang ditunjukkan oleh nilai yang dihasilkan fungsi melalui parameter Disposition . Jika kuncinya adalah jenis apa pun selain GeneralRegistryKey, maka fungsi membuka kunci yang sudah ada yang sebelumnya dibuat selama enumerasi perangkat Plug and Play.
Parameter DesiredAccess, ObjectAttributes, CreateOptions, dan Disposition mengambil nilai yang ditentukan untuk parameter dengan nama yang sama dalam panggilan ZwCreateKey .
Parameter RegistryKeyType harus diatur ke salah satu nilai enumerasi yang diperlihatkan dalam tabel berikut.
| Nilai RegistryKeyType | Makna |
|---|---|
| GeneralRegistryKey | Berikan akses generik ke jenis kunci apa pun. Buka kunci yang ditentukan jika sudah ada atau buat kunci jika tidak. |
| DeviceRegistryKey | Buka kunci yang ada yang berisi informasi khusus perangkat. Kunci terletak di bawah kunci untuk instans perangkat yang ditentukan oleh DeviceObject. |
| DriverRegistryKey | Buka kunci yang ada yang berisi informasi khusus driver. |
| HwProfileRegistryKey | Buka kunci yang ada relatif terhadap profil perangkat keras saat ini yang berisi informasi perangkat atau driver. Ini memungkinkan driver untuk mengakses informasi konfigurasi yang khusus untuk profil perangkat keras. |
| DeviceInterfaceRegistryKey | Tidak digunakan dengan PcNewRegistryKey. Lihat IPort::NewRegistryKey untuk detailnya. |
Untuk nilai RegistryKeyTypedari GeneralRegistryKey, pemanggil harus memberikan nilai parameter ObjectAttributes yang valid, dan parameter CreateOptions dan Disposition bersifat opsional. Untuk nilai RegistryKeyType lainnya, pemanggil harus memberikan nilai parameter DeviceObject yang valid, dan parameter CreateOptions dan Disposition tidak digunakan.
Parameter ObjectAttributes menunjuk ke struktur buram jenis OBJECT_ATTRIBUTES yang berisi atribut objek seperti nama kunci dan deskriptor keamanan. Gunakan makro InitializeObjectAttributes untuk menginisialisasi struktur. Dalam parameter Atribut untuk makro ini, atur bendera OBJ_KERNEL_HANDLE kecuali Anda berniat mengizinkan aplikasi mode pengguna yang tidak aman memiliki akses baca/tulis ke kunci registri.
Parameter DesiredAccess adalah masker kontrol akses. Ini menentukan jenis kontrol akses yang harus dimiliki pemanggil ke kunci registri baru saat mengaksesnya melalui objek OutRegistryKey . Masker ini tidak boleh dikacaukan dengan daftar kontrol akses (ACL) yang mengontrol akses oleh pengguna ke kunci registri. Saat memanggil PcNewRegistryKey untuk membuat kunci registri jenis GeneralRegistryKey, parameter ObjectAttributes menentukan atribut kunci, termasuk deskriptor keamanan yang berisi ACL. Namun, jika kunci baru berjenis GeneralRegistryKey dan penunjuk deskriptor keamanan dalam struktur ObjectAttributes adalah NULL atau penunjuk ACL dalam deskriptor keamanan adalah NULL, maka kunci baru akan mewarisi ACL kunci induk secara default.
Jika kuncinya adalah jenis apa pun selain GeneralRegistryKey, maka kunci mempertahankan ACL yang Plug and Play ditetapkan ke kunci saat dibuat selama enumerasi perangkat.
Fungsi PcNewRegistryKey mirip dengan metode IPort::NewRegistryKey kecuali bahwa objek perangkat dan objek port harus secara eksplisit ditentukan dalam panggilan PcNewRegistryKey tetapi hanya tersirat dalam panggilan NewRegistryKey . PcNewRegistryKey digunakan terutama oleh driver adaptor. Driver miniport biasanya memanggil NewRegistryKey sebagai gantinya.
Parameter OutRegistryKey dan OuterUnknown mengikuti konvensi penghitungan referensi untuk objek COM.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Driver sistem PortCls mengimplementasikan fungsi PcNewRegistryKey di Microsoft Windows 98/Me dan di sistem operasi Windows 2000 dan yang lebih baru. |
| Target Platform | Universal |
| Header | portcls.h (termasuk Portcls.h) |
| Pustaka | Portcls.lib |
| IRQL | PASSIVE_LEVEL |