If the method succeeds, the return value is the number of
characters copied into the string buffer, not including the
terminating null character. If the
client ID does not specify a valid client session,
the method will return zero. If the string buffer is not large
enough to contain the complete path, this method will return zero
and the last error code will be set to ST_ERROR_BUFFER_TOO_SMALL.
A virtual path for the
client is either relative to the server root directory, or the client home
directory if the client was authenticated as a restricted user. These
virtual paths are what the client will see as an absolute path on the server.
For example, if the server was configured to
use "C:\ProgramData\MyServer" as the root directory, and
the lpszLocalPath parameter was specified as
"C:\ProgramData\MyServer\Documents\Research", this method
would return the virtual path to that directory as
"/Documents/Research".
If the client session was authenticated as a restricted user, then
the virtual path is always relative to the client home directory
instead of the server root directory. This is because restricted users
are isolated to their own home directory and any subdirectories. For
example, if restricted user "John" has a home directory of
"C:\ProgramData\MyServer\Users\John" and the lpszLocalPath
parameter was specified as
"C:\ProgramData\MyServer\Users\John\Accounting\Projections.pdf"
this method would return the virtual path as
"/Accounting/Projections.pdf".
If the lpszLocalPath parameter specifies a file or
directory outside of the server root directory, this method will
return zero and the last error code will be set to
ST_ERROR_INVALID_FILE_NAME. This method can only be used with
authenticated clients. If the nClientId parameter specifies a
client session that has not been authenticated, this method will
return zero and the last error code will be
ST_ERROR_AUTHENTICATION_REQUIRED.