BOOL TelnetSearch(
	HCLIENT hClient,
	LPCTSTR lpszString,
	LPVOID lpvBuffer,
	LPDWORD lpdwLength,
	DWORD dwReserved
);

The TelnetSearch function searches for a specific character sequence in the data stream and stops reading if the sequence is encountered.

Parameters

hClient

Handle to the client session.

lpszString

A pointer to a null-terminated string which specifies the sequence of characters to search for in the data stream. This parameter cannot be NULL or point to an empty string.

lpvBuffer

A pointer to a byte buffer which will contain the output from the remote server, or a pointer to a global memory handle which will reference the output when the function returns. If the output from the server is not required, this parameter may be NULL.

lpdwLength

A pointer to an unsigned long integer which should be initialized to the maximum number of bytes that can be copied to the buffer specified by the lpvBuffer parameter. If the lpvBuffer parameter points to a global memory handle, the length value should be initialized to zero. When the function returns, this value will be updated with the actual number of bytes of output stored in the buffer. If the lpvBuffer parameter is NULL, this parameter should also be NULL.

dwReserved

A reserved parameter. This value must be zero.

Return Value

If the function succeeds and the character sequences was found in the data stream, the return value is non-zero. If the function fails or a timeout occurs before the sequence is found, the return value is zero. To get extended error information, call TelnetGetLastError.

Remarks

The TelnetSearch function searches for a character sequence in the data stream and stops reading when it is found. This is useful when the client wants to automate responses to the server, such as logging in a user and executing a command. The function collects the output from the server and stores it in the buffer specified by the lpvBuffer parameter. When the function returns, the buffer will contain everything sent by the server up to and including the search string.

The lpvBuffer parameter may be specified in one of two ways, depending on the needs of the application. The first method is to pre-allocate a buffer large enough to store the a fixed amount of output. In this case, the lpvBuffer parameter will point to the buffer that was allocated, the value that the lpdwLength parameter points to should be initialized to the size of that buffer. If the server sends more output than can be stored in the buffer, the remaining output will be discarded.

The second method that can be used is have the lpvBuffer parameter point to a global memory handle which will contain the output when the function returns. In this case, the value that the lpdwLength parameter points to must be initialized to zero. It is important to note that the memory handle returned by the function must be freed by the application, otherwise a memory leak will occur. This method is preferred if the client application does not have a general idea of how much output will be generated until the search string is found.

Example

LPCTSTR lpszUserName = "abc123\r\n";
LPCTSTR lpszPassword = "secret\r\n";
LPCTSTR lpszCommand = "/bin/ls -l\r\n";
HGLOBAL hgblOutput = NULL;
DWORD cbOutput = 0;
BOOL bResult;

// Search for the login prompt issued by the server

bResult = TelnetSearch(hClient,
                       _T("ogin: "),
                       NULL,
                       NULL,
                       0);

// If the Login: prompt was found, then write out the
// username and search for the Password: prompt; note
// that the username, password and command strings are
// terminated with a carriage-return/linefeed sequence
// which the server will see as the user pressing the
// Enter or Return key on the keyboard

if (bResult)
{
    TelnetWrite(hClient,
                (LPBYTE)lpszUserName,
                lstrlen(lpszUserName));

    bResult = TelnetSearch(hClient,
                           _T("word: "),
                           NULL,
                           NULL,
                           0);
}

// If the Password: prompt was found, write out the
// password and then search for the shell prompt;
// the prompt may be different, depending on what
// operating system and shell is being used

if (bResult)
{
    TelnetWrite(hClient,
                (LPBYTE)lpszPassword,
                lstrlen(lpszPassword));

    bResult = TelnetSearch(hClient,
                           _T("$ "),
                           NULL,
                           NULL,
                           0);
}

// If the shell prompt was found, issue the command
// and capture the output into the hgblBuffer global
// memory buffer; the cbBuffer variable will contain
// the actual number of bytes in the buffer when the
// function returns

if (bResult)
{
    TelnetWrite(hClient,
                (LPBYTE)lpszCommand,
                lstrlen(lpszCommand));

    bResult = TelnetSearch(hClient,
                           _T("$ "),
                           &hgblOutput,
                           &cbOutput,
                           0);
}

// Write the contents of the output buffer to the
// standard output stream

if (bResult)
{
    LPBYTE lpBuffer = (LPBYTE)GlobalLock(hgblBuffer);
    
    if (lpBuffer)
        fwrite(lpBuffer, 1, cbBuffer, stdout);

    GlobalUnlock(hgblBuffer);
    GlobalFree(hgblBuffer);
}

Requirements

Client: Requires Windows Vista, Windows XP or Windows 2000 Professional.
Server: Requires Windows Server 2008, Windows Server 2003 or Windows 2000 Server.
Header: Include cstools6.h.
Library: Use cstntav6.lib.
Unicode: Implemented as Unicode and ANSI versions.

See Also

TelnetIsBlocking, TelnetIsReadable, TelnetLogin, TelnetRead

Copyright © 2008 Catalyst Development Corporation. All rights reserved.