| INT WINAPI LlmGetUserAgent( |
| |
HCLIENT hClient, |
|
| |
LPTSTR lpszUserAgent, |
|
| |
INT nMaxLength |
|
| ); |
The LlmGetUserAgent function returns the current user-agent
string used by the client.
Parameters
- hClient
- A handle to the client session.
- lpszUserAgent
- A pointer to a string buffer which receives the user-agent
string for the current session. If this parameter is NULL, the
function returns the length of the user-agent string without
copying any characters. If a buffer is provided, it must be large
enough to contain the entire string, including the terminating
null character, or the function will fail.
- nMaxLength
- An integer value which specifies the maximum number of
characters that can be copied into the string buffer, including the
terminating null character. If the lpszUserAgent parameter
is NULL, this value should be zero.
Return Value
If the function succeeds, the return value is the number of
characters copied into the string buffer, not including the
terminating null character. If the function fails, the return
value is zero. To get extended error information, call
LlmGetLastError.
Remarks
The LlmGetUserAgent function retrieves the user-agent string
currently configured for the client session. This value is included
in HTTP requests sent to the provider unless disabled using the
LLM_OPTION_NOUSERAGENT option.
If no user-agent string has been explicitly set using
LlmSetUserAgent, the function may return a default value
defined by the library, or no value depending on the current
configuration.
To determine the required buffer size, call this function with
lpszUserAgent set to NULL. The return value specifies the
number of characters in the string, excluding the terminating
null character. If there is no user-agent string defined for the session, the
function returns zero and the last error value is cleared
(set to NO_ERROR). This condition should not be treated as a failure.
In most cases, the user-agent string will be relatively small. A buffer
of 256 characters is typically sufficient for standard user-agent values.
If a custom user-agent string is used, a larger buffer (such as 512
characters) may be more appropriate. Applications that require complete
flexibility should query the required length and allocate the buffer
dynamically.
The user-agent string is typically used by providers for logging
or request identification. Developers should avoid including
sensitive information in this value.
Example
INT cchUserAgent = 0;
// Query required buffer size
cchUserAgent = LlmGetUserAgent(hClient, NULL, 0);
if (cchUserAgent > 0)
{
LPTSTR lpszUserAgent = (LPTSTR)malloc((cchUserAgent + 1) * sizeof(TCHAR));
if (lpszUserAgent != NULL)
{
if (LlmGetUserAgent(hClient, lpszUserAgent, cchUserAgent + 1))
{
_tprintf(_T("User-Agent: %s\n"), lpszUserAgent);
}
else
{
DWORD dwError = LlmGetLastError();
_tprintf(_T("Error retrieving user-agent (0x%08lX)\n"), dwError);
}
free(lpszUserAgent);
}
}
Requirements
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools12.h
Import Library: csllmv12.lib
Unicode: Implemented as Unicode and ANSI versions
See Also
LlmGetClientOptions,
LlmGetLastError,
LlmSetClientOptions,
LlmSetUserAgent
|