MoveFile(src$, dst$[, t])

MoveFile(src$, dst$[, func, userdata])

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 specify a callback function which monitors the progress of this operation.

MoveFile() supports several optional arguments. Before Hollywood 9.0, those had to be passed as optional parameters (see above). Since Hollywood 9.0, however, it is recommended to use the new syntax, which has a single optional table argument that can be used to pass one or more optional arguments to MoveFile().

The following table fields are recognized by this function:

Force:

If this tag is set to True, write- or delete-protected files will automatically be deleted without asking the callback function first. Note that if there is no callback function and Force is set to False (the default), MoveFile() will just skip all write- or delete-protected files instead of deleting them. Note that Force is only used when MoveFile() actually needs to delete files, i.e. when moving files from one volume to another. Moving files on the same volume doesn't involve any deleting. Defaults to False. (V9.0)

BufferSize:

This table field can be used to set the buffer size that should be used when copying files. The value passed here must be specified in bytes. The default is 16384, i.e. 16 kilobytes. Note that BufferSize is only used when MoveFile() actually needs to copy files, i.e. when moving files from one volume to another. Moving files on the same volume doesn't involve copying. (V9.0)

FailOnError:

By default, MoveFile() will fail if a file or directory can't be copied or deleted. You can change this behaviour by setting FailOnError to False. In that case, MoveFile() won't fail if a file or directory can't be copied or deleted but instead your callback function, if there is one, will be notified using the #MOVEFILE_COPYFAILED and #MOVEFILE_DELETEFAILED messages and your callback must tell MoveFile() how to proceed (retry, continue, abort). See below to learn how to set up a callback function for MoveFile(). Note that FailOnError is only used when MoveFile() actually needs to copy and delete files, i.e. when moving files from one volume to another. Moving files on the same volume doesn't involve any copying or deleting. FailOnError defaults to True. (V9.0)

Async:

If this is set to True, MoveFile() will operate in asynchronous mode. This means that it will return immediately, passing an asynchronous operation handle to you. You can then use this asynchronous operation handle to finish the operation by repeatedly calling ContinueAsyncOperation() until it returns True. This is very useful in case your script needs to do something else while the operation is in progress, e.g. displaying a status animation or something similar. By putting MoveFile() into asynchronous mode, it is easily possible for your script to do something else while the operation is being processed. See ContinueAsyncOperation for details. Defaults to False. (V9.0)

Adapter:

This tag allows you to specify one or more filesystem adapters that should be asked to handle the operation. This must be set to a string containing the name(s) of one or more adapter(s). Defaults to the adapter set using SetDefaultAdapter(). See Loaders and adapters for details. (V10.0)

UserTags:

This tag can be used to specify additional data that should be passed to filesystem adapters. If you use this tag, you must set it to a table of key-value pairs that contain the additional data that should be passed to plugins. See User tags for details. (V10.0)

Callback:

For fine-tuned control of the move operation, you can specify a callback function that will be called on various occasions. For example, MoveFile() will call it from time to time so that you can update a progress bar. It will also be called when a file is delete-protected to ask you how to proceed. If there is no callback function, MoveFile() will silently skip delete-protected files. The callback function receives one argument: A table that contains more information.

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 any 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.

The following callback types are available:

#MOVEFILE_UNPROTECT:

The callback function of type #MOVEFILE_UNPROTECT will be called when MoveFile() needs 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 table field (see below).

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.

#MOVEFILE_DELETE:

This callback will be run whenever a file is deleted. The callback function of type #MOVEFILE_DELETE should normally return False. If it returns True, MoveFile() will abort the entire operation.

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 table field (see below).

#MOVEFILE_COPY:

This callback will be called while MoveFile() is copying files. The callback function of type #MOVEFILE_COPY should normally return False. If it returns True, MoveFile() will abort the entire operation.

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 table field (see below).

#MOVEFILE_DELETEFAILED:

This callback can only be called if the FailOnError tag has been set to False (see above). In that case, the callback function of type #MOVEFILE_DELETEFAILED will be called whenever a delete operation has failed. It has to return True to abort the entire operation, False to continue even though an error has occurred or -1 to retry the delete operation that has just failed. The following fields will be set in the table parameter that is passed to your callback function:

Action:

#MOVEFILE_DELETEFAILED

File:

Contains the fully qualified path of the file that could not be deleted.

UserData:

Contains the value you passed in the UserData table field (see below).

(V9.0)

#MOVEFILE_COPYFAILED:

This callback can only be called if the FailOnError tag has been set to False (see above). In that case, the callback function of type #MOVEFILE_COPYFAILED will be called whenever a copy operation has failed. It has to return True to abort the entire operation, False to continue even though an error has occurred or -1 to retry the copy operation that has just failed. The following fields will be set in the table parameter that is passed to your callback function:

Action:

#MOVEFILE_COPYFAILED

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 written (destination).

UserData:

Contains the value you passed in the UserData table field (see below).

(V9.0)

UserData:

This field can be used to pass an arbitrary value to your callback function. The value you specify here will be passed to your callback function whenever it is called. This is useful if you want to avoid working with global variables. Using the UserData tag 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. Your callback will receive this data in the UserData field in the table that is passed to it.

src$

source file or directory to move

dst$

destination file or directory; must not exist

t

optional: table containing additional options (see above) (V9.0)

MoveFile("image.png", "images/image.png")