Fungsi NtCreateTransaction (wdm.h)

Artikel
02/27/2024

Rutinitas ZwCreateTransaction membuat objek transaksi.

Sintaks

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransaction(
  [out]          PHANDLE            TransactionHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] LPGUID             Uow,
  [in, optional] HANDLE             TmHandle,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              IsolationLevel,
  [in, optional] ULONG              IsolationFlags,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PUNICODE_STRING    Description
);

Parameter

[out] TransactionHandle

Penunjuk ke variabel yang dialokasikan penelepon yang menerima handel ke objek transaksi baru, jika panggilan ke ZwCreateTransaction berhasil.

[in] DesiredAccess

Nilai ACCESS_MASK yang menentukan akses pemanggil yang diminta ke objek transaksi. Selain hak akses yang ditentukan untuk semua jenis objek (lihat ACCESS_MASK), pemanggil dapat menentukan salah satu bendera berikut untuk objek transaksi.

Masker akses	Mengizinkan penelepon untuk
TRANSACTION_COMMIT	Terapkan transaksi (lihat ZwCommitTransaction).
TRANSACTION_ENLIST	Buat pendaftaran untuk transaksi (lihat ZwCreateEnlistment).
TRANSACTION_PROPAGATE	Jangan gunakan.
TRANSACTION_QUERY_INFORMATION	Dapatkan informasi tentang transaksi (lihat ZwQueryInformationTransaction).
TRANSACTION_ROLLBACK	Gulung balik transaksi (lihat ZwRollbackTransaction).
TRANSACTION_SET_INFORMATION	Atur informasi untuk transaksi (lihat ZwSetInformationTransaction).

Atau, Anda dapat menentukan satu atau beberapa bitmap ACCESS_MASK berikut. Bitmap ini menggabungkan bendera dari tabel sebelumnya dengan bendera STANDARD_RIGHTS_XXX yang dijelaskan di halaman referensi ACCESS_MASK . Anda juga dapat menggabungkan bitmap ini dengan bendera tambahan dari tabel sebelumnya. Tabel berikut ini memperlihatkan bagaimana bitmap sesuai dengan hak akses tertentu.

Bitmap hak	Kumpulan hak akses tertentu
TRANSACTION_GENERIC_READ	STANDARD_RIGHTS_READ, TRANSACTION_QUERY_INFORMATION, dan SINKRONKAN
TRANSACTION_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT, dan SYNCHRONIZE
TRANSACTION_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK, dan SINKRONKAN
TRANSACTION_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTION_GENERIC_READ, TRANSACTION_GENERIC_WRITE, dan TRANSACTION_GENERIC_EXECUTE
TRANSACTION_RESOURCE_MANAGER_RIGHTS	STANDARD_RIGHTS_WRITE, TRANSACTION_GENERIC_READ, TRANSACTION_SET_INFORMATION, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, dan SINKRONKAN

Biasanya, manajer sumber daya menentukan TRANSACTION_RESOURCE_MANAGER_RIGHTS.

Nilai DesiredAccess tidak boleh nol.

[in, optional] ObjectAttributes

Penunjuk ke struktur OBJECT_ATTRIBUTES yang menentukan nama objek dan atribut lainnya. Gunakan rutinitas InitializeObjectAttributes untuk menginisialisasi struktur ini. Jika penelepon tidak berjalan dalam konteks utas sistem, pemanggil harus mengatur atribut OBJ_KERNEL_HANDLE saat memanggil InitializeObjectAttributes. Parameter ini bersifat opsional dan dapat berupa NULL.

[in, optional] Uow

Pointer ke GUID yang digunakan KTM sebagai pengidentifikasi unit kerja (UOW) objek transaksi baru. Parameter ini bersifat opsional dan dapat berupa NULL. Jika parameter ini NULL, KTM menghasilkan GUID dan menetapkannya ke objek transaksi. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in, optional] TmHandle

Handel ke objek manajer transaksi yang diperoleh oleh panggilan sebelumnya ke ZwCreateTransactionManager atau ZwOpenTransactionManager. KTM menetapkan objek transaksi baru ke objek manajer transaksi yang ditentukan. Jika parameter ini NULL, KTM menetapkan objek transaksi baru ke manajer transaksi nanti, ketika manajer sumber daya membuat pendaftaran untuk transaksi.

[in, optional] CreateOptions

Bendera pembuatan objek opsional. Tabel berikut berisi bendera yang tersedia, yang ditentukan dalam Ktmtypes.h.

