LlmGetMessage

LlmGetMessage Function

BOOL WINAPI LlmGetMessage(

HCLIENT hClient,

LONG nMessageIndex,

LPLLM_MESSAGE lpMessage,

LPLLM_RESPONSE lpResponse

);

The LlmGetMessage function retrieves a message turn in the client history using an index value.

Parameters

hClient

A handle to the client session.

nMessageIndex

An integer value which identifies the message using a zero-based index value. This value cannot be less than zero or greater than the number of messages in the conversation history.

lpMessage

A pointer to an LLM_MESSAGE structure that receives information about the client request. This parameter may be NULL, in which case no message information is returned.

lpResponse

A pointer to an LLM_RESPONSE structure that receives information about the server response. This parameter may be NULL, in which case no response information is returned.

Return Value

If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. To get extended error information, call LlmGetLastError.

Remarks

The LlmGetMessage function retrieves a message and its corresponding response from the client history using a zero-based index value. The index value of zero refers to the oldest message currently stored in the history.

The message history is managed as a first-in, first-out (FIFO) queue. When the number of messages exceeds the configured history size, older messages are automatically removed. As a result, the index value for a given message may change over time. Applications that need to reliably reference a specific message should use the LlmGetMessageById function instead.

If message history has been disabled, the library does not retain previous messages. However, the most recent message and response are still available and may be retrieved using an index value of zero. This also means the data returned in the LLM_MESSAGE and LLM_RESPONSE structures will only remain valid until the next call to LlmSendMessage, LlmSendMessageEx, or until the session is reset or disconnected. Applications that need to preserve this information should make a copy of the data before issuing another request.

If the nMessageIndex parameter is less than zero or greater than or equal to the number of messages currently stored in the history, the function will fail and set the error code to ST_ERROR_INVALID_PARAMETER.

If the lpMessage and/or lpResponse parameters are specified, their respective structures must be initialized with the dwSize member set to the size of the structure before calling this function. This enables the library to validate the structure version and maintain compatibility with future releases.

Either the lpMessage or lpResponse parameter may be NULL if only one type of information is required. At least one of these parameters must be specified. If both parameters are NULL, the function fails and sets the error code to ST_ERROR_INVALID_PARAMETER.

Example

LLM_MESSAGE clientMessage = { sizeof(LLM_MESSAGE) };
LLM_RESPONSE serverResponse = { sizeof(LLM_RESPONSE) };
LONG nMessageIndex = 0;

// If conversation history is enabled, retrieve the most recent message.
// If history is disabled, an index of 0 refers to the most recent
// message and response from the previous request.

LONG nCount = LlmGetMessageCount(hClient);

if (LlmGetHistorySize(hClient) > 0 && nCount > 0)
    nMessageIndex = nCount - 1;

if (LlmGetMessage(hClient, nMessageIndex, &clientMessage, &serverResponse))
{
    _tprintf(_T("\nMessage %u\n"), clientMessage.dwMessageId);
    _tprintf(_T("  Input Tokens:    %u\n"), clientMessage.nInputTokens);
    _tprintf(_T("  Content Length:  %u\n"), clientMessage.nContentLength);
    _tprintf(_T("  Content:         \"%s\"\n"), clientMessage.lpszContent);

    _tprintf(_T("\nResponse %u\n"), serverResponse.dwMessageId);
    _tprintf(_T("  Elapsed:         %u ms\n"), serverResponse.dwElapsed);
    _tprintf(_T("  Output Tokens:   %u\n"), serverResponse.nOutputTokens);
    _tprintf(_T("  Content Length:  %u\n"), serverResponse.nContentLength);
    _tprintf(_T("  Content:         \"%s\"\n"), serverResponse.lpszContent);
    _tprintf(_T("  Response ID:     %s\n"), (serverResponse.lpszResponseId ? serverResponse.lpszResponseId : _T("None")));
    _tprintf(_T("  Model Name:      %s\n"), (serverResponse.lpszModelName ? serverResponse.lpszModelName : _T("None")));
    _tprintf(_T("  Status Text:     %s\n"), (serverResponse.lpszStatusText ? serverResponse.lpszStatusText : _T("None")));
}
else
{
    DWORD dwError = LlmGetLastError();
    _tprintf(_T("Unable to retrieve message at index %ld (error 0x%08lX)\n"), nMessageIndex, dwError);
}

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

Parameters

Return Value

Remarks

Example

Requirements

See Also