CreateDirectoryA function (fileapi.h)

Creates a new directory. If the underlying file system supports security on files and directories, the function applies a specified security descriptor to the new directory.

To specify a template directory, use the CreateDirectoryEx function.

To perform this operation as a transacted operation, use the CreateDirectoryTransacted function.

Syntax

Parameters

The path of the directory to be created.

For the ANSI version of this function, there is a default string size limit for paths of 248 characters (MAX_PATH — enough room for a 8.3 filename). To extend this limit to 32,767 wide characters, call the Unicode version of the function and prepend «\\?\» to the path. For more information, see Naming a File

A pointer to a SECURITY_ATTRIBUTES structure. The lpSecurityDescriptor member of the structure specifies a security descriptor for the new directory. If lpSecurityAttributes is NULL, the directory gets a default security descriptor. The ACLs in the default security descriptor for a directory are inherited from its parent directory.

The target file system must support security on files and directories for this parameter to have an effect. (This is indicated when GetVolumeInformation returns FS_PERSISTENT_ACLS.)

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. Possible errors include the following.

Return code	Description
ERROR_ALREADY_EXISTS	The specified directory already exists.
ERROR_PATH_NOT_FOUND	One or more intermediate directories do not exist; this function will only create the final directory in the path.

Remarks

Some file systems, such as the NTFS file system, support compression or encryption for individual files and directories. On volumes formatted for such a file system, a new directory inherits the compression and encryption attributes of its parent directory.

An application can obtain a handle to a directory by calling CreateFile with the FILE_FLAG_BACKUP_SEMANTICS flag set. For a code example, see CreateFile.

To support inheritance functions that query the security descriptor of this object may heuristically determine and report that inheritance is in effect. See Automatic Propagation of Inheritable ACEs for more information.

In WindowsВ 8 and Windows ServerВ 2012, this function is supported by the following technologies.

Technology	Supported
Server Message Block (SMB) 3.0 protocol	Yes
SMB 3.0 Transparent Failover (TFO)	Yes
SMB 3.0 with Scale-out File Shares (SO)	Yes
Cluster Shared Volume File System (CsvFS)	Yes
Resilient File System (ReFS)	Yes

В

Examples

The fileapi.h header defines CreateDirectory as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Known Folders

WindowsВ Vista introduces new storage scenarios and a new user profile namespace. To address these new factors, the older system of referring to standard folders by a CSIDL value has been replaced. As of WindowsВ Vista, those folders are referenced by a new set of GUID values called Known Folder IDs.

The Known Folder system provides these advantages:

• Independent software vendors (ISVs) can extend the set of Known Folder IDs with their own. They can define folders, give them IDs, and register them with the system. CSIDL values could not be extended.
• All Known Folders on a system can be enumerated. No API provided this functionality for CSIDL values. See IKnownFolderManager::GetFolderIds for more information.
• A known folder added by an ISV can add custom properties that allow it to explain its purpose and intended use.
• Many known folders can be redirected to new locations, including network locations. Under the CSIDL system, only the My Documents folder could be redirected.
• Known folders can have custom handlers for use during creation or deletion.

The CSIDL system and APIs that make use of CSIDL values are still supported for compatibility. However, it is not recommended to use them in any new development.

The following topics discuss the specifics of the Known Folders system.

The following reference pages explain the Win32 Known Folders functions, which can be used to retrieve the location of Known Folders or redirect them to a new location. These functions replace older Win32 functions. The new functions are provided to give equivalent behavior to the old functions, but each new function is also duplicated by a Component Object Model (COM) API.

New Function	Replaces	COM Equivalent
SHGetKnownFolderPath	SHGetFolderPath	IKnownFolder::GetPath
SHGetKnownFolderIDList	SHGetFolderLocation	IKnownFolder::GetIDList
SHSetKnownFolderPath	SHSetFolderPath	IKnownFolder::SetPath

