Fungsi CreateFileMapping2 (memoryapi.h)

Artikel
08/24/2023

Membuat atau membuka objek pemetaan file bernama atau tidak bernama untuk file tertentu. Anda dapat menentukan simpul NUMA pilihan untuk memori fisik sebagai parameter yang diperluas; lihat parameter ExtendedParameters .

Sintaks

HANDLE CreateFileMapping2(
  HANDLE                 File,
  SECURITY_ATTRIBUTES    *SecurityAttributes,
  ULONG                  DesiredAccess,
  ULONG                  PageProtection,
  ULONG                  AllocationAttributes,
  ULONG64                MaximumSize,
  PCWSTR                 Name,
  MEM_EXTENDED_PARAMETER *ExtendedParameters,
  ULONG                  ParameterCount
);

Parameter

File

Ketik: _In_ HANDLE

Handel ke file untuk membuat objek pemetaan file.

File harus dibuka dengan hak akses yang kompatibel dengan bendera perlindungan yang ditentukan parameter flProtect . Ini tidak diperlukan, tetapi disarankan agar file yang ingin Anda petakan dibuka untuk akses eksklusif. Untuk informasi selengkapnya, lihat Keamanan file dan hak akses.

Jika hFileINVALID_HANDLE_VALUE, proses panggilan juga harus menentukan ukuran untuk objek pemetaan file di parameter dwMaximumSizeHigh dan dwMaximumSizeLow . Dalam skenario ini, CreateFileMapping membuat objek pemetaan file dengan ukuran tertentu yang didukung oleh file halaman sistem alih-alih oleh file dalam sistem file.

SecurityAttributes

Jenis: SECURITY_ATTRIBUTES _In_opt_*

Penunjuk ke struktur SECURITY_ATTRIBUTES yang menentukan apakah handel yang dikembalikan dapat diwariskan oleh proses anak. Anggota lpSecurityDescriptor dari struktur SECURITY_ATTRIBUTES menentukan deskriptor keamanan untuk objek pemetaan file baru.

Jika lpAttributesADALAH NULL, handel tidak dapat diwariskan dan objek pemetaan file mendapatkan deskriptor keamanan default. Daftar kontrol akses (ACL) di deskriptor keamanan default untuk objek pemetaan file berasal dari token utama atau peniruan dari pembuat. Untuk informasi selengkapnya, lihat Keamanan Pemetaan File dan Hak Akses.

DesiredAccess

Ketik: _In_ ULONG

Masker akses yang diinginkan untuk handel pemetaan file yang dikembalikan. Untuk daftar hak akses, lihat Keamanan pemetaan file dan hak akses.

PageProtection

Ketik: _In_ ULONG

Menentukan perlindungan halaman objek pemetaan file. Semua tampilan objek yang dipetakan harus kompatibel dengan perlindungan ini.

Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
PAGE_EXECUTE_READ 0x20	Memungkinkan tampilan dipetakan untuk akses baca-saja, salin-saat-tulis, atau jalankan. Handel file yang ditentukan oleh parameter hFile harus dibuat dengan hak akses GENERIC_READ dan GENERIC_EXECUTE . Windows Server 2003 dan Windows XP: Nilai ini tidak tersedia sampai Windows XP dengan SP2 dan Windows Server 2003 dengan SP1.
PAGE_EXECUTE_READWRITE 0x40	Memungkinkan tampilan dipetakan untuk akses baca-saja, salin-tulis, baca/tulis, atau jalankan. Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ, GENERIC_WRITE, dan GENERIC_EXECUTE . Windows Server 2003 dan Windows XP: Nilai ini tidak tersedia sampai Windows XP dengan SP2 dan Windows Server 2003 dengan SP1.
PAGE_EXECUTE_WRITECOPY 0x80	Memungkinkan tampilan dipetakan untuk akses baca-saja, salin-saat-tulis, atau jalankan. Nilai ini setara dengan PAGE_EXECUTE_READ. Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ dan GENERIC_EXECUTE . Windows Vista: Nilai ini tidak tersedia sampai Windows Vista dengan SP1. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.
PAGE_READONLY 0x02	Memungkinkan tampilan dipetakan untuk akses baca-saja atau salin-saat-tulis. Upaya untuk menulis ke wilayah tertentu menghasilkan pelanggaran akses. Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ .
PAGE_READWRITE 0x04	Memungkinkan tampilan dipetakan untuk akses baca-saja, salin-tulis, atau baca/tulis. Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ dan GENERIC_WRITE .
PAGE_WRITECOPY 0x08	Memungkinkan tampilan dipetakan untuk akses baca-saja atau salin-saat-tulis. Nilai ini setara dengan PAGE_READONLY. Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ .

AllocationAttributes

Ketik: _In_ ULONG

