If the lpszNewFileName parameter specifies a file which
already exists on the server, the contents of that file will be
deleted and replaced by the contents of the file specified by
lpszOldFileName. If you want to prevent this from occurring, your
application can check if a file with the new name exists by calling
the GetFileStatus method. If successful, you can warn the
user the rename operation would delete the contents of the new file as
a consequence of renaming the original file.
If the connection was established using the standard FTP or FTPS
protocols, this method causes two separate commands to be sent to the
server, RNFR and RNTO. If either command fails, the method
will fail and return an error code. If the connection was established
using SFTP (SSH) the client will request the server rename the file
atomically by specifying the internal SSH_FXF_RENAME_ATOMIC option. If
the server does not support this option and lpszNewFileName
already exists on the server, this method will attempt to delete the file
and retry the rename operation.
This method can be used to move a file from one folder to another
on the server, as long as the user has the appropriate permissions
required to perform the operation. If the new file name includes a
path, that path must already exist on the server or the method will
fail.
If the old and new file names specify folders instead of regular
files, the server may or may not allow the operation, depending on the
access rights for those folders and the server's configuration. Some
servers may allow a simple rename operation within the same parent
folder, but may not permit you to move the folder to another location
in the filesystem.
There is no guarantee the rename operation will be performed
in an atomic fashion if multiple client sessions attempt to rename the
same file at the same time. For example, it is possible that one
client could attempt to rename a file while another client is already
in the process of moving the file to a new folder. In this case, the
server may respond with an error indicating the file cannot be found,
an access denied error or a general failure error.