CreateDirectory2A-Funktion (fileapi.h)

Erstellt ein neues Verzeichnis. Wenn das zugrunde liegende Dateisystem die Sicherheit für Dateien und Verzeichnisse unterstützt, wendet die Funktion einen angegebenen Sicherheitsdeskriptor auf das neue Verzeichnis an.

Verwenden Sie die CreateDirectoryEx-Funktion , um ein Vorlagenverzeichnis anzugeben.

Verwenden Sie die CreateDirectoryTransacted-Funktion , um diesen Vorgang als transacted-Vorgang auszuführen.

Syntax

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

Die Parameter

lpPathName

Der Pfad des zu erstellenden Verzeichnisses.

Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um diesen Grenzwert auf 32.767 breite Zeichen zu erweitern, stellen Sie "\\?\" dem Pfad voran. Weitere Informationen finden Sie unter Benennen von Dateien, Pfaden und Namespaces.

Tipp

Sie können sich anmelden, um die MAX_PATH Einschränkung zu entfernen , ohne "\\?\" vorauszustehen. Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbeschränkung" der Benennungsdateien, Pfade und Namespaces .

dwDesiredAccess

Der ACCESS_MASK Wert, der den Typ des Zugriffs ausdrückt, den der Aufrufer für das Verzeichnis benötigt. Der Satz systemdefinierter dwDesiredAccess-Flags bestimmt die folgenden spezifischen Zugriffsberechtigungsverzeichnisdateiobjekte:

Wert	Bedeutung
FILE_LIST_DIRECTORY	Dateien im Verzeichnis können aufgelistet werden.
FILE_TRAVERSE	Das Verzeichnis kann durchlaufen werden: d. h. es kann Teil des Pfadnamens einer Datei sein.
SYNCHRONISIEREN	Das zurückgegebene Handle kann mit dem Abschluss eines E/A-Vorgangs auf die Synchronisierung gewartet werden. Wenn das Handle nicht für synchrone E/A geöffnet wurde, wird dieser Wert ignoriert.

dwShareMode

Der Typ des Freigabezugriffs, den der Aufrufer in der Datei verwenden möchte, als Null oder als eine oder eine Kombination der folgenden Werte:

Wert	Bedeutung
0 `0x00000000`	Verhindert, dass andere Prozesse eine Datei oder ein Gerät öffnen, wenn sie Lösch-, Lese- oder Schreibzugriff anfordern.
FILE_SHARE_READ `0x00000001`	Ermöglicht nachfolgenden Öffnenvorgängen auf einer Datei oder einem Gerät das Anfordern des Lesezugriffs. Andernfalls können andere Prozesse die Datei oder das Gerät nicht öffnen, wenn sie Lesezugriff anfordern. Wenn dieses Flag nicht angegeben ist, aber die Datei oder das Gerät für den Lesezugriff geöffnet wurde, schlägt die Funktion fehl.
FILE_SHARE_WRITE `0x00000002`	Ermöglicht nachfolgenden Öffnenvorgängen auf einer Datei oder einem Gerät das Anfordern des Schreibzugriffs. Andernfalls können andere Prozesse die Datei oder das Gerät nicht öffnen, wenn sie Schreibzugriff anfordern. Wenn dieses Flag nicht angegeben ist, aber die Datei oder das Gerät für den Schreibzugriff geöffnet wurde oder über eine Dateizuordnung mit Schreibzugriff verfügt, schlägt die Funktion fehl.
FILE_SHARE_DELETE `0x00000004`	Ermöglicht nachfolgenden Öffnenvorgängen auf einer Datei oder einem Gerät das Anfordern des Löschzugriffs. Andernfalls können andere Prozesse die Datei oder das Gerät nicht öffnen, wenn sie den Löschzugriff anfordern. Wenn dieses Flag nicht angegeben ist, aber die Datei oder das Gerät für den Löschzugriff geöffnet wurde, schlägt die Funktion fehl. Anmerkung: Der Löschzugriff ermöglicht sowohl Lösch- als auch Umbenennungsvorgänge.

DirectoryFlags