Anda dapat menentukan satu atau beberapa atribut berikut untuk objek pemetaan file. Lihat juga parameter PageProtection .

Nilai	Makna
SEC_COMMIT 0x8000000	Jika objek pemetaan file didukung oleh file halaman sistem operasi (parameter hfileINVALID_HANDLE_VALUE), menentukan bahwa ketika tampilan file dipetakan ke dalam ruang alamat proses, seluruh rentang halaman diterapkan daripada dicadangkan. Sistem harus memiliki cukup halaman yang dapat dikomit untuk menahan seluruh pemetaan. Jika tidak, CreateFileMapping gagal. Atribut ini tidak berpengaruh untuk objek pemetaan file yang didukung oleh file gambar atau file data yang dapat dieksekusi (parameter hfile adalah handel ke file). SEC_COMMIT tidak dapat digabungkan dengan SEC_RESERVE. Jika tidak ada atribut yang ditentukan, SEC_COMMIT diasumsikan .
SEC_IMAGE 0x1000000	Menentukan bahwa file yang ditentukan parameter hFile adalah file gambar yang dapat dieksekusi. Atribut SEC_IMAGE harus dikombinasikan dengan nilai perlindungan halaman seperti PAGE_READONLY. Namun, nilai perlindungan halaman ini tidak berpengaruh pada tampilan file gambar yang dapat dieksekusi. Perlindungan halaman untuk tampilan file gambar yang dapat dieksekusi ditentukan oleh file yang dapat dieksekusi itu sendiri. Tidak ada atribut lain yang valid dengan SEC_IMAGE.
SEC_IMAGE_NO_EXECUTE 0x11000000	Menentukan bahwa file yang ditentukan parameter hFile adalah file gambar yang dapat dieksekusi yang tidak akan dijalankan dan file gambar yang dimuat tidak akan memiliki pemeriksaan integritas paksa yang dijalankan. Selain itu, memetakan tampilan objek pemetaan file yang dibuat dengan atribut SEC_IMAGE_NO_EXECUTE tidak akan memanggil panggilan balik driver yang terdaftar menggunakan API kernel PsSetLoadImageNotifyRoutine . Atribut SEC_IMAGE_NO_EXECUTE harus dikombinasikan dengan nilai perlindungan halaman PAGE_READONLY . Tidak ada atribut lain yang valid dengan SEC_IMAGE_NO_EXECUTE. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Nilai ini tidak didukung sebelum Windows Server 2012 dan Windows 8.
SEC_LARGE_PAGES 0x80000000	Memungkinkan halaman besar digunakan untuk objek pemetaan file yang didukung oleh file halaman sistem operasi (parameter hfileINVALID_HANDLE_VALUE). Atribut ini tidak didukung untuk objek pemetaan file yang didukung oleh file gambar atau file data yang dapat dieksekusi (parameter hFile adalah handel ke gambar atau file data yang dapat dieksekusi). Ukuran maksimum objek pemetaan file harus kelipatan ukuran minimum halaman besar yang dikembalikan oleh fungsi GetLargePageMinimum . Jika tidak, CreateFileMapping gagal. Saat memetakan tampilan objek pemetaan file yang dibuat dengan SEC_LARGE_PAGES, alamat dasar dan ukuran tampilan juga harus kelipatan dari ukuran halaman besar minimum. SEC_LARGE_PAGES memerlukan hak istimewa SeLockMemoryPrivilege untuk diaktifkan dalam token pemanggil. Jika SEC_LARGE_PAGES ditentukan, SEC_COMMIT juga harus ditentukan. Windows Server 2003: Nilai ini tidak didukung sampai Windows Server 2003 dengan SP1. Windows XP: Nilai ini tidak didukung.
SEC_NOCACHE 0x10000000	Mengatur semua halaman agar tidak dapat di-cache. Aplikasi tidak boleh menggunakan atribut ini kecuali ketika secara eksplisit diperlukan untuk perangkat. Menggunakan fungsi yang saling di-interlock dengan memori yang dipetakan dengan SEC_NOCACHE dapat menghasilkan pengecualian EXCEPTION_ILLEGAL_INSTRUCTION . SEC_NOCACHE mengharuskan atribut SEC_RESERVE atau SEC_COMMIT diatur.
SEC_RESERVE 0x4000000	Jika objek pemetaan file didukung oleh file halaman sistem operasi (parameter hfileINVALID_HANDLE_VALUE), menentukan bahwa ketika tampilan file dipetakan ke dalam ruang alamat proses, seluruh rentang halaman dicadangkan untuk digunakan nanti oleh proses daripada diterapkan. Halaman yang dipesan dapat dilakukan dalam panggilan berikutnya ke fungsi VirtualAlloc . Setelah halaman diterapkan, halaman tidak dapat dibebaskan atau dinonaktifkan dengan fungsi VirtualFree . Atribut ini tidak berpengaruh untuk objek pemetaan file yang didukung oleh file gambar atau file data yang dapat dieksekusi (parameter hfile adalah handel ke file). SEC_RESERVE tidak dapat digabungkan dengan SEC_COMMIT.
SEC_WRITECOMBINE 0x40000000	Mengatur semua halaman yang akan digabungkan dengan penulisan. Aplikasi tidak boleh menggunakan atribut ini kecuali ketika secara eksplisit diperlukan untuk perangkat. Menggunakan fungsi yang saling di-interlock dengan memori yang dipetakan dengan SEC_WRITECOMBINE dapat menghasilkan pengecualian EXCEPTION_ILLEGAL_INSTRUCTION . SEC_WRITECOMBINE mengharuskan atribut SEC_RESERVE atau SEC_COMMIT diatur. Windows Server 2003 dan Windows XP: Bendera ini tidak didukung sampai Windows Vista.

