The LlmFindMessage function searches the message history
for text that matches a specific pattern. The search can be limited
to prompts, responses, or both, depending on the options specified
by the dwOptions parameter. The pattern you are matching
against must be a null-terminated string and it cannot consist of only
whitespace characters (spaces, tabs, carriage returns and linefeeds).
If the dwStartMessageId parameter is non-zero, the function will
begin searching with the first message whose identifier is equal to or
greater than the specified value. Message identifiers are unique within
a client session and are assigned incrementally, so newer messages will
always have higher identifier values than older messages.
If the lpszPattern parameter does not contain any
regular expression constructs (such as ^, $,
[ ], or quantifiers like * and +),
the search is performed using a simple substring comparison. Regular
expression matching is automatically enabled when the pattern contains
recognized regular expression constructs, unless the
LLM_SEARCH_LITERAL_MATCH option is specified.
If a regular expression pattern is specified, the function compiles the
pattern and searches the message content for a match. The regular
expression matching uses a simplified version which only supports
anchors, wildcards, match classes (enclosed in brackets) and a
limited number of escape sequences such as \d to match
any digit or \s to match any space character. It does
not support grouping or replacement.
Supported regular expression constructs include:
- The caret
^ and dollar symbol $
for the beginning and end of the content.
- The period
. to match any character.
- Character classes such as
[abc] which would
match any of the characters enclosed in brackets.
- Negated classes such as
[^abc] which would
match if none of those characters are found.
- Escaped matches such as
\d for digits,
\w for word characters and \s for
whitespace characters
- The
+ quantifier can be used to match one
or more occurrences.
- The
* quantifier will match zero or more
occurrences.
This function uses a minimal regular expression parser and does not
include support for complex constructs such as grouping, backreferences
or alternation using the pipe | character. If you want to
search for text which may contain characters typically used in regular
expressions such as [ or $, you can either
escape them using a backslash, or you can use the LLM_SEARCH_LITERAL_MATCH
option which forces the function to only perform a substring search.
Applications searching for arbitrary user-entered text should
usually specify the LLM_SEARCH_LITERAL_MATCH option to avoid
unintended interpretation of regular expression characters. This will
avoid situations where a user may unexpectedly enter search text which
appears to be a regular expression pattern.
Regular expression matches are performed against the entire prompt
or response text and are not implicitly anchored. It is also important
to keep in mind that matches can span multiple lines (they do not end
at line breaks) and will attempt to match as much text as possible
(this is sometimes referred to as a "greedy match"). This can
yield unexpected results if you use wildcards in the pattern which
are overly broad, matching large sections of the prompt or response text.
For example, a pattern like ".*abc" will match everything
until the last instance of "abc" is found.
If you are calling this function in C, C++ or another C-like
language and want to use a backslash in your regular expression,
remember you will need to escape the backslash (in other words, use
double backslashes). For example, if you wanted to use the regular
expression \d+\s+ in your pattern, the C string literal
would look like "\\d+\\s+", otherwise the
compiler will probably warn you about unrecognized escape sequences.
If neither the LLM_SEARCH_PROMPT nor LLM_SEARCH_RESPONSE options
are explicitly specified, the search will match against both message
prompts and responses.
The LlmGetMessageById function can be used to obtain the
complete contents of the prompt and/or response for a matching
message.
LPCTSTR lpszPattern = _T("exception.*handler");
DWORD dwOptions = LLM_SEARCH_DEFAULT;
DWORD dwMessageId = 0;
// Find the first message that contains the specified text
dwMessageId = LlmFindMessage(hClient, lpszPattern, dwMessageId, dwOptions))
if (dwMessageId != 0)
{
_tprintf(_T("Found match in message ID %lu\n"), dwMessageId);
// Continue searching for additional matches
do
{
dwMessageId = LlmFindMessage(hClient, lpszPattern, dwMessageId + 1, dwOptions);
if (dwMessageId != 0)
_tprintf(_T("Found another match in message ID %lu\n"), dwMessageId);
}
while (dwMessageId != 0);
}
else
{
_tprintf(_T("No matching messages were found.\n"));
}