共用方式為

CreateDirectory2A 函式 （fileapi.h）

建立新目錄。 如果基礎文件系統支援檔案和目錄的安全性，函式會將指定的安全性描述元套用至新的目錄。

若要指定範本目錄，請使用 CreateDirectoryEx 函式。

若要以交易作業的形式執行這項作業，請使用 CreateDirectoryTransacted 函式。

語法

HANDLE CreateDirectory2A(
  LPCSTR                lpPathName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  DIRECTORY_FLAGS       DirectoryFlags,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

參數

lpPathName

要建立之目錄的路徑。

根據預設，名稱限製為 MAX_PATH 個字元。 若要將此限制延伸至 32,767 寬字元，請在路徑前面加上 “\\？\”。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間。

小提示

您可以加入加入以移除 MAX_PATH 限制，而不需加上 “\\？\”。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間 的一節。

dwDesiredAccess

ACCESS_MASK值，表示呼叫端對目錄所需的存取類型。 系統定義的 dwDesiredAccess 旗標集合會決定下列特定的存取權限目錄檔案物件：

價值 意義
FILE_LIST_DIRECTORY 目錄中的檔案可以列出。
FILE_TRAVERSE 目錄可以周遊：也就是說，它可以是檔案路徑名稱的一部分。
同步 傳回的句柄可以等候與 I/O 作業完成同步處理。 如果未開啟同步 I/O 的句柄，則會忽略此值。

dwShareMode

呼叫端想要在檔案中使用的共用存取類型，以零或下列值的組合表示：

價值 意義
0
0x00000000		 如果其他進程要求刪除、讀取或寫入存取，則防止其他進程開啟檔案或裝置。
FILE_SHARE_READ
0x00000001		 啟用檔案或裝置上的後續開啟作業，以要求讀取存取權。 否則，如果進程要求讀取許可權，則無法開啟檔案或裝置。 如果未指定此旗標，但檔案或裝置已開啟以供讀取存取，則函式會失敗。
FILE_SHARE_WRITE
0x00000002		 啟用檔案或裝置上的後續開啟作業，以要求寫入存取權。 否則，如果其他進程要求寫入存取權，則無法開啟檔案或裝置。 如果未指定此旗標，但檔案或裝置已開啟以進行寫入存取，或具有寫入存取權的檔案對應，則函式會失敗。
FILE_SHARE_DELETE
0x00000004		 啟用檔案或裝置上的後續開啟作業，以要求刪除存取權。 否則，如果進程要求刪除存取權，則無法開啟檔案或裝置。 如果未指定此旗標，但檔案或裝置已開啟以進行刪除存取，則函式會失敗。

注意： 刪除存取允許刪除和重新命名作業。

DirectoryFlags

此參數可以包含 DIRECTORY_FLAGS的組合。

價值 意義
DIRECTORY_FLAGS_DISALLOW_PATH_REDIRECTS
0x00000001		 防止重新分析點或符號連結重新導向 lpPathName 。

lpSecurityAttributes

SECURITY_ATTRIBUTES 結構的指標。 結構的 lpSecurityDescriptor 成員會指定新目錄的安全性描述元。 如果 lpSecurityAttributes 為 NULL，目錄會取得預設的安全性描述元。 目錄的預設安全性描述元中的 ACL 會繼承自其父目錄。

目標文件系統必須支援檔案和目錄的安全性，此參數才能生效。 （當 GetVolumeInformation 傳回 FS_PERSISTENT_ACLS時，就會指出此情況。

返回值

如果函式成功，則傳回值為非零值。

如果函式失敗，傳回值會INVALID_HANDLE_VALUE。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

可能的錯誤包括下列各項：

回傳碼 說明
錯誤_已存在 指定的目錄已經存在。
ERROR_PATH_NOT_FOUND 一或多個中繼目錄不存在;此函式只會在路徑中建立最終目錄。
ERROR_PATH_REDIRECTED lpNewDirectory 是由重新分析點和/或符號連結重新導向。

備註

某些文件系統，例如 NTFS 檔案系統，支援個別檔案和目錄的壓縮或加密。 在格式化為這類文件系統的磁碟區上，新目錄會繼承其父目錄的壓縮和加密屬性。

應用程式可以藉由呼叫已設定FILE_FLAG_BACKUP_SEMANTICS旗標的 CreateFile，來取得目錄的句柄。 如需程式代碼範例，請參閱 CreateFile。

若要支持查詢此物件之安全性描述元的繼承函式，可能會啟發學習判斷並報告繼承是否有效。 如需詳細資訊，請參閱 可繼承 ACE 的自動傳播 。

下列技術支援此函式：

科技 支持
伺服器消息塊 （SMB） 3.0 通訊協定 是的
SMB 3.0 透明故障轉移 （TFO） 是的
具有向外延展檔案共用的SMB 3.0（SO） 是的
叢集共用磁碟區檔案系統 （CsvFS） 是的
復原檔案系統 （ReFS） 是的

備註

標頭會將 fileapi.hCreateDirectory2 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型 的慣例。

範例

下列範例會使用 CreateDirectory2 函式建立新的目錄。 系統會使用 FILE_LIST_DIRECTORY 和 SYNCHRONIZE 訪問許可權來建立新的目錄。 新的目錄也會使用 FILE_SHARE_READ 共用模式來建立，讓其他進程開啟目錄以供讀取存取。

// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF 
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO 
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A 
// PARTICULAR PURPOSE. 
// 
// Copyright (C) Microsoft. All rights reserved 
#include <Windows.h>
#include <stdio.h>
#include <strsafe.h>

int main(int argc, wchar_t* argv[])
{
    WCHAR filePath[MAX_PATH] = { 0 };

    // Create a directory to put a file into, that can't be deleted
    // and redirected before this handle is closed.
    HANDLE hDirectory = CreateDirectory2(argv[1],
        FILE_LIST_DIRECTORY | SYNCHRONIZE,
        FILE_SHARE_READ,
        DIRECTORY_FLAGS_NONE,
        NULL,
        NULL);
    if (hDirectory == INVALID_HANDLE_VALUE)
    {
        // Handle the error.
        printf("CreateDirectory2 failed (%d)\n", GetLastError());
        return (1);
    }

    StringCchPrintf(filePath,
        ARRAYSIZE(filePath),
        L"%ws\\example.test",
        argv[1]);

    HANDLE hFile = CreateFile3(filePath,
        GENERIC_ALL,
        FILE_SHARE_READ,
        CREATE_ALWAYS,
        NULL);
    if (hFile == INVALID_HANDLE_VALUE)
    {
        // Handle the error.
        CloseHandle(hDirectory);
        printf("CreateFile3 failed (%d)\n", GetLastError());
        return (1);
    }

    CloseHandle(hFile);
    CloseHandle(hDirectory);
    return (0);
}

如需其他範例，請參閱 擷取和變更檔案屬性。

需求

要求 價值
最低支援的用戶端 Windows 11 24H2 [傳統型應用程式 |UWP 應用程式]
支援的最低伺服器 Windows Server 2025 [傳統型應用程式 |UWP 應用程式]
標題 fileapi.h （包括 Windows.h）
程式庫 內核 32.lib
DLL Kernel32.dll

另請參閱

CreateFile3

DeleteFile2

RemoveDirectory2

  • Last updated on