MaximumSize

Jenis: _In_ ULONG64

Ukuran maksimum objek pemetaan file.

Jika parameter ini adalah 0 (nol), maka ukuran maksimum objek pemetaan file sama dengan ukuran file saat ini yang diidentifikasi hFile .

Upaya untuk memetakan file dengan panjang 0 (nol) gagal dengan kode kesalahan ERROR_FILE_INVALID. Anda harus menguji file dengan panjang 0 (nol), dan menolak file-file tersebut.

Name

Jenis: _In_opt_ PCWSTR

Nama objek pemetaan file.

Jika parameter ini cocok dengan nama objek pemetaan yang ada, maka fungsi meminta akses ke objek dengan perlindungan yang ditentukan flProtect .

Jika parameter ini NULL, maka objek pemetaan file dibuat tanpa nama.

Jika lpName cocok dengan nama peristiwa yang ada, semaphore, mutex, timer yang dapat di tunggu, atau objek pekerjaan, fungsi gagal, dan fungsi GetLastError mengembalikan ERROR_INVALID_HANDLE. Ini terjadi karena objek ini memiliki namespace yang sama.

Nama dapat memiliki awalan "Global" atau "Lokal" untuk secara eksplisit membuat objek di namespace layanan global atau sesi. Sisa nama dapat berisi karakter apa pun kecuali karakter garis miring terbelakang (\). Membuat objek pemetaan file di namespace global dari sesi selain sesi nol memerlukan hak istimewa SeCreateGlobalPrivilege . Untuk informasi selengkapnya, lihat Namespace Objek Kernel.

Peralihan pengguna cepat diimplementasikan dengan menggunakan sesi Layanan Terminal. Pengguna pertama yang masuk menggunakan sesi 0 (nol), pengguna berikutnya untuk masuk menggunakan sesi 1 (satu), dan sebagainya. Nama objek kernel harus mengikuti panduan yang diuraikan untuk Layanan Terminal sehingga aplikasi dapat mendukung beberapa pengguna.

ExtendedParameters

Jenis: MEM_EXTENDED_PARAMETER _Inout_updates_opt_(ParameterCount)*

Penunjuk opsional ke satu atau beberapa parameter jenis MEM_EXTENDED_PARAMETER yang diperluas. Masing-masing nilai parameter yang diperluas itu sendiri dapat memiliki bidang Jenisdari MemExtendedParameterAddressRequirements atau MemExtendedParameterNumaNode. Jika tidak ada parameter perluasan MemExtendedParameterNumaNode yang disediakan, maka perilakunya sama dengan untuk fungsi VirtualAlloc/MapViewOfFile (yaitu, simpul NUMA pilihan untuk halaman fisik ditentukan berdasarkan prosesor ideal utas yang pertama kali mengakses memori).

ParameterCount

In ULONG ParameterCount

Jumlah parameter yang diperluas yang diacu oleh ExtendedParameters.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke objek pemetaan file yang baru dibuat.

Jika objek ada sebelum panggilan fungsi, fungsi mengembalikan handel ke objek yang ada (dengan ukurannya saat ini, bukan ukuran yang ditentukan), dan GetLastError mengembalikan ERROR_ALREADY_EXISTS.

Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Lihat Komentar untuk CreateFileMapping.

Contoh

Misalnya, lihat Membuat memori bersama bernama, atau Membuat pemetaan file menggunakan halaman besar.

Persyaratan


Klien minimum yang didukung	Windows 10 Build 20348
Server minimum yang didukung	Windows 10 Build 20348
Target Platform	Windows
Header	memoryapi.h (termasuk Windows.h, Memoryapi.h)
Pustaka	onecore.lib
DLL	Kernel32.dll