Fungsi NtCreateEnlistment (wdm.h)

Artikel
02/29/2024

Rutinitas ZwCreateEnlistment membuat objek pendaftaran baru untuk transaksi.

Sintaks

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateEnlistment(
  [out]          PHANDLE            EnlistmentHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           HANDLE             ResourceManagerHandle,
  [in]           HANDLE             TransactionHandle,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [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 ZwCreateEnlistment berhasil.

[in] DesiredAccess

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

bendera ACCESS_MASK	Mengizinkan penelepon untuk
ENLISTMENT_QUERY_INFORMATION	Informasi kueri tentang pendaftaran (lihat ZwQueryInformationEnlistment).
ENLISTMENT_SET_INFORMATION	Atur informasi untuk pendaftaran (lihat ZwSetInformationEnlistment).
ENLISTMENT_RECOVER	Pulihkan pendaftaran (lihat ZwRecoverEnlistment).
ENLISTMENT_SUBORDINATE_RIGHTS	Lakukan operasi yang dilakukan manajer sumber daya yang tidak unggul (lihat ZwRollbackEnlistment, ZwPrepareComplete, ZwPrepareComplete, ZwCommitComplete, ZwRollbackComplete, ZwSinglePhaseReject, ZwReadOnlyEnlistment).
ENLISTMENT_SUPERIOR_RIGHTS	Lakukan operasi yang harus dilakukan manajer transaksi superior (lihat ZwPrepareEnlistment, ZwPrepareEnlistment, ZwCommitEnlistment).

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 bersama dengan bendera tambahan dari tabel sebelumnya. Tabel berikut ini memperlihatkan bagaimana bitmap sesuai dengan hak akses tertentu.

Akses generik ke kanan	Kumpulan hak akses tertentu
ENLISTMENT_GENERIC_READ	STANDARD_RIGHTS_READ dan ENLISTMENT_QUERY_INFORMATION
ENLISTMENT_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, ENLISTMENT_SET_INFORMATION, ENLISTMENT_RECOVER, ENLISTMENT_REFERENCE, ENLISTMENT_SUBORDINATE_RIGHTS, dan ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, ENLISTMENT_RECOVER, ENLISTMENT_SUBORDINATE_RIGHTS, dan ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, ENLISTMENT_GENERIC_READ, ENLISTMENT_GENERIC_WRITE, dan ENLISTMENT_GENERIC_EXECUTE

[in] ResourceManagerHandle

Handel ke objek manajer sumber daya penelepon yang diperoleh oleh panggilan sebelumnya ke ZwCreateResourceManager atau ZwOpenResourceManager.

[in] TransactionHandle

Handel ke objek transaksi yang diperoleh oleh panggilan sebelumnya ke ZwCreateTransaction atau ZwOpenTransaction. KTM menambahkan transaksi ini ke daftar transaksi yang ditangani oleh manajer sumber daya panggilan.

[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] 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. 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

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

Menampilkan kode	Deskripsi
STATUS_INVALID_HANDLE	Handel objek tidak valid.
STATUS_INVALID_PARAMETER	Nilai parameter CreateOptions atau NotificationMask tidak valid, atau KTM tidak dapat menemukan transaksi yang ditentukan parameter TransactionHandle .
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 TransactionHandle tidak aktif.
STATUS_TRANSACTION_SUPERIOR_EXISTS	Penelepon mencoba mendaftar sebagai manajer transaksi yang unggul tetapi manajer transaksi 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

Manajer sumber daya memanggil ZwCreateEnlistment untuk mendaftar dalam transaksi.

Manajer sumber daya yang tidak unggul harus menyertakan bendera ENLISTMENT_SUBORDINATE_RIGHTS dalam masker akses mereka.

Manajer transaksi superior harus menyertakan bendera ENLISTMENT_SUPERIOR_RIGHTS dalam masker akses mereka. Biasanya, manajer transaksi superior menyertakan kode yang memanggil ZwRollbackEnlistment, sehingga juga harus menyertakan bendera ENLISTMENT_SUBORDINATE_RIGHTS.

Manajer sumber daya yang memanggil ZwCreateEnlistment akhirnya harus memanggil ZwClose untuk menutup handel objek.

Manajer sumber daya Anda dapat menggunakan parameter EnlistmentKey untuk menetapkan nilai unik untuk setiap pendaftaran, seperti penunjuk ke struktur data yang berisi informasi tentang pendaftaran. Misalnya, jika manajer sumber daya menyimpan handel objek pendaftaran dalam struktur, manajer sumber daya dapat melakukan hal berikut:

Hubungi ZwGetNotificationResourceManager untuk mendapatkan pemberitahuan.
Dapatkan nilai kunci pendaftaran dari struktur TRANSACTION_NOTIFICATION .
Gunakan kunci pendaftaran untuk menemukan handel objek pendaftaran tersimpan.
Rutinitas panggilan yang memerlukan handel pendaftaran sebagai input, seperti ZwCommitComplete atau ZwRollbackComplete.

Untuk informasi selengkapnya tentang ZwCreateEnlistment, lihat Membuat Resource Manager dan Membuat Manajer Transaksi Superior.

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