The SetCommandFile method is used by the application to
change the target file or directory name for the current command from
within an OnCommand event handler. This can be used to
effectively redirect the client to use a different file than the one
that was actually requested. For example, if the client issues the
GET command to download a file from the server, this method can be
used to redirect the command to use a different file name. To obtain
the full path to the file or directory that is the target of the
current command, use the GetCommandFile method.
The lpszFileName parameter specifies the path to the new
file or directory name. If the path is absolute, then it will be used
as-is. If the path is relative, it will be relative to the root directory
for the client session. Because the root document directory for the
client can depend on the hostname that the client used when connecting
to the server, it is recommended that you always use an absolute path.
The full path to this file is not limited to the server root directory
or its subdirectory, it can specify a file anywhere on the local system.
If this parameter is a NULL pointer, or points to an empty string,
then the server will revert to using the actual file or directory name
specified by the command. This enables the application to effectively
undo a previous call to this method to change the target file name.
Typically this method would be used to redirect a client to a
file or directory that it may not normally have access to. Exercise
caution when using this method to provide access to data that is
stored outside of the server root directory. Incorrect use of this
method could expose the server to security risks or cause
unpredictable behavior by client applications. In most cases it is
preferable to use the AddVirtualPath method to create a
virtual path or file name on the server, or the RedirectRequest
method to request the client use a different URL to access the
resource.
This method should only be called within the context of the
OnCommand event, and only for those commands that perform an
action on a file or directory. If the current command does not target
a file or directory, this method will return zero and the last error
code will be set to ST_ERROR_INVALID_COMMAND.