IPort::Metode NewRegistryKey (portcls.h)

Metode NewRegistryKey membuka kunci registri yang ada atau membuat kunci baru di registri. Metode ini membuat objek kunci registri untuk mewakili kunci dan menghasilkan referensi ke objek ini ke pemanggil. Pemanggil kemudian mengakses kunci melalui antarmuka IRegistryKey objek.

Sintaks

NTSTATUS NewRegistryKey(
  PREGISTRYKEY       *OutRegistryKey,
  PUNKNOWN           OuterUnknown,
  ULONG              RegistryKeyType,
  ACCESS_MASK        DesiredAccess,
  POBJECT_ATTRIBUTES ObjectAttributes,
  ULONG              CreateOptions,
  PULONG             Disposition
);

Parameter

OutRegistryKey

Arahkan ke variabel pointer yang dialokasikan penelepon tempat metode menulis referensi ke objek IRegistryKey. Objek ini mewakili kunci registri yang sedang dibuka atau dibuat. Pemanggil harus menentukan nilai penunjuk non-NULL yang valid untuk parameter ini.

OuterUnknown

Arahkan ke antarmuka IUnknown objek yang perlu mengagregasi objek kunci registri. Parameter ini bersifat opsional. Jika agregasi tidak diperlukan, tentukan parameter ini sebagai NULL.

RegistryKeyType

Menentukan jenis kunci registri yang diminta akses pemanggil. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

DesiredAccess

Masker kontrol akses yang menentukan jenis akses yang diperlukan pemanggil ke kunci. Parameter ini berjenis ACCESS_MASK. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

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, metode tidak menggunakan parameter ini. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

CreateOptions

Bendera yang menunjukkan opsi buat. Bisa nol jika tidak ada yang diinginkan. Parameter ini diperlukan jika RegistryKeyType memiliki nilai GeneralRegistryKey; jika tidak, metode tidak menggunakan parameter ini. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

Disposition

Penunjuk ke variabel ULONG yang dialokasikan pemanggil tempat metode menulis nilai status yang menunjukkan apakah kunci baru dibuat atau kunci yang ada dibuka. Parameter ini bersifat opsional dan dapat ditentukan sebagai NULL jika pemanggil tidak memerlukan nilai status. Metode ini hanya menggunakan parameter ini jika RegistryKeyType memiliki nilai GeneralRegistryKey. Metode ini tidak menggunakan parameter untuk salah satu jenis kunci lainnya. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

Mengembalikan nilai

Metode ini mengembalikan NTSTATUS yang berisi STATUS_SUCCESS jika panggilan berhasil. Jika tidak, metode mengembalikan kode kesalahan yang sesuai.

Keterangan

Parameter DesiredAccess, ObjectAttributes, dan Disposition mengambil nilai yang ditentukan untuk parameter dengan nama yang sama dalam panggilan ZwCreateKey.

Jika parameter RegistryKeyType memiliki nilai GeneralRegistryKey, maka metode NewRegistryKey membuka kunci registri yang ada atau membuat kunci baru di registri, seperti yang ditunjukkan oleh nilai yang dihasilkan metode melalui parameter Disposition. Jika jenis kunci adalah nilai apa pun selain GeneralRegistryKey, maka metode membuka kunci yang sudah ada yang sebelumnya dibuat selama enumerasi perangkat Plug and Play.

Pemanggil harus mengatur parameter RegistryKeyType ke salah satu nilai enumerasi yang diperlihatkan dalam tabel berikut.

Nilai RegistryKeyType	Makna
GeneralRegistryKey	Berikan akses generik ke jenis kunci apa pun. Membuka kunci jika ada atau membuat kunci jika tidak.
DeviceRegistryKey	Buka kunci yang ada yang berisi informasi khusus perangkat.
DriverRegistryKey	Buka kunci yang ada yang berisi informasi khusus driver.
HwProfileRegistryKey	Buka kunci yang ada relatif terhadap profil perangkat keras saat ini untuk informasi perangkat atau driver. Ini memungkinkan driver untuk mengakses informasi konfigurasi yang khusus untuk profil perangkat keras.
DeviceInterfaceRegistryKey	Buka kunci registri yang ada yang berisi informasi tentang instans antarmuka perangkat tertentu.

Untuk nilai RegistryKeyType dari 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 ACL (daftar kontrol akses) yang mengontrol akses oleh pengguna ke kunci registri. Saat memanggil NewRegistryKey untuk membuat kunci registri jenis GeneralRegistryKey, parameter ObjectAttributes menentukan atribut kunci, termasuk deskriptor keamanan yang berisi ACL. Namun, jika jenis kuncinya adalah GeneralRegistryKey dan penunjuk deskriptor keamanan dalam struktur ObjectAttributes adalah NULL atau penunjuk ACL dalam deskriptor keamanan adalah NULL, maka kunci baru yang dibuat oleh panggilan akan mewarisi ACL kunci induk secara default.

Jika kunci tidak berjenis GeneralRegistryKey, maka kunci mempertahankan ACL yang Plug and Play ditetapkan ke kunci saat dibuat selama enumerasi perangkat.

Metode NewRegistryKey mirip dengan fungsi PcNewRegistryKey kecuali bahwa objek perangkat dan objek port harus ditentukan secara eksplisit dalam panggilan PcNewRegistryKey tetapi hanya tersirat dalam panggilan NewRegistryKey. PcNewRegistryKey biasanya dipanggil oleh driver adaptor. Driver miniport biasanya memanggil NewRegistryKey sebagai gantinya.

Setelah kunci registri dibuat atau dibuka oleh panggilan ke NewRegistryKey atau PcNewRegistryKey, metode IRegistryKey::NewSubKey dapat digunakan untuk membuat subkunci di bawah kunci tersebut.

Parameter OutRegistryKey dan OuterUnknown mengikuti konvensi penghitungan referensi untuk objek COM.

Persyaratan

Persyaratan	Nilai
Header	portcls.h
IRQL	PASSIVE_LEVEL

Lihat juga

IPort