INT GetCommandFile(
	UINT nClientId,
	LPTSTR lpszFileName,
	INT nMaxLength
);

INT GetCommandFile(
	UINT nClientId,
	CString& strFileName
);

Get the full path to a file name or directory specified by the client.

Parameters

nClientId

An unsigned integer which uniquely identifies the client session.

lpszFileName

A pointer to a string buffer that will contain the full path to a file name or directory specified by the client when it issued a command. The string buffer will be null terminated and must be large enough to store the complete file path. This parameter cannot be NULL. An alternate version of this method accepts a CString object if it is available.

nMaxLength

An integer value that specifies the maximum number of characters that can be copied into the string buffer. It is recommended that the buffer be at least MAX_PATH characters in size. If the maximum length specified is smaller than the actual length of the full path, this method will fail.

Return Value

An integer value which specifies the number of characters copied into the buffer, not including the terminating null character. If the method fails, the return value will be zero and the GetLastError method can be used to retrieve the last error code.

Remarks

The GetCommandFile method is used to obtain the full path to a local file name or directory specified by the client as an argument to a standard HTTP command. For example, if the client sends the GET command to the server, this method will return the complete path to the local file that the client wants to retrieve. This method will only work with those standard commands that perform some action on a file or directory.

This method should always be used to obtain the file name for a command that performs a file or directory operation. It normalizes the path provided by the client and ensures that it specifies a file or directory name in the correct location. The GetCommandUrl method can be used to obtain the URL that was provided by the client.

To map a virtual path to a file or directory on the local system, use the AddVirtualPath method. To redirect a client to use a different URL to access the resource, use the RedirectRequest method.

The SetCommandFile method can be used to change the name of the local file or directory that is the target of the command, however using this method to redirect access to a resource can have unintended side-effects, particularly in the case where the URL provided by the client actually resolves to an executable CGI program that handles the request.

If the client has provided a URL that resolves to a CGI program that handles the request, this method behaves differently than if the URL is resolved to a local file or directory. If the client uses the GET or POST command that results in a program being executed to handle the request, this method will return the path to the server root directory along with any additional path information provided in the URL. In other words, the file name returned by this method will be the same as the PATH_TRANSLATED value passed to the CGI program.

This method should only be called after the client request has been received by the server, typically inside a OnCommand or OnExecute event handler. It should not be called inside a OnConnect event handler because the server has not processed the client request at that point.

Requirements

Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: cshtsv11.lib
Unicode: Implemented as Unicode and ANSI versions

See Also

AddVirtualPath, GetCommandUrl, RedirectRequest, SetCommandFile, OnCommand, OnExecute

Copyright © 2025 Catalyst Development Corporation. All rights reserved.