The following reference pages explain the COM Known Folders APIs, which provide all of the functionality of the Win32 APIs listed above, plus add the ability to enumerate all Known Folders, access Known Folder properties, and extend the standard set of Known Folders.

A C++ sample that demonstrates the Known Folder APIs is included in the Windows Software Development Kit (SDK). Once you have installed the Windows SDK on your computer, the sample can be found under %ProgramFiles%\Microsoft SDKs\Windows\v6.0\Samples\WinUI\Shell\AppPlatform\KnownFolders.

Known Folders Class

Definition

Provides access to common locations that contain user content. This includes content from a user’s local libraries (such as Documents, Pictures, Music, and Videos), HomeGroup, removable devices, and media server devices.

Windows 10 requirements

Examples

The File access sample shows you how to use the PicturesLibrary property to create a new file in the Pictures library.

After the CreateFileAsync method completes, the file variable contains a StorageFile that represents the new file.

Remarks

This class is static and cannot be instantiated. Access its properties directly, as shown in the following example.

• StorageFolder storageFolder = KnownFolders.PicturesLibrary;

Prerequisites

To access the folders and libraries represented by the properties of this class, specify the corresponding capabilities in your app manifest. For example, to access KnownFolders.PicturesLibrary, specify the Pictures Library capability in the app manifest. Learn more about capabilities in App capability declarations.

Return value

The properties of the KnownFolders class return a StorageFolder. To work with the known folder and its contents, call the methods and properties of the StorageFolder class.

• For info about how to use pictures, music, and videos in your app, see Audio, video, and camera.
• For general info about how to use files and folders, see Enumerate and query files and folders.

More info

Here’s how to access some other commonly used locations.

To learn more about the locations that your app can access, see File access permissions.

Version history

Windows version	SDK version	Value added
1511	10586	GetFolderForUserAsync
2004	19041	GetFolderAsync
2004	19041	RequestAccessAsync
2004	19041	RequestAccessForUserAsync

Properties

Gets the App Captures folder.

Gets the Camera Roll folder.

Gets the Documents library. The Documents library is not intended for general use.

Gets the HomeGroup folder.

Gets the folder of media server (Digital Living Network Alliance (DLNA)) devices.

Gets the Music library.

Gets the Objects 3D folder.

Gets the Pictures library.

Gets the play lists folder.

Gets the recorded calls folder.

Gets the removable devices folder.

Gets the Saved Pictures folder.

Gets the Videos library.

Methods

Retrieves the folder for the folderId specified.

Static method that returns a specified known folder for a User.

Requests access for the capability controlling access to the folder.

Storage Folder Class

Definition

Manages folders and their contents and provides information about them.

Windows 10 requirements

Remarks

Typically you get StorageFolder objects as the return value of asynchronous method calls. For example, the static method GetFolderFromPathAsync returns a StorageFolder that represents the specified folder.

Note that when you call a file picker to let the user pick a folder, the file picker returns the folder as a StorageFolder.

There is not currently a «MoveAsync» or similar method. One simple implementation of moving a folder might be to get the desired folder, copy it to the desired location, and then delete the original folder.

Version history

Windows version	SDK version	Value added
1803	17134	TryGetChangeTracker
2004	19041	GetFolderFromPathForUserAsync

Properties

Gets the attributes of the current folder.

Gets the date and time that the current folder was created.

Gets the user-friendly name of the current folder.

Gets the user-friendly description of the type of the folder; for example, JPEG image .

Gets an identifier for the current folder. This ID is unique for the query result or StorageFolder that contains the current folder or file group, and can be used to distinguish between items that have the same name.

Gets the name of the current folder.

Gets the full path of the current folder in the file system, if the path is available.

Gets an object that provides access to the content-related properties of the current folder.

Gets the StorageProvider object that contains info about the service that stores the current folder.

Methods

Indicates whether the current folder supports the specified QueryOptions.

Creates a new file with the specified name in the current folder.

Creates a new file in the current folder. This method also specifies what to do if a file with the same name already exists in the current folder.

Gets a query result object that contains the files in the current folder.

