共用方式為

CreateFileFromAppW 函式 (fileapifromapp.h)

  • 發行項

建立或開啟檔案或 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

檔案或裝置的要求共用模式，這些模式可以是讀取、寫入、刪除、全部或無 (請參閱下表) 。 存取屬性或擴充屬性的要求不受此旗標影響。

值 意義
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。

如需詳細資訊，請參閱＜備註＞一節。

此參數必須是下列其中一個值，無法合併：

值 意義
CREATE_ALWAYS 2

一律建立新的檔案。

如果指定的檔案存在且可寫入，則函式會截斷檔案、函式成功，且最後錯誤碼會設定為 ERROR_ALREADY_EXISTS ( 183) 。

如果指定的檔案不存在且是有效的路徑，則會建立新的檔案、函式成功，且最後一個錯誤碼會設定為零。

如需詳細資訊，請參閱本主題的一節。
CREATE_NEW 1

只有在檔案不存在時，才會建立新的檔案。

如果指定的檔案存在，函式會失敗，且最後一個錯誤碼會設定為 ( 80) ERROR_FILE_EXISTS。

如果指定的檔案不存在，而且是可寫入位置的有效路徑，則會建立新的檔案。
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 相關旗標資訊，如下表的屬性和旗標資料表。

屬性 意義
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)

檔案應封存。 應用程式會使用這個屬性來標記要備份或移除的檔案。
FILE_ATTRIBUTE_ENCRYPTED 16384 (0x4000)

檔案或目錄已加密。 對檔案而言，這表示檔案中的所有資料都被加密。 對於目錄，這表示加密是新建立的檔案和子目錄的預設值。 如需詳細資訊，請參閱 檔案加密。

如果同時指定 FILE_ATTRIBUTE_SYSTEM， 此旗標就不會有任何作用。

在家用版、家用版、入門版或 ARM 版本的 Windows 上不支援此旗標。
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)

檔案正用於暫存檔。

如需詳細資訊，請參閱本主題的快取行為一節。

 

旗標 意義
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 作業也會序列化。

如需使用此旗標所建立之檔案控制代碼時的考慮資訊，請參閱本主題的同步和非同步 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的一部分時，它也可以包含下列一或多個值。

安全性旗標 意義
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。

規格需求

   
最低支援的用戶端 Windows 10 (版本 1803)
標頭 fileapifromapp.h