Fungsi CreateDirectory2W (fileapi.h)

Artikel
2025-04-11

Membuat direktori baru. Jika sistem file yang mendasar mendukung keamanan pada file dan direktori, fungsi menerapkan deskriptor keamanan tertentu ke direktori baru.

Untuk menentukan direktori templat, gunakan fungsi CreateDirectoryEx .

Untuk melakukan operasi ini sebagai operasi yang ditransaksikan, gunakan fungsi CreateDirectoryTransacted .

Sintaksis

HANDLE CreateDirectory2W(
  LPCWSTR               lpPathName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  DIRECTORY_FLAGS       DirectoryFlags,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Parameter-parameternya

lpPathName

Jalur direktori yang akan dibuat.

Secara default, nama dibatasi untuk MAX_PATH karakter. Untuk memperpanjang batas ini menjadi 32.767 karakter lebar, tambahkan awal "\\?\" ke jalur. Untuk informasi selengkapnya, lihat Menamai File, Jalur, dan Namespace.

Petunjuk / Saran

Anda dapat ikut serta untuk menghapus batasan MAX_PATH tanpa menambahkan sebelumnya "\\?\". Lihat bagian "Batasan Panjang Jalur Maksimum" dari Penamaan File, Jalur, dan Namespace untuk detailnya.

dwDesiredAccess

Nilai ACCESS_MASK yang mengekspresikan jenis akses yang diperlukan pemanggil ke direktori. Set bendera dwDesiredAccess yang ditentukan sistem menentukan objek file direktori hak akses tertentu berikut:

Nilai	Makna
FILE_LIST_DIRECTORY	File dalam direktori dapat dicantumkan.
FILE_TRAVERSE	Direktori dapat dilalui: yaitu, dapat menjadi bagian dari nama jalur file.
MENSINKRONISASI	Handel yang dikembalikan dapat ditunggu untuk disinkronkan dengan penyelesaian operasi I/O. Jika handel tidak dibuka untuk I/O sinkron, nilai ini diabaikan.

dwShareMode

Jenis akses berbagi yang ingin digunakan pemanggil dalam file, sebagai nol, atau sebagai salah satu atau kombinasi dari nilai berikut:

Nilai	Makna
0 `0x00000000`	Mencegah proses lain membuka file atau perangkat jika meminta akses hapus, baca, atau tulis.
FILE_SHARE_READ `0x00000001`	Memungkinkan operasi terbuka berikutnya pada file atau perangkat untuk meminta akses baca. Jika tidak, proses lain tidak dapat membuka file atau perangkat jika mereka meminta akses baca. Jika bendera ini tidak ditentukan, tetapi file atau perangkat telah dibuka untuk akses baca, fungsi gagal.
FILE_SHARE_WRITE `0x00000002`	Memungkinkan operasi terbuka berikutnya pada file atau perangkat untuk meminta akses tulis. Jika tidak, proses lain tidak dapat membuka file atau perangkat jika meminta akses tulis. Jika bendera ini tidak ditentukan, tetapi file atau perangkat telah dibuka untuk akses tulis atau memiliki pemetaan file dengan akses tulis, fungsi gagal.
FILE_SHARE_DELETE `0x00000004`	Memungkinkan operasi terbuka berikutnya pada file atau perangkat untuk meminta akses penghapusan. Jika tidak, proses lain tidak dapat membuka file atau perangkat jika meminta akses penghapusan. Jika bendera ini tidak ditentukan, tetapi file atau perangkat telah dibuka untuk akses penghapusan, fungsi gagal. Nota: Menghapus akses memungkinkan operasi hapus dan ganti nama.

DirectoryFlags

Parameter ini dapat berisi kombinasi DIRECTORY_FLAGS.

Nilai	Makna
DIRECTORY_FLAGS_DISALLOW_PATH_REDIRECTS `0x00000001`	Cegah lpPathName dialihkan oleh titik pemisahan ulang atau tautan simbolis.

lpSecurityAttributes

Penunjuk ke struktur SECURITY_ATTRIBUTES . Anggota lpSecurityDescriptor dari struktur menentukan deskriptor keamanan untuk direktori baru. Jika lpSecurityAttributes adalah NULL, direktori mendapatkan deskriptor keamanan default. ACL dalam deskriptor keamanan default untuk direktori diwarisi dari direktori induknya.

Sistem file target harus mendukung keamanan pada file dan direktori agar parameter ini berpengaruh. (Ini ditunjukkan ketika GetVolumeInformation mengembalikan FS_PERSISTENT_ACLS.)

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.

Kemungkinan kesalahan termasuk yang berikut ini:

Mengembalikan kode	Deskripsi
ERROR_SUDAH_ADA	Direktori yang ditentukan sudah ada.
ERROR_PATH_NOT_FOUND	Satu atau beberapa direktori perantara tidak ada; fungsi ini hanya akan membuat direktori akhir di jalur.

Komentar

Beberapa sistem file, seperti sistem file NTFS, mendukung kompresi atau enkripsi untuk file dan direktori individual. Pada volume yang diformat untuk sistem file tersebut, direktori baru mewarisi atribut kompresi dan enkripsi direktori induknya.

Aplikasi dapat memperoleh handel ke direktori dengan memanggil CreateFile dengan set bendera FILE_FLAG_BACKUP_SEMANTICS . Untuk contoh kode, lihat CreateFile.

Untuk mendukung fungsi pewarisan yang mengkueri deskriptor keamanan objek ini dapat menentukan dan melaporkan bahwa pewarisan berlaku secara heuristik. Lihat Penyebaran Otomatis ACE yang Dapat Diwariskan untuk informasi selengkapnya.

Fungsi ini didukung oleh teknologi berikut:

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
Failover Transparan (TFO) SMB 3.0	Ya
SMB 3.0 dengan Scale-out File Shares (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

Nota

Header fileapi.h mendefinisikan CreateDirectory2 sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preprosektor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Contoh

Contoh berikut membuat direktori baru dengan fungsi CreateDirectory2 . Direktori baru dibuat dengan hak akses FILE_LIST_DIRECTORY dan SYNCHRONIZE . Direktori baru juga dibuat dengan mode berbagi FILE_SHARE_READ , yang memungkinkan proses lain membuka direktori untuk akses baca.

// 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);
}

Untuk contoh tambahan, lihat Mengambil dan Mengubah Atribut File.

Persyaratan

Persyaratan	Nilai
klien minimum yang didukung	Windows 11 24H2 [aplikasi desktop \| Aplikasi UWP]
server minimum yang didukung	Windows Server 2025 [aplikasi desktop \| Aplikasi UWP]
Tajuk	fileapi.h (termasuk Windows.h)
Perpustakaan	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

CreateFile3

DeleteFile2

RemoveDirectory2

Bagikan melalui