Fungsi NtCreateSectionEx (ntifs.h)

Artikel
03/10/2023

NtCreateSectionEx membuat objek bagian** dan membuka handel ke objek dengan akses yang diinginkan yang ditentukan. Ini adalah versi yang diperluas dari NtCreateSection yang membuat objek bagian dengan menentukan untuk menunjukkan bahwa ini sebenarnya adalah bagian Address Windowing Extensions (AWE).

Sintaks

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateSectionEx(
  [out]          PHANDLE                 SectionHandle,
  [out]          ACCESS_MASK             DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES      ObjectAttributes,
  [in, optional] PLARGE_INTEGER          MaximumSize,
  [in]           ULONG                   SectionPageProtection,
  [in]           ULONG                   AllocationAttributes,
  [in, optional] HANDLE                  FileHandle,
  [in/out]       PMEM_EXTENDED_PARAMETER ExtendedParameters,
                 ULONG                   ExtendedParameterCount
);

Parameter

[out] SectionHandle

Penunjuk ke variabel HANDLE yang menerima handel ke objek bagian.

[out] DesiredAccess

Menentukan nilai ACCESS_MASK yang menentukan akses yang diminta ke objek. Selain hak akses yang ditentukan untuk semua jenis objek, pemanggil dapat menentukan salah satu hak akses berikut, yang khusus untuk objek bagian:

Bendera DesiredAccess	Memungkinkan penelepon untuk melakukan ini
SECTION_EXTEND_SIZE	Perluas ukuran bagian secara dinamis.
SECTION_MAP_EXECUTE	Jalankan tampilan bagian.
SECTION_MAP_READ	Baca tampilan bagian.
SECTION_MAP_WRITE	Tulis tampilan bagian .
SECTION_QUERY	Kueri objek bagian untuk informasi tentang bagian tersebut. Driver harus mengatur bendera ini.
SECTION_ALL_ACCESS	Semua bendera sebelumnya dikombinasikan dengan STANDARD_RIGHTS_REQUIRED.

[in, optional] ObjectAttributes

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

[in, optional] MaximumSize

Menentukan ukuran maksimum, dalam byte, dari bagian . NtCreateSection membulatkan nilai ini ke kelipatan PAGE_SIZE terdekat. Jika bagian didukung oleh file halaman, MaximumSize menentukan ukuran bagian yang sebenarnya. Jika bagian didukung oleh file biasa, MaximumSize menentukan ukuran maksimum yang dapat diperluas atau dipetakan file.

[in] SectionPageProtection

Menentukan perlindungan yang akan ditempatkan pada setiap halaman di bagian . Gunakan salah satu dari empat nilai berikut: PAGE_READONLY, PAGE_READWRITE, PAGE_EXECUTE, atau PAGE_WRITECOPY. Untuk deskripsi nilai-nilai ini, lihat CreateFileMapping.

[in] AllocationAttributes

Menentukan bitmask bendera SEC_XXX yang menentukan atribut alokasi bagian. Untuk deskripsi bendera ini, lihat CreateFileMapping.

[in, optional] FileHandle

Secara opsional menentukan handel untuk objek file terbuka. Jika nilai FileHandle adalah NULL, bagian didukung oleh file halaman. Jika tidak, bagian didukung oleh file yang ditentukan.

[in/out] ExtendedParameters

Penunjuk ke array MEM_EXTENDED_PARAMETER struktur berisi parameter yang diperluas untuk membuat bagian.

ExtendedParameterCount

Ukuran array yang dituju oleh ExtendedParameters .

Nilai kembali

NtCreateSectionEx mengembalikan STATUS_SUCCESS pada keberhasilan, atau kode kesalahan NTSTATUS yang sesuai pada kegagalan. Kemungkinan kode status kesalahan meliputi yang berikut ini:

Menampilkan kode	Deskripsi
STATUS_FILE_LOCK_CONFLICT	File yang ditentukan oleh parameter FileHandle dikunci.
STATUS_INVALID_FILE_FOR_SECTION	File yang ditentukan oleh FileHandle tidak mendukung bagian.
STATUS_INVALID_PAGE_PROTECTION	Nilai yang ditentukan untuk parameter SectionPageProtection tidak valid.
STATUS_MAPPED_FILE_SIZE_ZERO	Ukuran file yang ditentukan oleh FileHandle adalah nol, dan MaximumSize adalah nol.
STATUS_SECTION_TOO_BIG	Nilai MaximumSize terlalu besar. Ini terjadi ketika MaximumSize lebih besar dari maksimum yang ditentukan sistem untuk bagian, atau jika MaximumSize lebih besar dari file yang ditentukan dan bagian tidak dapat ditulis.

Keterangan

Setelah handel yang ditunjukkan oleh SectionHandle tidak lagi digunakan, driver harus memanggil NtClose untuk menutupnya.

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

Untuk informasi selengkapnya tentang menyiapkan bagian dan tampilan memori yang dipetakan, lihat Bagian dan Tampilan.

Catatan

Jika panggilan ke fungsi ini terjadi dalam mode pengguna, Anda harus menggunakan nama "NtCreateSectionEx" alih-alih "ZwCreateSectionEx".

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.

ExtendedParameters adalah parameter yang diperluas berbasis tumpukan jika simpul NUMA pilihan ditentukan.

Hanya satu instans parameter yang diperluas yang dapat ditentukan.

Konversikan ke nomor simpul numa berbasis 1 yang diharapkan di hilir API ini.