Dieser Parameter kann Kombinationen aus DIRECTORY_FLAGS enthalten.

Wert	Bedeutung
DIRECTORY_FLAGS_DISALLOW_PATH_REDIRECTS `0x00000001`	Verhindern, dass lpPathName durch Analysepunkte oder symbolische Verknüpfungen umgeleitet wird.

lpSecurityAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES Struktur. Das lpSecurityDescriptor-Element der Struktur gibt einen Sicherheitsdeskriptor für das neue Verzeichnis an. Wenn lpSecurityAttributes lautet NULL, ruft das Verzeichnis einen Standardsicherheitsdeskriptor ab. Die ACLs im Standardsicherheitsdeskriptor für ein Verzeichnis werden vom übergeordneten Verzeichnis geerbt.

Das Zieldateisystem muss die Sicherheit für Dateien und Verzeichnisse unterstützen, damit dieser Parameter wirksam wird. (Dies wird angegeben, wenn GetVolumeInformationFS_PERSISTENT_ACLS zurückgibt.)

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlschlägt, wird der Rückgabewert INVALID_HANDLE_VALUE. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Mögliche Fehler sind:

Rückgabecode	BESCHREIBUNG
ERROR_ALREADY_EXISTS	Das angegebene Verzeichnis ist bereits vorhanden.
ERROR_PATH_NOT_FOUND	Mindestens ein Zwischenverzeichnis ist nicht vorhanden; Diese Funktion erstellt nur das endgültige Verzeichnis im Pfad.
ERROR_PATH_REDIRECTED	lpNewDirectory wurde durch Analysepunkte und/oder symbolische Verknüpfungen umgeleitet.

Bemerkungen

Einige Dateisysteme, z. B. das NTFS-Dateisystem, unterstützen die Komprimierung oder Verschlüsselung für einzelne Dateien und Verzeichnisse. Bei Volumes, die für ein solches Dateisystem formatiert sind, erbt ein neues Verzeichnis die Komprimierungs- und Verschlüsselungsattribute des übergeordneten Verzeichnisses.

Eine Anwendung kann ein Handle für ein Verzeichnis abrufen, indem Sie CreateFile mit dem FILE_FLAG_BACKUP_SEMANTICS Flagsatz aufrufen. Ein Codebeispiel finden Sie unter CreateFile.

Um Vererbungsfunktionen zu unterstützen, die den Sicherheitsdeskriptor dieses Objekts abfragen, kann heuristisch bestimmen und melden, dass die Vererbung wirksam ist. Weitere Informationen finden Sie unter "Automatische Verteilung von vererbbaren ACEs ".

Diese Funktion wird von den folgenden Technologien unterstützt:

Technologie	Unterstützt
Server Message Block (SMB) 3.0-Protokoll	Ja
SMB 3.0 Transparentes Failover (TFO)	Ja
SMB 3.0 mit Skalierungsdateifreigaben (SO)	Ja
Freigegebenes Clustervolumedateisystem (CsvFS)	Ja
Robustes Dateisystem (Resilient File System (ReFS))	Ja

Hinweis

Der fileapi.h Header definiert CreateDirectory2 als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Beispiele

Im folgenden Beispiel wird ein neues Verzeichnis mit der CreateDirectory2-Funktion erstellt. Das neue Verzeichnis wird mit den FILE_LIST_DIRECTORY - und SYNCHRONIZE-Zugriffsrechten erstellt. Das neue Verzeichnis wird auch mit dem FILE_SHARE_READ Freigabemodus erstellt, mit dem andere Prozesse das Verzeichnis für den Lesezugriff öffnen können.

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

Weitere Beispiele finden Sie unter Abrufen und Ändern von Dateiattributen.

Anforderungen

Anforderung	Wert
Unterstützter Client (Mindestversion)	Windows 11 24H2 [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2025 [Desktop-Apps \| UWP-Apps]
Kopfzeile	fileapi.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll

Siehe auch

CreateFile3

DeleteFile2

RemoveDirectory2

Feedback

War diese Seite hilfreich?

Last updated on 2025-04-11