BOOL Search(
	LPCTSTR lpszString
);

BOOL Search(
	LPCTSTR lpszString,
	LPBYTE lpBuffer,
	LPDWORD lpdwLength
);

BOOL Search(
	LPCTSTR lpszString,
	HGLOBAL *lpBuffer,
	LPDWORD lpdwLength
);

BOOL Search(
	LPCTSTR lpszString,
	CString& strBuffer
);

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

Parameters

lpszString

A pointer to a 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.

lpBuffer

A pointer to a byte buffer which will contain the output from the server, or a pointer to a global memory handle which will reference the output when the method 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 lpBuffer parameter. If the lpBuffer parameter points to a global memory handle, the length value should be initialized to zero. When the method returns, this value will be updated with the actual number of bytes of output stored in the buffer. If the lpBuffer parameter is NULL, this parameter should also be NULL.

Return Value

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

Remarks

The Search method 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 method collects the output from the server and stores it in the buffer specified by the lpBuffer parameter. When the method returns, the buffer will contain everything sent by the server up to and including the search string.

The lpBuffer 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 lpBuffer 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 lpBuffer parameter point to a global memory handle which will contain the output when the method 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 method 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 lpszCommand = _T("/bin/ls -l\r\n");
LPCTSTR lpszPrompt = _T("$ ");
HGLOBAL hgblOutput = NULL;
DWORD cbOutput = 0;
BOOL bResult;

// Search for a command prompt issued by the server

bResult = pClient->Search(lpszPrompt, 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)
{
    pClient->Write((LPBYTE)lpszCommand, lstrlen(lpszCommand));

    bResult = pClient->Search(lpszPrompt,
                              &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: cstshv11.lib
Unicode: Implemented as Unicode and ANSI versions

See Also

IsBlocking, IsReadable, Peek, Read, ReadLine, Write, WriteLine

Copyright © 2025 Catalyst Development Corporation. All rights reserved.