CreateFileMappingFromApp 函式 (memoryapi.h)
從 Windows 市集應用程式建立或開啟指定檔案的具名或未命名檔案對應物件。
語法
HANDLE CreateFileMappingFromApp(
[in] HANDLE hFile,
[in, optional] PSECURITY_ATTRIBUTES SecurityAttributes,
[in] ULONG PageProtection,
[in] ULONG64 MaximumSize,
[in, optional] PCWSTR Name
);
參數
[in] hFile
要從中建立檔案對應物件的檔案控制碼。
檔案必須以與 flProtect 參數指定的保護旗標相容的存取權限開啟。 這並非必要專案，但建議您開啟您想要對應以取得獨佔存取權的檔案。 如需詳細資訊，請參閱 檔案安全性和存取權限。
如果hFile是INVALID_HANDLE_VALUE，呼叫進程也必須指定dwMaximumSizeHigh 和 dwMaximumSizeLow參數中檔案對應物件的大小。 在此案例中， CreateFileMappingFromApp 會建立指定大小的檔案對應物件，該物件是由系統分頁檔案所支援，而不是由檔案系統中的檔案所支援。
[in, optional] SecurityAttributes
SECURITY_ATTRIBUTES結構的指標，決定子進程是否可以繼承傳回的控制碼。 SECURITY_ATTRIBUTES結構的lpSecurityDescriptor成員會指定新檔案對應物件的安全性描述元。
如果 SecurityAttributes 為 Null，則無法繼承控制碼，而且檔案對應物件會取得預設的安全性描述元。 存取控制會在檔案對應物件的預設安全性描述元中列出 (ACL) 來自建立者的主要或模擬權杖。 如需詳細資訊，請參閱 檔案對應安全性和存取權限。
[in] PageProtection
指定檔案對應物件的頁面保護。 物件的所有對應檢視都必須與這個保護相容。
此參數可以是下列其中一個值。
應用程式可以將檔案對應物件的下列一或多個屬性結合在一起，並結合上述其中一個頁面保護值。
| 值 | 意義 |
|---|---|
|
如果檔案對應物件是由作業系統分頁檔案所支援， (hfile 參數 INVALID_HANDLE_VALUE) ，則指定當檔案的檢視對應到進程位址空間時，會認可整個頁面範圍，而不是保留。 系統必須有足夠的可認可頁面，才能保存整個對應。 否則， CreateFileMappingFromApp 會失敗。
此屬性對於可執行檔映射檔或資料檔案所支援的檔案對應物件沒有任何作用， (hfile 參數是檔案) 的控制碼。 SEC_COMMIT 無法與 SEC_RESERVE結合。 如果未指定任何屬性，則會假設 SEC_COMMIT 。 |
|
指定 hFile 參數指定的檔案是不會執行的可執行檔，且載入的映射檔不會執行強制完整性檢查。
此外，使用 SEC_IMAGE_NO_EXECUTE 屬性建立的檔案對應物件檢視，將不會叫用使用 PsSetLoadImageNotifyRoutine 核心 API 註冊的驅動程式回呼。
SEC_IMAGE_NO_EXECUTE屬性必須與PAGE_READONLY頁面保護值結合。 SEC_IMAGE_NO_EXECUTE沒有其他屬性有效。 |
|
讓大型頁面可用於作業系統分頁檔案所支援的檔案對應物件， (hfile 參數 INVALID_HANDLE_VALUE) 。 (hFile 參數是可執行檔映射檔或資料檔案) 可執行檔的控制碼，不支援這個屬性。
檔案對應物件的大小上限必須是 GetLargePageMinimum 函式所傳回之大型頁面大小下限的倍數。 如果不是， CreateFileMappingFromApp 會失敗。 當對應使用 SEC_LARGE_PAGES建立的檔案對應物件檢視時，基底位址和檢視大小也必須是最小大頁面大小的倍數。 SEC_LARGE_PAGES 需要在呼叫端的權杖中啟用 SeLockMemoryPrivilege 許可權。 如果指定 SEC_LARGE_PAGES ，也必須指定 SEC_COMMIT 。 |
|
將所有頁面設定為不可快取。
應用程式不應該使用這個屬性，除非裝置明確需要時才使用此屬性。 搭配與 SEC_NOCACHE 對應的記憶體使用連結函式可能會導致 EXCEPTION_ILLEGAL_INSTRUCTION 例外狀況。 SEC_NOCACHE 需要設定 SEC_RESERVE 或 SEC_COMMIT 屬性。 |
|
如果檔案對應物件是由作業系統分頁檔案所支援， (hfile 參數 INVALID_HANDLE_VALUE) ，則指定當檔案的檢視對應到進程位址空間時，整個頁面範圍會保留供進程稍後使用，而不是認可。
在 VirtualAlloc 函式的後續呼叫中，可以認可保留的頁面。 認可頁面之後，就無法使用 VirtualFree 函式釋放或取消認可這些頁面。 此屬性對於可執行檔映射檔或資料檔案所支援的檔案對應物件沒有任何作用， (hfile 參數是檔案) 的控制碼。 SEC_RESERVE 無法與 SEC_COMMIT結合。 |
|
將所有頁面設定為寫入合併。
應用程式不應該使用這個屬性，除非裝置明確需要時才使用此屬性。 使用與 SEC_WRITECOMBINE 對應記憶體的相互連結函式可能會導致 EXCEPTION_ILLEGAL_INSTRUCTION 例外狀況。 SEC_WRITECOMBINE 需要設定 SEC_RESERVE 或 SEC_COMMIT 屬性。 |
[in] MaximumSize
檔案對應物件的大小上限。
嘗試對應長度為 0 (零的檔案，) 失敗，錯誤碼 為 ERROR_FILE_INVALID。 應用程式應該測試長度為 0 (零) 的檔案，並拒絕這些檔案。
[in, optional] Name
檔案對應物件的名稱。
如果此參數符合現有對應物件的名稱，函式會要求存取 具有 flProtect 所指定保護的物件。
如果此參數為 Null，則會建立沒有名稱的檔案對應物件。
如果 lpName 符合現有事件、旗號、mutex、可等候的計時器或工作物件的名稱，則函式會失敗， 而且 GetLastError 函式會傳回 ERROR_INVALID_HANDLE。 這是因為這些物件共用相同的命名空間。
名稱可以有 「Global」 或 「Local」 前置詞，以在全域或會話命名空間中明確建立物件。 名稱的其餘部分可以包含任何字元，但反斜線字元 (\) 除外。 從會話零以外的會話建立全域命名空間中的檔案對應物件需要 SeCreateGlobalPrivilege 許可權。 如需詳細資訊，請參閱 核心物件命名空間。
使用終端機服務會話實作快速使用者切換。 第一個登入的使用者會使用會話 0 (零) ，下一個使用者登入會使用會話 1 (一個) 等等。 核心物件名稱必須遵循終端機服務概述的指導方針，讓應用程式可以支援多個使用者。
傳回值
如果函式成功，則傳回值是新建立之檔案對應物件的控制碼。
如果物件存在於函式呼叫之前，函式會傳回現有物件的控制碼 (其目前大小，而不是指定的大小) ， 而 GetLastError 會傳回 ERROR_ALREADY_EXISTS。
如果函式失敗，則傳回值為 Null。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
備註
建立檔案對應物件之後，檔案的大小不得超過檔案對應物件的大小;如果是，則並非所有檔案內容都可供共用。
如果應用程式指定檔案對應物件的大小大於磁片上實際具名檔案的大小，而且頁面保護允許寫入存取 (， flProtect 參數會指定 PAGE_READWRITE) ，則磁片上的檔案會增加以符合檔案對應物件的指定大小。 如果擴充檔案，則檔案的舊端與新檔案結尾之間的檔案內容不保證為零;行為是由檔案系統所定義。 如果磁片上的檔案無法增加， CreateFileMappingFromApp 會失敗， 而且 GetLastError 會傳回 ERROR_DISK_FULL。
作業系統分頁檔案所支援之檔案對應物件中頁面的初始內容為 0 (零) 。
CreateFileMappingFromApp傳回的控制碼具有新檔案對應物件的完整存取權，而且可以與需要檔案對應物件的控制碼的任何函式搭配使用。
多個進程可以使用單一共用檔案對應物件，或建立相同檔案支援的個別檔案對應物件，來共用相同檔案的檢視。 透過在進程建立時繼承控制碼、複製控制碼，或依名稱開啟檔案對應物件，可以由多個進程共用單一檔案對應物件。 如需詳細資訊，請參閱 CreateProcess、 DuplicateHandle 和 OpenFileMapping 函式 。
建立檔案對應物件實際上不會將檢視對應至進程位址空間。 MapViewOfFileEx函式會將檔案的檢視對應至進程位址空間。
有一個重要例外狀況，衍生自相同檔案所支援之任何檔案對應物件的檔案檢視在特定時間是一致或相同的。 對於進程內的檢視，以及由不同進程對應的檢視，保證一致性。
例外狀況與遠端檔案相關。 雖然 CreateFileMappingFromApp 可與遠端檔案搭配使用，但不會保持一致。 例如，如果兩部電腦將檔案對應為可寫入，而且兩部電腦都會變更相同的頁面，則每部電腦只會看到自己的頁面寫入。 當資料在磁片上更新時，它不會合並。
使用輸入和輸出 (I/) O 函式來存取的對應檔案和檔案， (ReadFile 和 WriteFile) 不一定一致。
檔案對應物件的對應檢視會維護物件的內部參考，而且檔案對應物件在釋放所有參考之前不會關閉。 因此，若要完全關閉檔案對應物件，應用程式必須呼叫 UnmapViewOfFile 來取消對應檔案對應物件的所有對應檢視，並藉由呼叫 CloseHandle關閉檔案對應物件控制碼。 這些函式可以依任何順序呼叫。
透過對應檢視修改檔案時，可能不會自動更新上次修改時間戳記。 如有需要，呼叫端應該使用 SetFileTime 來設定時間戳記。
使用結構化例外狀況處理來保護寫入或讀取檔案檢視的任何程式碼。 如需詳細資訊，請參閱 從檔案檢視讀取和寫入。
如果您的應用程式具有 codeGeneration 功能，您只能成功要求可執行檔案保護。
需求
| 最低支援的用戶端 | Windows 8 [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2012 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | memoryapi.h (包括 Windows.h) |
| 程式庫 | onecore.lib |
| DLL | Kernel32.dll |
另請參閱
檔案對應函式
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應