GetFileTitle
The GetFileTitle
function returns the name of the file identified by the lpszFile
parameter.
short GetFileTitle(
|
LPCTSTR lpszFile, |
// pointer to full
path and filename for file |
|
LPTSTR lpszTitle, |
// pointer to
buffer that receives filename |
|
WORD cbBuf |
// length of buffer |
|
); |
|
Parameters
lpszFile
Pointer to
the name and location of a file.
lpszTitle
Pointer to a
buffer into which the function is to copy the name of the file.
cbBuf
Specifies the
length, in characters, of the buffer pointed to by the lpszTitle
parameter.
Return Values
If the function
succeeds, the return value is zero.
If the
filename is invalid, the return value is a negative number.
If the buffer
pointed to by the lpszTitle parameter is too small, the return value is
a positive integer that specifies the required buffer size, in bytes (ANSI
version) or characters (Unicode version). The required buffer size includes the
terminating null character.
Remarks
The GetFileTitle
function returns an error value if the buffer pointed to by the lpszFile
parameter contains any of the following elements:
An empty string
A string containing a wildcard
(*), opening bracket ([), or closing bracket (])
A string that ends with a colon
(:), slash mark (/), or backslash (\)
A string whose length exceeded
the length of the buffer
An invalid character (for
example, a space or an unprintable character)
To get the
buffer size needed for the name of a file, call the function with lpszTitle
set to NULL and cbBuf set to zero. The function will return the required
size.
GetFileTitle returns the string that the system would use to
display the filename to the user. The display name includes an extension only
if that is the user s preference for displaying filenames. This means that the
returned string may not accurately identify the file if it is used in calls to
file system functions.
If the lpszTitle
buffer is too small, GetFileTitle returns the size required to hold the
display name. There is no guaranteed connection between the required size and
the characters originally specified in the lpszFile buffer. In porting
applications to Windows 95 and Windows NT, developers will need to update any code
that relies on such behavior in previous versions of the operating system. The
most common case is code that deliberately calls GetFileTitle with lpszTitle
set to NULL and cbBuf set to zero, and then uses the return value as an
index into the lpszFile string. This technique is no longer supported.
You can usually achieve similar results (and superior performance) with
run-time library functions such as strrchr, wcsrchr, and _mbsrchr.
See Also