| |
| BOOL WINAPI 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 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 buffer which will contain the output from
the 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 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
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: cstntv11.lib
Unicode: Implemented as Unicode and ANSI versions
See Also
TelnetIsBlocking,
TelnetIsReadable,
TelnetLogin,
TelnetRead
|
|