Fungsi ZwOpenKeyTransactedEx (wdm.h)

Artikel
08/08/2023

Rutinitas ZwOpenKeyTransactedEx membuka kunci registri yang ada dan mengaitkan kunci dengan transaksi.

Sintaks

NTSYSAPI NTSTATUS ZwOpenKeyTransactedEx(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  ULONG              OpenOptions,
  [in]  HANDLE             TransactionHandle
);

Parameter

[out] KeyHandle

Penunjuk ke variabel HANDLE tempat rutin menulis handel ke kunci.

[in] DesiredAccess

Menentukan jenis akses ke kunci yang diminta pemanggil. Parameter ini adalah nilai ACCESS_MASK . Untuk informasi selengkapnya, lihat deskripsi parameter DesiredAccess dari rutinitas ZwCreateKey .

[in] ObjectAttributes

Penunjuk ke atribut objek kunci yang sedang dibuka. Parameter ini menunjuk ke struktur OBJECT_ATTRIBUTES yang sebelumnya harus diinisialisasi oleh rutinitas InitializeObjectAttributes . Pemanggil harus menentukan nama kunci registri sebagai parameter ObjectName dalam panggilan ke InitializeObjectAttributes. Jika penelepon tidak berjalan dalam konteks utas sistem, pemanggil harus mengatur atribut OBJ_KERNEL_HANDLE saat memanggil InitializeObjectAttributes.

[in] OpenOptions

Menentukan opsi yang akan diterapkan saat membuka kunci. Atur parameter ini ke nol atau ke bitwise ATAU dari satu atau beberapa bit bendera REG_OPTION_XXX berikut.

Bendera OpenOptions	Deskripsi
REG_OPTION_OPEN_LINK	Kuncinya adalah tautan simbolis. Bendera ini tidak digunakan oleh perangkat dan driver perantara.
REG_OPTION_BACKUP_RESTORE	Kunci harus dibuka dengan hak istimewa khusus yang memungkinkan operasi pencadangan dan pemulihan. Bendera ini tidak digunakan oleh perangkat dan driver perantara.

[in] TransactionHandle

Handel ke objek transaksi. Untuk mendapatkan handel ini, Anda dapat memanggil rutinitas ZwCreateTransaction . Atau, jika Anda memiliki penunjuk ke objek transaksi, Anda dapat menyediakan penunjuk ke rutinitas ObOpenObjectByPointer untuk mendapatkan handel transaksi yang sesuai.

Nilai kembali

ZwOpenKeyTransactedEx mengembalikan STATUS_SUCCESS jika panggilan berhasil membuka kunci. Kemungkinan nilai pengembalian kesalahan meliputi yang berikut ini:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter ObjectAttributes adalah NULL atau menunjuk ke informasi yang tidak valid.
STATUS_INVALID_PARAMETER_4	Nilai parameter OpenOptions menentukan opsi yang tidak valid.
STATUS_OBJECT_PATH_SYNTAX_BAD	Jalur registri dalam atribut objek tidak valid.
STATUS_OBJECT_NAME_NOT_FOUND	Jalur registri dalam atribut objek tidak ditemukan.
STATUS_ACCESS_DENIED	Penelepon tidak memiliki hak akses yang diperlukan untuk membuka handel untuk kunci registri bernama.
STATUS_INSUFFICIENT_RESOURCES	Operasi alokasi memori gagal.

Keterangan

Rutinitas ini menyediakan handel yang dengannya pemanggil dapat mengakses kunci registri. Selain itu, rutinitas ini mengaitkan kunci dengan transaksi aktif.

Setelah handel yang ditunjukkan oleh KeyHandle tidak lagi digunakan, driver harus memanggil rutinitas ZwClose untuk menutupnya.

Jika kunci yang ditentukan tidak ada di registri, ZwOpenKeyTransactedEx mengembalikan nilai status kesalahan dan tidak menyediakan handel kunci. Tidak seperti rutinitas ZwCreateKeyTransacted , rutinitas ZwOpenKeyTransactedEx tidak membuat kunci yang ditentukan jika kunci tidak ada. ZwCreateKeyTransacted dan ZwOpenKeyTransactedEx mengaitkan kunci registri dengan transaksi.

Rutinitas ZwOpenKeyEx mirip dengan ZwOpenKeyTransactedEx, tetapi tidak mengaitkan kunci dengan transaksi.

Rutinitas ZwOpenKeyTransacted mirip dengan ZwOpenKeyTransactedEx tetapi tidak menerima parameter OpenOptions . Parameter OpenOptions dari ZwOpenKeyTransactedEx memungkinkan pemanggil untuk membuka kunci yang merupakan tautan simbolis, atau untuk membuka kunci untuk operasi pencadangan dan pemulihan. Panggilan ke ZwOpenKeyTransactedEx dengan parameter OpenOptions yang diatur ke nol setara dengan panggilan ke ZwOpenKeyTransacted.

Setelah driver mode kernel mendapatkan handel ke transaksi (misalnya, dengan memanggil ZwCreateTransaction), driver dapat melakukan serangkaian operasi registri yang merupakan bagian dari transaksi ini. Driver dapat menutup transaksi baik dengan berkomitmen pada perubahan yang dilakukan dalam transaksi atau dengan menggulung balik transaksi.

Setelah driver berhasil menyelesaikan semua operasi registri yang merupakan bagian dari transaksi, driver dapat memanggil rutinitas ZwCommitTransaction untuk berkomitmen pada perubahan. Driver dapat memanggil rutinitas ZwRollbackTransaction untuk menggulung balik transaksi.

Selama transaksi, operasi registri adalah bagian dari transaksi jika panggilan sistem yang melakukan operasi memenuhi salah satu kondisi berikut:

Panggilan menentukan, sebagai parameter input, handel transaksi. Misalnya, panggilan ke ZwCreateKeyTransacted dan ZwOpenKeyTransactedEx dapat mengaitkan satu atau beberapa kunci dengan transaksi.
Panggilan menentukan, sebagai parameter input, handel kunci registri yang diperoleh oleh panggilan ke ZwCreateKeyTransacted atau ZwOpenKeyTransactedEx tempat handel transaksi disediakan. Misalnya, panggilan ke rutinitas ZwSetValueKey dapat menggunakan handel kunci yang diperoleh dengan cara ini untuk mengatur nilai kunci registri sebagai bagian dari transaksi.

Untuk informasi selengkapnya tentang transaksi mode kernel, lihat Menggunakan Kernel Transaction Manager.

ZwOpenKeyTransactedEx mengabaikan informasi keamanan dalam struktur yang ditunjuk parameter ObjectAttributes .

Jika pemanggil mode kernel tidak berjalan dalam konteks utas sistem, pemanggil harus memastikan bahwa setiap handel yang dibuatnya adalah handel kernel. Jika tidak, handel dapat diakses oleh proses dalam konteks driver yang berjalan. Untuk informasi selengkapnya, lihat Penanganan Objek.

Untuk informasi selengkapnya tentang cara bekerja dengan kunci registri dalam mode kernel, lihat Menggunakan Registri di Driver.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Windows 7 dan versi yang lebih baru dari sistem operasi Windows.
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)