|
|
| BOOL RshSearch(
|
|
|
HCLIENT
hClient, |
|
|
|
|
LPCTSTR
lpszString, |
|
|
|
|
LPVOID
lpvBuffer, |
|
|
|
|
LPDWORD
lpdwLength, |
|
|
|
|
DWORD
dwReserved |
|
|
| );
|
The RshSearch 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
RshGetLastError.
Remarks
The RshSearch 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 executing a command and processing the output. 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.
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 csrshav6.lib.
Unicode: Implemented as Unicode and ANSI versions.
See Also
RshExecute, RshIsBlocking, RshIsReadable, RshLogin, RshRead
|
|