Gets a query result object that contains the files in the current folder. Also gets the files from the subfolders of the current folder when the value of the query argument is something other than CommonFileQuery.DefaultQuery. Files are sorted based on the specified CommonFileQuery.

Gets a query result object that contains the files in the current folder and, optionally, in the subfolders of the current folder. The results are based on the specified QueryOptions.

Creates a new subfolder with the specified name in the current folder.

Creates a new subfolder with the specified name in the current folder. This method also specifies what to do if a subfolder with the same name already exists in the current folder.

Gets a query result object that contains the subfolders in the current folder.

Gets a query result object that contains the subfolders in the current folder. When the value of the query argument is something other than CommonFolderQuery.DefaultQuery, gets a list of virtual folders that represent containers for groups of files in the subfolders of the current folder. Files are grouped into folders based on the specified value from the CommonFolderQuery enumeration.

Gets a query result object that contains the subfolders in the current folder and, optionally, nested subfolders. The results are based on the specified QueryOptions.

Gets a query result object that contains the files and subfolders in the current folder.

Gets a query result object that contains the files and subfolders in the current folder and, optionally, in the subfolders of the current folder. The results are based on the specified QueryOptions.

Deletes the current folder.

Deletes the current folder. This method also specifies whether to delete the folder permanently.

Gets the basic properties of the current folder or file group.

Gets the file with the specified name from the current folder.

Gets the files in the current folder.

Gets the files in the current folder. Also gets the files from the subfolders of the current folder when the value of the query argument is something other than CommonFileQuery.DefaultQuery. Files are sorted based on the specified value from the CommonFileQuery enumeration.

Gets an index-based range of files from the list of all files in the current folder. Also gets the files from the subfolders of the current folder when the value of the query argument is something other than CommonFileQuery.DefaultQuery. Files are sorted based on the specified value from the CommonFileQuery enumeration.

Gets the subfolder with the specified name from the current folder.

Gets the folder that has the specified absolute path in the file system.

Gets the StorageFolder based on an absolute path in the file system for a given user.

Gets the subfolders in the current folder.

Gets the subfolders in the current folder. When the value of the query argument is something other than CommonFolderQuery.DefaultQuery, gets a list of virtual folders that represent containers for groups of files in the subfolders of the current folder. Files are grouped into folders based on the specified value from the CommonFolderQuery enumeration.

Gets an index-based range of folders from the list of all subfolders in the current folder. When the value of the query argument is something other than CommonFolderQuery.DefaultQuery, gets a list of virtual folders that represent containers for groups of files in the subfolders of the current folder. Files are grouped into folders based on the specified value from the CommonFolderQuery enumeration.

Gets the indexed state of the current folder.

Gets the file or folder with the specified name from the current folder.

Gets the files and subfolders in the current folder.

Gets an index-based range of files and folders from the list of all files and subfolders in the current folder.

Gets the parent folder of the current folder.

Gets a scaled image as a thumbnail, determined by the purpose of the thumbnail.

Gets a scaled image as a thumbnail, determined by the purpose of the thumbnail and the requested size.

Gets a scaled image as a thumbnail, determined by the purpose of the thumbnail, the requested size, and the specified options

Gets a thumbnail image for the current folder, sized for the specified purpose of the thumbnail.

Gets a thumbnail image for the current folder, sized for the specified purpose of the thumbnail and adjusted to the requested size.

Gets a thumbnail image for the current folder, sized for the specified purpose of the thumbnail and adjusted to the requested size with the specified options.

Indicates whether the current folder supports the specified CommonFileQuery.

Indicates whether the current folder supports the specified CommonFolderQuery.

Indicates whether the current folder is equal to the specified folder.

Indicates whether the current StorageFolder matches the specified StorageItemTypes value.

Renames the current folder.

Renames the current folder and specifies what to do if a folder with the same name already exists.

Tries to get the file or folder with the specified name from the current folder. Returns null instead of raising a FileNotFoundException if the specified file or folder is not found.