Edit

Share via

SHCreateDirectoryExA function (shlobj_core.h)

  • Article

[This function is available through Windows XP Service Pack 2 (SP2) and Windows Server 2003. It might be altered or unavailable in subsequent versions of Windows.]

Creates a new file system folder, with optional security attributes.

Syntax

int SHCreateDirectoryExA(
  [in, optional] HWND                      hwnd,
  [in]           LPCSTR                    pszPath,
  [in, optional] const SECURITY_ATTRIBUTES *psa
);

Parameters

[in, optional] hwnd

Type: HWND

A handle to a parent window. This parameter can be set to NULL if no user interface will be displayed.

[in] pszPath

Type: LPCTSTR

A pointer to a null-terminated string specifying the fully qualified path of the directory. This string is of maximum length of 248 characters, including the terminating null character.

[in, optional] psa

Type: const SECURITY_ATTRIBUTES*

A pointer to a SECURITY_ATTRIBUTES structure with the directory's security attribute. Set this parameter to NULL if no security attributes need to be set.

Return value

Type: int

Returns ERROR_SUCCESS if successful. If the operation fails, other error codes can be returned, including those listed here. For values not specifically listed, see System Error Codes.

Return code Description
ERROR_BAD_PATHNAME
 The pszPath parameter was set to a relative path.
ERROR_FILENAME_EXCED_RANGE
 The path pointed to by pszPath is too long.
ERROR_PATH_NOT_FOUND
 The system cannot find the path pointed to by pszPath. The path may contain an invalid entry.
ERROR_FILE_EXISTS
 The directory exists.
ERROR_ALREADY_EXISTS
 The directory exists.
ERROR_CANCELLED
 The user canceled the operation.

Remarks

This function creates a file system folder whose fully qualified path is given by pszPath. If one or more of the intermediate folders do not exist, they are created as well. SHCreateDirectoryEx also verifies that the files are visible. If they are not visible, expect one of the following:

  • If hwnd is set to a valid window handle, a message box is displayed warning the user that he or she might not be able to access the files. If the user chooses not to proceed, the function returns ERROR_CANCELLED.
  • If hwnd is set to NULL, no user interface is displayed and the function returns ERROR_CANCELLED.

Note

The shlobj_core.h header defines SHCreateDirectoryEx as an alias that 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 is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header shlobj_core.h (include Shlobj.h, Shlobj_core.h)
Library Shell32.lib
DLL Shell32.dll (version 5.0 or later)

See also

SHCreateDirectory