Bendera opsi	Makna
TRANSACTION_DO_NOT_PROMOTE	Disiapkan untuk penggunaan masa mendatang.

[in, optional] IsolationLevel

Disiapkan untuk penggunaan masa mendatang. Penelepon harus mengatur parameter ini ke nol.

[in, optional] IsolationFlags

Disiapkan untuk penggunaan masa mendatang. Pemanggil harus mengatur parameter ini ke nol.

[in, optional] Timeout

Penunjuk ke nilai waktu habis. Jika transaksi belum dilakukan pada waktu yang ditentukan oleh parameter ini, KTM mengembalikan transaksi. Nilai waktu habis dinyatakan dalam unit waktu sistem (interval 100 nanodetik), dan dapat menentukan waktu absolut atau waktu relatif. Jika nilai yang diarahkan oleh Timeout negatif, waktu kedaluwarsa relatif terhadap waktu sistem saat ini. Jika tidak, waktu kedaluwarsa adalah absolut. Penunjuk ini bersifat opsional dan dapat berupa NULL jika Anda tidak ingin transaksi memiliki nilai waktu habis. Jika Timeout = NULL atau *Timeout = 0, transaksi tidak pernah kehabisan waktu. (Anda juga dapat menggunakan ZwSetInformationTransaction untuk mengatur nilai waktu habis.)

[in, optional] Description

Penunjuk ke struktur UNICODE_STRING yang disediakan penelepon yang berisi string yang dihentikan NULL. String menyediakan deskripsi transaksi. KTM menyimpan salinan string dan menyertakan string dalam pesan yang ditulisnya ke aliran log. Panjang string maksimum adalah MAX_TRANSACTION_DESCRIPTION_LENGTH. Parameter ini bersifat opsional dan dapat berupa NULL.

Nilai kembali

ZwCreateTransaction mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, rutinitas ini mungkin mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter CreateOptions berisi bendera yang tidak valid, parameter DesiredAccess adalah nol, atau string parameter Deskripsi terlalu panjang.
STATUS_INSUFFICIENT_RESOURCES	KTM tidak dapat mengalokasikan sumber daya sistem (biasanya memori).
STATUS_INVALID_ACL	Deskriptor keamanan berisi daftar kontrol akses (ACL) yang tidak valid.
STATUS_INVALID_SID	Deskriptor keamanan berisi pengidentifikasi keamanan (SID) yang tidak valid.
STATUS_OBJECT_NAME_EXISTS	Nama objek yang ditentukan parameter ObjectAttributes sudah ada.
STATUS_OBJECT_NAME_INVALID	Nama objek yang ditentukan parameter ObjectAttributes tidak valid.
STATUS_ACCESS_DENIED	Nilai parameter DesiredAccess tidak valid.

Rutinitas mungkin mengembalikan nilai NTSTATUS lainnya.

Keterangan

Pemanggil dapat menggunakan parameter Uow untuk menentukan pengidentifikasi UOW untuk objek transaksi. Jika pemanggil tidak menentukan pengidentifikasi UOW, KTM menghasilkan GUID dan menetapkannya ke objek transaksi. Penelepon nantinya dapat memperoleh GUID ini dengan memanggil ZwQueryInformationTransaction.

Biasanya, Anda harus membiarkan KTM menghasilkan GUID untuk objek transaksi, kecuali komponen Anda berkomunikasi dengan komponen TPS lain yang telah menghasilkan pengidentifikasi UOW untuk transaksi tersebut.

Untuk menutup handel transaksi, komponen yang disebut ZwCreateTransaction harus memanggil ZwClose. Jika handel transaksi terakhir ditutup sebelum komponen memanggil ZwCommitTransaction untuk transaksi, KTM mengembalikan transaksi.

Untuk informasi selengkapnya tentang bagaimana klien transaksi harus menggunakan ZwCreateTransaction, lihat Membuat Klien Transaksional.

Untuk panggilan dari driver mode kernel, versi NtXxx dan ZwXxx dari rutinitas Windows Native System Services dapat berperilaku berbeda dalam cara mereka menangani dan menafsirkan parameter input. Untuk informasi selengkapnya tentang hubungan antara versi NtXxx dan ZwXxx dari rutinitas, lihat Menggunakan Versi Nt dan Zw dari Rutinitas Layanan Sistem Asli.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Windows Vista dan versi sistem operasi yang lebih baru.
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, PowerIrpDDis