Fungsi NtCreateTransaction (wdm.h)

Artikel
07/02/2025

Rutinitas ZwCreateTransaction membuat objek transaksi .

Sintaksis

C++

__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 pemanggil 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	Memungkinkan 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	Set 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 SYNCHRONIZE
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 SYNCHRONIZE

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 InitializeObjectAttributes rutinitas untuk menginisialisasi struktur ini. Jika pemanggil tidak berjalan dalam konteks utas sistem, pemanggil harus mengatur atribut OBJ_KERNEL_HANDLE saat memanggil InitializeObjectAttributes. Parameter ini bersifat opsional dan dapat NULL.

[in, optional] Uow

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

[in, optional] TmHandle

Handel ke objek manajer transaksi yang diperoleh melalui 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	Arti
TRANSACTION_DO_NOT_PROMOTE	Dicadangkan untuk digunakan di masa mendatang.

[in, optional] IsolationLevel

Dicadangkan untuk digunakan di masa mendatang. Penelepon harus mengatur parameter ini ke nol.

[in, optional] IsolationFlags

Dicadangkan untuk digunakan di masa mendatang. Penelepon harus mengatur parameter ini ke nol.

[in, optional] Timeout

Penunjuk ke nilai waktu habis. Jika transaksi belum dilakukan oleh waktu yang ditentukan oleh parameter ini, KTM akan mengembalikan transaksi. Nilai waktu habis dinyatakan dalam unit waktu sistem (interval 100 nanodetik), dan dapat menentukan waktu absolut atau waktu relatif. Jika nilai yang ditunjukkan oleh Batas Waktu negatif, waktu kedaluwarsa relatif terhadap waktu sistem saat ini. Jika tidak, waktu kedaluwarsa adalah absolut. Penunjuk ini bersifat opsional dan dapat 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 memberikan 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 NULL.

Mengembalikan nilai

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

Mengembalikan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter CreateOptions berisi bendera yang tidak valid, parameter DesiredAccess adalah nol, atau string parameter Description 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.

Komentar

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. Pemanggil 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.

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

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

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

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Tersedia di Windows Vista dan versi sistem operasi yang lebih baru.
Platform Target	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