SHFILEOPSTRUCT Structure

Type SHFILEOPSTRUCT
	hwnd As Long
	wFunc As Long
	pFrom As String
	pTo As String
	fFlags As Integer
	fAnyOperationsAborted As Long
	hNameMappings As Long
	lpszProgressTitle As String
End Type

Description & Usage

The SHFILEOPSTRUCT structure holds a description of a file operation to have the SHFileOperation function perform. The contents of the structure identify the operation itself (copy, move, delete, or rename) as well as the targeted files and any other options. In some cases, the structure also receives feedback information based on the actions of the operation.

Visual Basic-Specific Issues

Because of how Visual Basic byte-aligns structure contents, the SHFILEOPSTRUCT cannot be passed directly to SHFileOperation or any other API function. Instead, it must be copied to a byte array in such a way to correct for the improper byte alignment. Specifically, bytes 1 through 18 of the structure must immediately precede bytes 21 through 32. In other words, bytes 19 and 20 must be removed. (The given byte positions are given so that the first byte is byte #1.) The example code for SHFileOperation demonstrates the most straightforward way to correct for this problem.

Data Members

hwnd

A handle to the window that is performing the file operation.

wFunc

One of the following flags specifying which file operation to perform:

FO_COPY: Copy the files specified by pFrom to the location specified by pTo.
FO_DELETE: Delete the files specified by pFrom. (To send files to the Recycle Bin, use this file operation and include the FOF_ALLOWUNDO flag in fFlags.)
FO_MOVE: Move the files specified by pFrom to the location specified by pTo.
FO_RENAME: Rename the files specified by pFrom to the names specified by pTo.

pFrom

A list of one or more files that are the source of the file operation. If multiple files are specified, they must be separated by a null character. The entire string must be terminated by two null characters. Wildcard characters (* and ?) are allowed in the filenames.

pTo

A list of one or more paths or files that are the target of the file operation. If multiple files or paths are specified, they must be separated by a null character. The entire string must be terminated by two null characters. Wildcard characters (* and ?) are sometimes allowed, depending on the operation. Always specify the entire path and filename for any files or directories.

fFlags

A combination of the following flags specifying other options or settings:

FOF_ALLOWUNDO: Allow the user to Undo the file operation, if possible. All paths must be fully qualified for this flag to work.
FOF_FILESONLY: If a *.* wildcard file is specified in pFrom or pTo, only perform the file operation on the files (and not the directories).
FOF_MULTIDESTFILES: pTo specifies multiple destination files -- one for each source file in pFrom -- instead of a single target for all source files.
FOF_NOCONFIRMATION: Do not prompt the user with any confirmation dialogs, instead assuming a "Yes to All" response.
FOF_NOCONFIRMMKDIR: Do not confirm the creation of a new directory if the file operation requires one to be made.
FOF_NO_CONNECTED_ELEMENTS: Windows 2000: Do not move connected files as a group; instead, move only the specified files.
FOF_NOCOPYSECURITYATTRIBS: Windows NT 4.71 and later, 2000: Do not copy the security attributes of the files.
FOF_NOERRORUI: Do not display a message box if an error occurs.
FOF_NORECURSION: Only perform the file operation in the specified directory, not operating recursively into its subdirectories.
FOF_RENAMEONCOLLISION: If a file being moved, copied, or renamed conflicts with an existing file, give the file operated on a new name.
FOF_SILENT: Do not display a progress dialog box.
FOF_SIMPLEPROGRESS: Display a progress dialog box displaying the text specified by lpszProgressTitle but do not display the file names being processed.
FOF_WANTMAPPINGHANDLE: Create a SHNAMEMAPPING structure to identify any files that must be renamed as a result of the FOF_RENAMEONCOLLISION flag. A handle to this structure is put into hNameMappings.
FOF_WANTNUKEWARNING: Windows 2000: Warn the user if a file is being deleted rather than being sent to the Recycle Bin.

fAnyOperationsAborted

Receives a nonzero value if the user aborted any file operations before they were complete. This receives 0 if all operations completed without user intervention.

hNameMappings

If fFlags contains FOF_WANTMAPPINGHANDLE, this receives a handle to an array of SHNAMEMAPPING structures that identify which files were renamed. After use, this handle must be freed by the SHFreeNameMappings function. NOTE: I have not been able to figure out how to use the mapping handle placed in this data member. If anyone knows how, please e-mail me.

lpszProgressTitle

If fFlags contains the FOF_SIMPLEPROGRESS flag, this is the text to display in the progress dialog box. This string must be null-terminated.

Constant Definitions

Const FO_COPY = &H2
Const FO_DELETE = &H3
Const FO_MOVE = &H1
Const FO_RENAME = &H4
Const FOF_ALLOWUNDO = &H40
Const FOF_FILESONLY = &H80
Const FOF_MULTIDESTFILES = &H1
Const FOF_NOCONFIRMATION = &H10
Const FOF_NOCONFIRMMKDIR = &H200
Const FOF_NO_CONNECTED_ELEMENTS = &H1000
Const FOF_NOCOPYSECURITYATTRIBS = &H800
Const FOF_NOERRORUI = &H400
Const FOF_RENAMEONCOLLISION = &H8
Const FOF_SILENT = &H4
Const FOF_SIMPLEPROGRESS = &H100
Const FOF_WANTMAPPINGHANDLE = &H20
Const FOF_WANTNUKEWARNING = &H2000

Used By

SHFileOperation

Back to the Structure list.
Back to the Reference section.

Last Modified: April 16, 2000
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vbapi.com/ref/s/shfileopstruct.html