建立或開啟檔案或 I/O 裝置。 此函式的行為與 CreateFile 相同，不同之處在於此函式會遵守通用 Windows 平臺應用程式安全性模型。
語法
WINSTORAGEAPI HANDLE CreateFileFromAppW(
LPCWSTR lpFileName,
DWORD dwDesiredAccess,
DWORD dwShareMode,
LPSECURITY_ATTRIBUTES lpSecurityAttributes,
DWORD dwCreationDisposition,
DWORD dwFlagsAndAttributes,
HANDLE hTemplateFile
) noexcept;
參數
lpFileName
要建立或開啟的檔案或裝置名稱。 您可以在此名稱中使用正斜線 （/） 或反斜線 （\）。
在此功能的 ANSI 版本中，名稱僅限於 MAX_PATH 個字元。 若要將此限制延伸至 32,767 個寬字元，請呼叫函式的 Unicode 版本，並將 “\\？\” 附加到路徑前面。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間。
如需特殊裝置名稱的相關資訊，請參閱 定義 MS-DOS 裝置名稱。
若要建立檔案串流，請指定檔案名稱、冒號，然後指定串流名稱。 如需詳細資訊，請參閱 檔案串流。
針對此函式的 Unicode 版本 （CreateFileFromAppW），您可以選擇加入以移除 MAX_PATH 限制，而不加上前置 “\\？\”。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間 的「最大路徑長度限制」一節。
dwDesiredAccess
要求存取檔案或裝置，可以總結為讀取、寫入、兩者或兩者都不是零）。
最常用的值是 GENERIC_READ、 GENERIC_WRITE或兩者 （GENERIC_READ | GENERIC_WRITE）。 如需詳細資訊，請參閱 一般存取權限、 檔案安全性和存取權限、 檔案存取權限常數和 ACCESS_MASK。
如果此參數為零，應用程式可以查詢某些中繼資料，例如檔案、目錄或裝置屬性，而不需要存取該檔案或裝置，即使 GENERIC_READ 存取會遭到拒絕也一樣。
您無法要求與已具有開啟控制碼的開啟要求中 dwShareMode 參數所指定的共用模式衝突的存取模式。
dwShareMode
檔案或裝置所要求的共用模式，可以是讀取、寫入、兩者、刪除、所有這些或無 （請參閱下表）。 對屬性或延伸屬性的存取要求不受此旗標的影響。
| 價值觀 | Meaning |
|---|---|
| 0 0x00000000 | 防止其他進程在要求刪除、讀取或寫入存取權時開啟檔案或裝置。 |
| FILE_SHARE_DELETE 0x00000004 | 啟用檔案或裝置上的後續開啟作業，以要求刪除存取權。 否則，如果其他進程要求刪除存取權，則無法開啟檔案或裝置。 如果未指定此旗標，但已開啟檔案或裝置以進行刪除存取，則函式會失敗。 便條 刪除存取權允許刪除和重新命名作業。 |
| FILE_SHARE_READ 0x00000001 | 啟用檔案或裝置上的後續開啟作業，以要求讀取存取權。 否則，其他進程在要求讀取存取權時無法開啟檔案或裝置。 如果未指定此旗標，但已開啟檔案或裝置以取得讀取權，則函式會失敗。 |
| FILE_SHARE_WRITE 0x00000002 | 啟用檔案或裝置上的後續開啟作業，以要求寫入存取權。 否則，如果其他進程要求寫入存取權，則無法開啟檔案或裝置。 如果未指定此旗標，但已開啟檔案或裝置以進行寫入存取，或具有具有寫入存取權的檔案對映，則函式會失敗。 |
lpSecurityAttributes
包含兩個個別但相關資料成員的 SECURITY_ATTRIBUTES 結構指標：選擇性安全性描述元，以及判斷子進程是否可以繼承傳回控制碼的布林值。
此參數可以是 NULL。
如果此參數為 Null，則應用程式可能建立的任何子進程都無法繼承傳回的控制碼，而與傳回控制碼相關聯的檔案或裝置會取得預設安全性描述元。
結構的 lpSecurityDescriptor 成員會指定檔案或裝置的 SECURITY_DESCRIPTOR 。 如果此成員為 Null，則會指派與傳回控制碼相關聯的檔案或裝置預設安全性描述元。
此函式會在開啟現有的檔案或裝置時忽略 lpSecurityDescriptor 成員，但會繼續使用 bInheritHandle 成員。
結構的 bInheritHandle 成員會指定是否可以繼承傳回的控制碼。
dwCreationDisposition
對存在或不存在的檔案或裝置採取的動作。
對於檔案以外的設備，此參數通常設定為 OPEN_EXISTING。
如需詳細資訊，請參閱一節。
此參數必須是下列其中一個值，且無法組合：
| 價值觀 | Meaning |
|---|---|
| CREATE_ALWAYS 2 | 一律建立新檔案。 如果指定的檔案存在且可寫入，則函式會截斷檔案，函式會成功，且最後一個錯誤碼會設定為 ERROR_ALREADY_EXISTS （183）。 如果指定的檔案不存在且是有效路徑，則會建立新檔案、函式成功，且最後一個錯誤碼會設為零。 如需詳細資訊，請參閱本主題的備註一節。 |
| CREATE_NEW 1 | 建立新檔案，僅當該檔案尚不存在時。 如果指定的檔案存在，則函式會失敗，且最後一個錯誤碼會設為 ERROR_FILE_EXISTS （80）。 如果指定的檔案不存在，且是可寫入位置的有效路徑，則會建立新檔案。 |
| OPEN_ALWAYS 4 | 一律開啟檔案。 如果指定的檔案存在，則函式會成功，且最後一個錯誤碼會設定為 ERROR_ALREADY_EXISTS （183）。 如果指定的檔案不存在，且是可寫入位置的有效路徑，則函式會建立檔案，並將最後一個錯誤碼設為零。 |
| OPEN_EXISTING 3 | 開啟檔案或裝置，前提是它存在。 如果指定的檔案或裝置不存在，則函式會失敗，且最後一個錯誤碼會設定為 ERROR_FILE_NOT_FOUND （2）。 如需裝置的詳細資訊，請參閱備註一節。 |
| TRUNCATE_EXISTING 5 | 開啟檔案並截斷它，使其大小為零位元組，只有在檔案存在時。 如果指定的檔案不存在，則函數會失敗，且最後一個錯誤碼會設為 ERROR_FILE_NOT_FOUND （2）。 呼叫程式必須開啟檔案，並將 GENERIC_WRITE 位設定為 dwDesiredAccess 參數的一部分。 |
dwFlagsAndAttributes
檔案或裝置屬性和旗標， FILE_ATTRIBUTE_NORMAL 檔案最常見的預設值。
此參數可以包含可用檔案屬性 （FILE_ATTRIBUTE_*） 的任意組合。 所有其他檔案屬性都會覆寫 FILE_ATTRIBUTE_NORMAL。
此參數也可以包含旗標 （FILE_FLAG_*） 的組合，以控制檔案或裝置快取行為、存取模式及其他特殊用途旗標。 這些值與任何 FILE_ATTRIBUTE_* 值結合。
此參數也可以透過指定 SECURITY_SQOS_PRESENT 旗標來包含安全服務品質 （SQOS） 資訊。 其他 SQOS 相關旗標資訊會顯示在屬性及旗標表格之後的表格中。
| Attribute | Meaning |
|---|---|
| FILE_ATTRIBUTE_ARCHIVE 32 （0x20） | 該文件應該被存檔。 應用程式會使用此屬性來標示要備份或移除的檔案。 |
| FILE_ATTRIBUTE_ENCRYPTED 16384 （0x4000） | 檔案或目錄已加密。 對於檔案，這表示檔案中的所有資料都已加密。 對於目錄，這表示加密是新建立檔案和子目錄的預設值。 如需詳細資訊，請參閱 檔案加密。 如果也指定 FILE_ATTRIBUTE_SYSTEM 則此旗標無效。 Windows 的 Home、Home Premium、Starter 或 ARM 版本不支援此旗標。 |
| FILE_ATTRIBUTE_HIDDEN 2 （0x2） | 檔案已隱藏。 請勿將其包含在一般目錄清單中。 |
| FILE_ATTRIBUTE_NORMAL 128 （0x80） | 檔案未設定其他屬性。 此屬性只有在單獨使用時才有效。 |
| FILE_ATTRIBUTE_OFFLINE 4096 （0x1000） | 檔案的資料無法立即使用。 此屬性指出檔案資料會實際移至離線儲存體。 此屬性由分層儲存管理軟體遠端儲存體使用。 應用程式不應該任意變更此屬性。 |
| FILE_ATTRIBUTE_READONLY 1 （0x1） | 檔案是唯讀的。 應用程式可以讀取檔案，但無法寫入或刪除檔案。 |
| FILE_ATTRIBUTE_SYSTEM 4 （0x4） | 該檔案是作業系統的一部分或僅由作業系統使用。 |
| FILE_ATTRIBUTE_TEMPORARY 256 （0x100） | 檔案正用於暫存儲存。 如需詳細資訊，請參閱本主題的快取行為一節。 |
| Flag | Meaning |
|---|---|
| FILE_FLAG_BACKUP_SEMANTICS 0x02000000 | 正在開啟或建立檔案以進行備份或還原作業。 系統可確保呼叫處理程序在處理程序具有 SE_BACKUP_NAME 和 SE_RESTORE_NAME 專用權時置換檔案安全檢查。 如需詳細資訊，請參閱 變更權杖中的權限。 您必須設定此旗標，才能取得目錄的控制碼。 目錄控制碼可以傳遞至某些函式，而不是檔案控制碼。 如需詳細資訊，請參閱一節。 |
| FILE_FLAG_DELETE_ON_CLOSE 0x04000000 | 檔案會在關閉所有控制碼之後立即刪除，其中包括指定的控制碼和任何其他開啟或重複的控制碼。 如果檔案有現有的開啟控制碼，除非它們都以 FILE_SHARE_DELETE 共用模式開啟，否則呼叫會失敗。 檔案的後續開啟要求會失敗，除非指定 FILE_SHARE_DELETE 共用模式。 |
| FILE_FLAG_NO_BUFFERING 0x20000000 | 正在開啟檔案或裝置，但沒有用於資料讀取和寫入的系統快取。 此旗標不會影響硬碟快取或記憶體對應檔案。 使用 FILE_FLAG_NO_BUFFERING 旗標成功處理使用此函式開啟的檔案有嚴格的要求，如需詳細資訊，請參閱 檔案緩衝。 |
| FILE_FLAG_OPEN_NO_RECALL 0x00100000 | 要求檔案資料，但應該繼續位於遠端儲存體中。 不應將其傳輸回本機儲存體。 此旗標供遠端儲存體系統使用。 |
| FILE_FLAG_OPEN_REPARSE_POINT 0x00200000 | 不會發生正常的 重新分析點 處理;此函式會嘗試開啟重新分析點。 開啟檔案時，會傳回檔案控制碼，無論控制重新分析點的篩選條件是否可運作。 此旗標不能與 CREATE_ALWAYS 旗標搭配使用。 如果檔案不是重新分析點，則會忽略此旗標。 如需詳細資訊，請參閱一節。 |
| FILE_FLAG_OVERLAPPED 0x40000000 | 正在開啟或建立檔案或裝置以進行非同步 I/O。 在此控制碼上完成後續的 I/O 作業時， OVERLAPPED 結構中指定的事件會設定為訊號狀態。 如果指定此旗標，則檔案可用於同時讀取和寫入作業。 如果未指定此旗標，則會序列化 I/O 作業，即使讀取和寫入函式的呼叫指定 OVERLAPPED 結構也一樣。 如需使用此旗標建立的檔案控制碼時的考量資訊，請參閱本主題的同步和非同步 I/O 控制碼一節。 |
| FILE_FLAG_POSIX_SEMANTICS 0x0100000 | 訪問將根據 POSIX 規則進行。 這包括允許多個具有名稱的檔案，僅大小寫不同，以支援該命名的檔案系統。 使用此選項時請小心，因為針對 MS-DOS 或 16 位 Windows 撰寫的應用程式可能無法存取使用此旗標建立的檔案。 |
| FILE_FLAG_RANDOM_ACCESS 0x10000000 | 訪問是隨機的。 系統可以將其作為優化檔案快取的提示。 如果檔案系統不支援快取的 I/O 和 FILE_FLAG_NO_BUFFERING，則此旗標無效。 如需詳細資訊，請參閱本主題的快取行為一節。 |
| FILE_FLAG_SESSION_AWARE 0x00800000 | 檔案或裝置正在以會話感知開啟。 如果未指定此旗標，則每個會話裝置 （例如使用 RemoteFX USB 重新導向的裝置） 無法由在會話 0 中執行的進程開啟。 此旗標對不在會話 0 中的呼叫端沒有影響。 此旗標僅在 Windows 的伺服器版本上受支援。 |
| FILE_FLAG_SEQUENTIAL_SCAN 0x08000000 | 存取旨在從頭到尾按順序進行。 系統可以將其作為優化檔案快取的提示。 如果要使用後讀 （亦即反向掃描） ，則不應使用此旗標。 如果檔案系統不支援快取的 I/O 和 FILE_FLAG_NO_BUFFERING，則此旗標無效。 如需詳細資訊，請參閱本主題的快取行為一節。 |
| FILE_FLAG_WRITE_THROUGH 0x80000000 | 寫入操作不會經過任何中間緩存，它們將直接進入磁碟。 如需其他資訊，請參閱本主題的快取行為一節。 |
dwFlagsAndAttributes參數也可以指定 SQOS 資訊。 如需詳細資訊，請參閱 模擬層級。 當呼叫應用程式將 SECURITY_SQOS_PRESENT 旗標指定為 dwFlagsAndAttributes 的一部分時，它也可以包含下列一或多個值。
| 安全性旗標 | Meaning |
|---|---|
| SECURITY_ANONYMOUS | 在匿名模擬層級模擬用戶端。 |
| SECURITY_CONTEXT_TRACKING | 安全追蹤模式是動態的。 如果未指定此旗標，則安全性追蹤模式為靜態。 |
| SECURITY_DELEGATION | 在委派模擬層級模擬用戶端。 |
| SECURITY_EFFECTIVE_ONLY | 只有用戶端安全前後關聯的已啟用層面可供伺服器使用。 如果您未指定此旗標，則用戶端安全性內容的所有層面都可供使用。 這可讓用戶端限制伺服器在模擬用戶端時可以使用的群組和許可權。 |
| SECURITY_IDENTIFICATION | 在識別模擬層級模擬用戶端。 |
| SECURITY_IMPERSONATION | 在模擬層級模擬用戶端。 如果未指定其他旗標以及 SECURITY_SQOS_PRESENT 旗標，則這是預設行為。 |
hTemplateFile
具有 GENERIC_READ 存取權限之範本檔案的有效控制碼。 範本檔案會為正在建立的檔案提供檔案屬性及延伸屬性。
此參數可以是 NULL。
開啟現有檔案時，會忽略此參數。
開啟新的加密檔案時，檔案會從其父目錄繼承任意存取控制清單。 如需詳細資訊，請參閱 檔案加密。
返回值
如果函式成功，傳回值是指定檔案、裝置、具名管道或郵件位置的開啟控制碼。
如果函式失敗，則傳回值為 INVALID_HANDLE_VALUE。 若要取得擴充錯誤資訊，請呼叫 GetLastError。
需求
| Requirement | 價值觀 |
|---|---|
| 最低支援的用戶端 | Windows 10 版本 1803 |
| Header | fileapifromapp.h |
| Library | OneCore.Lib |