Name
MoveFile -- move file or directory (V7.1)
Synopsis
MoveFile(src$, dst$[, func, userdata])
Function
This function moves the file or directory specified in src$ to the file or directory specified in dst$. Note that dst$ must not exist or MoveFile() will fail. Also, src$ must not be a volume's root directory because this obviously cannot be moved anywhere.

Moving files (or directories) on the same volume is really quick and takes almost no time. When moving files from one volume to another, MoveFile() first has to copy the files and in a second step, delete them from the original volume. This process is much slower than moving files around on the same volume. That is why you can pass a callback function in the func parameter which monitors the progress of this operation.

The callback function is then called by MoveFile() from time to time. It always receives a table as its sole argument. The table will always have the Action field initialized, all other fields depend on the contents of the Action field. The following callback types are currently supported:

The callback function of type #MOVEFILE_UNPROTECT is called if MoveFile() wants to delete a file which is delete-protected. The parameter table for this callback type will contain the following fields:

Action:
#MOVEFILE_UNPROTECT

File:
Contains the fully qualified path to the file that is delete-protected.

UserData:
Contains the value you passed in the userdata argument.

This callback function needs to return True if it is okay to unprotect the file or False if it shall not be unprotected. If you return -1, the move operation will be completely aborted.

Callback function type #MOVEFILE_DELETE:

Action:
#MOVEFILE_DELETE

File:
Contains the fully qualified path of the file that is to be deleted next.

UserData:
Contains the value you specified in the userdata argument.

The callback function of type #MOVEFILE_DELETE should normally return False. If it returns True, the delete operation will be aborted.

Callback function type #MOVEFILE_COPY:

Action:
#MOVEFILE_COPY

Source:
Contains the fully qualified path of the file that is currently being copied (source).

Destination:
Contains the fully qualified path of the file that is currently being copied (destination).

Copied:
Contains the number of bytes that have already been copied.

Filesize:
Contains the filesize of the source file.

UserData:
Contains the value you passed in the userdata argument.

The callback function of type #MOVEFILE_COPY should normally return False. If it returns True, the copy operation will be aborted.

Note that the callback function will only be called when moving files across volumes. Moving files on the same volume can be done instantly and won't result in a callback invocation. Also note that if files are moved across volumes and you do not specify a callback function, files that are delete-protected won't be deleted but will just be copied to the new location without deleting the old file.

Finally, there is also an optional argument called userdata. The value you specify here is passed to your callback function whenever it is called. This is useful if you want to avoid working with global variables. Using the userdata argument you can easily pass data to your callback function. You can specify a value of any type in userdata. Numbers, strings, tables, and even functions can be passed as user data.

Inputs
src$
source file or directory to move
dst$
destination file or directory; must not exist
func
optional: callback function monitoring progress
userdata
optional: user specific data to pass to callback function
Example
MoveFile("image.png", "images/image.png")
Moves the file "image.png" to the subdirectory "images" while keeping its name.

Show TOC