Fungsi TmCreateEnlistment (wdm.h)

Artikel
02/29/2024

Rutinitas TmCreateEnlistment membuat objek pendaftaran baru untuk transaksi.

Sintaks

NTSTATUS TmCreateEnlistment(
  [out]          PHANDLE            EnlistmentHandle,
  [in]           KPROCESSOR_MODE    PreviousMode,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           PRKRESOURCEMANAGER ResourceManager,
  [in]           PKTRANSACTION      Transaction,
  [in, optional] ULONG              CreateOptions,
  [in]           NOTIFICATION_MASK  NotificationMask,
  [in, optional] PVOID              EnlistmentKey
);

Parameter

[out] EnlistmentHandle

Penunjuk ke variabel yang dialokasikan penelepon yang menerima handel ke objek pendaftaran baru jika panggilan ke TmCreateEnlistment berhasil.

[in] PreviousMode

Mode prosesor proses yang akan menggunakan handel pendaftaran untuk mengakses objek pendaftaran. Nilai ini harus UserMode atau KernelMode.

[in] DesiredAccess

Nilai ACCESS_MASK yang menentukan akses pemanggil yang diminta ke objek pendaftaran. Untuk informasi selengkapnya tentang parameter ini, lihat deskripsi parameter DesiredAccess untuk ZwCreateEnlistment.

[in] 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] ResourceManager

Penunjuk ke objek resource manager. Untuk mendapatkan pointer ini, komponen Anda harus memanggil ObReferenceObjectByHandle dan menyediakan handel objek yang sebelumnya memanggil ZwCreateResourceManager atau ZwOpenResourceManager yang disediakan.

[in] Transaction

Penunjuk ke objek transaksi. Untuk mendapatkan pointer ini, komponen Anda harus memanggil ObReferenceObjectByHandle dan menyediakan handel objek yang sebelumnya memanggil ZwCreateTransaction atau ZwOpenTransaction yang disediakan. KTM menambahkan transaksi ini ke daftar transaksi yang ditangani oleh manajer sumber daya panggilan.

[in, optional] CreateOptions

Bendera opsi pendaftaran. Tabel berikut berisi satu-satunya bendera yang tersedia.

Bendera CreateOptions	Makna
ENLISTMENT_SUPERIOR	Pemanggil mendaftar sebagai manajer transaksi yang unggul untuk transaksi yang ditentukan.

Parameter ini bersifat opsional dan bisa nol.

[in] NotificationMask

Bitwise OR dari nilai TRANSACTION_NOTIFY_XXX yang ditentukan dalam Ktmtypes.h. Nilai masker ini menentukan jenis pemberitahuan transaksi yang dikirim KTM ke pemanggil.

[in, optional] EnlistmentKey

Penunjuk ke informasi yang ditentukan penelepon yang secara unik mengidentifikasi pendaftaran. Manajer sumber daya menerima pointer ini ketika memanggil ZwGetNotificationResourceManager atau ketika KTM memanggil rutinitas panggilan balik ResourceManagerNotification . Manajer sumber daya dapat mempertahankan jumlah referensi untuk kunci ini dengan memanggil TmReferenceEnlistmentKey dan TmDereferenceEnlistmentKey. Parameter ini bersifat opsional dan dapat berupa NULL.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Nilai parameter CreateOptions atau NotificationMask tidak valid, atau KTM tidak dapat menemukan transaksi yang ditentukan parameter Transaksi .
STATUS_INSUFFICIENT_RESOURCES	Alokasi memori gagal.
STATUS_TRANSACTIONMANAGER_NOT_ONLINE	Pendaftaran gagal karena KTM atau manajer sumber daya tidak dalam status operasional.
STATUS_TRANSACTION_NOT_ACTIVE	Pendaftaran gagal karena transaksi yang ditentukan parameter Transaksi tidak aktif.
STATUS_TRANSACTION_SUPERIOR_EXISTS	Penelepon mencoba mendaftar sebagai manajer transaksi yang unggul tetapi pendaftaran yang unggul sudah ada.
STATUS_TM_VOLATILE	Pemanggil mencoba mendaftar sebagai manajer transaksi yang unggul, tetapi objek manajer sumber daya penelepon volatil sementara objek manajer transaksi terkait tidak volatil.
STATUS_ACCESS_DENIED	Nilai parameter DesiredAccess tidak valid.

Rutinitas mungkin mengembalikan nilai NTSTATUS lainnya.

Keterangan

Rutinitas TmCreateEnlistment adalah versi berbasis pointer dari rutinitas ZwCreateEnlistment .

Untuk informasi tentang kapan harus menggunakan rutinitas TmXxx KTM alih-alih rutinitas ZwXxx , lihat Menggunakan Rutinitas TmXxx.

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