SHFileOperationA function (shellapi.h)

Copies, moves, renames, or deletes a file system object. This function has been replaced in Windows Vista by IFileOperation.

Syntax

int SHFileOperationA(
  [in, out] LPSHFILEOPSTRUCTA lpFileOp
);

Parameters

[in, out] lpFileOp

Type: LPSHFILEOPSTRUCT

A pointer to an SHFILEOPSTRUCT structure that contains information this function needs to carry out the specified operation. This parameter must contain a valid value that is not NULL. You are responsible for validating the value. If you do not validate it, you will experience unexpected results.

Return value

Type: int

Returns zero if successful; otherwise nonzero. Applications normally should simply check for zero or nonzero.

It is good practice to examine the value of the fAnyOperationsAborted member of the SHFILEOPSTRUCT. SHFileOperation can return 0 for success if the user cancels the operation. If you do not check fAnyOperationsAborted as well as the return value, you cannot know that the function accomplished the full task you asked of it and you might proceed under incorrect assumptions.

Do not use GetLastError with the return values of this function.

To examine the nonzero values for troubleshooting purposes, they largely map to those defined in Winerror.h. However, several of its possible return values are based on pre-Win32 error codes, which in some cases overlap the later Winerror.h values without matching their meaning. Those particular values are detailed here, and for these specific values only these meanings should be accepted over the Winerror.h codes. However, these values are provided with these warnings:

• These are pre-Win32 error codes and are no longer supported or defined in any public header file. To use them, you must either define them yourself or compare against the numerical value.
• These error codes are subject to change and have historically done so.
• These values are provided only as an aid in debugging. They should not be regarded as definitive.

Error Code	Value	Meaning
DE_SAMEFILE	0x71	The source and destination files are the same file.
DE_MANYSRC1DEST	0x72	Multiple file paths were specified in the source buffer, but only one destination file path.
DE_DIFFDIR	0x73	Rename operation was specified but the destination path is a different directory. Use the move operation instead.
DE_ROOTDIR	0x74	The source is a root directory, which cannot be moved or renamed.
DE_OPCANCELLED	0x75	The operation was canceled by the user, or silently canceled if the appropriate flags were supplied to SHFileOperation.
DE_DESTSUBTREE	0x76	The destination is a subtree of the source.
DE_ACCESSDENIEDSRC	0x78	Security settings denied access to the source.
DE_PATHTOODEEP	0x79	The source or destination path exceeded or would exceed MAX_PATH.
DE_MANYDEST	0x7A	The operation involved multiple destination paths, which can fail in the case of a move operation.
DE_INVALIDFILES	0x7C	The path in the source or destination or both was invalid.
DE_DESTSAMETREE	0x7D	The source and destination have the same parent folder.
DE_FLDDESTISFILE	0x7E	The destination path is an existing file.
DE_FILEDESTISFLD	0x80	The destination path is an existing folder.
DE_FILENAMETOOLONG	0x81	The name of the file exceeds MAX_PATH.
DE_DEST_IS_CDROM	0x82	The destination is a read-only CD-ROM, possibly unformatted.
DE_DEST_IS_DVD	0x83	The destination is a read-only DVD, possibly unformatted.
DE_DEST_IS_CDRECORD	0x84	The destination is a writable CD-ROM, possibly unformatted.
DE_FILE_TOO_LARGE	0x85	The file involved in the operation is too large for the destination media or file system.
DE_SRC_IS_CDROM	0x86	The source is a read-only CD-ROM, possibly unformatted.
DE_SRC_IS_DVD	0x87	The source is a read-only DVD, possibly unformatted.
DE_SRC_IS_CDRECORD	0x88	The source is a writable CD-ROM, possibly unformatted.
DE_ERROR_MAX	0xB7	MAX_PATH was exceeded during the operation.
	0x402	An unknown error occurred. This is typically due to an invalid path in the source or destination. This error does not occur on Windows Vista and later.
ERRORONDEST	0x10000	An unspecified error occurred on the destination.
DE_ROOTDIR | ERRORONDEST	0x10074	Destination is a root directory and cannot be renamed.

Remarks

You should use fully qualified path names with this function. Using it with relative path names is not thread safe.

With two exceptions, you cannot use SHFileOperation to move special folders from a local drive to a remote computer by specifying a network path. The exceptions are the My Documents (CSIDL_PERSONAL, CSIDL_DOCUMENTS) and My Pictures folders (CSIDL_MYPICTURES).

When used to delete a file, SHFileOperation permanently deletes the file unless you set the FOF_ALLOWUNDO flag in the fFlags member of the SHFILEOPSTRUCT structure pointed to by lpFileOp. Setting that flag sends the file to the Recycle Bin. If you want to simply delete a file and guarantee that it is not placed in the Recycle Bin, use DeleteFile.

If a copy callback handler is exposed and registered, SHFileOperation calls it unless you set a flag such as FOF_NOCONFIRMATION in the fFlags member of the structure pointed to by lpFileOp. See ICopyHook::CopyCallback for details on implementing copy callback handlers.

File deletion is recursive unless you set the FOF_NORECURSION flag in lpFileOp.

Connecting Files

With Windows 2000 or later, it is possible to connect an HTML file with a folder that contains related files such as Graphics Interchange Format (GIF) images or style sheets. If file connection is enabled, when you move or copy the HTML file, the connected folder and all of its files are also moved or copied. Conversely, if you move the folder with the related files, the HTML file is also moved.

The HTML file must have a .htm or .html extension. You create the connection to the related files by placing the folder that contains them into the same folder as the HTML file. The name of the folder that contains the connected files must be the same as the name of the HTML file followed by "_files" or ".files" (this is case sensitive; for example, ".Files" does not work). An example is given here.

1. Create a file named Test.htm in the C:\Files directory (C:\Files\Test.htm).
2. Create a new folder named Test.files in the C:\Files directory (C:\Files\Test.files).
3. Populate the folder with a few files. Any file placed in this folder is connected to Test.htm.
4. Move or copy the Test.htm file to the C:\Files2 directory.
5. Note that the Test.files directory is now found in the C:\Files2 directory as well.

File connection is enabled by default. It can be disabled by adding a REG_DWORD entry, NoFileFolderConnection, as shown here:

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  NoFileFolderConnection

Setting NoFileFolderConnection to 1 disables file connection. If the value is set to zero or is missing, file connection is enabled.

To move only the specified files and none of the connected files, set the FOF_NO_CONNECTED_ELEMENTS flag in the fFlags member of the structure pointed to by lpFileOp.

Note that the use of a folder with a name like "MyFile_files" to define a connection may not be valid for localized versions of Windows. The term "files" may need to be replaced by the equivalent word in the local language.

Note

The shellapi.h header defines SHFileOperation 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.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	shellapi.h
Library	Shell32.lib
DLL	Shell32.dll (version 4.0 or later)
API set	ext-ms-win-shell-shell32-l1-2-1 (introduced in Windows 10, version 10.0.10240)