CSGetZoneText Function

Description

Gets the text between the ZONE_BEGIN and ZONE_END Consoul vt100 escape sequences for a zone ID in a specific console line.

Syntax

VB/A 32bits

Private Declare Function CSGetZoneText Lib "consoul_010205_32.dll" ( _
  ByVal hWnd As Long, _
  ByVal wLine As Integer, _
  ByVal wZoneID As Integer, _
  ByVal wBufferCharLen As Integer, _
  ByVal lpStringBuffer As Long, _
  ByVal wAsVt100 As Integer _
) As Integer

VB/A 64bits

Private Declare PtrSafe Function CSGetZoneText Lib "consoul_010205_64.dll" ( _
  ByVal hWnd As LongPtr, _
  ByVal wLine As Integer, _
  ByVal wZoneID As Integer, _
  ByVal wBufferCharLen As Integer, _
  ByVal lpStringBuffer As LongPtr, _
  ByVal wAsVt100 As Integer _
) As Integer

Return Value

The return value is the number of characters written in lpStringBuffer (not zero terminated).

Parameters

hWnd

The window handle (HWND) of the Consoul window, as returned by CSCreateLogWindow.

wLine

The number of the line (as returned by CSPushLine) where the specified wZoneID should be.

wZoneID

The zone number for which we want get the text. Consoul will reach for the tag of the first zone it finds on the line with this zone ID; other instances of the zone on the same line cannot be reached by this function.

wBufferCharLen

The size in characters (*Consoul" is unicode, one char is 2 bytes) of the receiving memory buffer.

lpStringBuffer

The address of the memory buffer where Consoul will write the extracted text string, up to wBufferCharLen characters. No terminating zero is written in the buffer.

wAsVt100

If 0 (zero), only the text parts of the zone contents are extracted, stripping out the Consoul vt100 escape sequences. If 1 (one) then the full contents, including escapes sequences are written in lpStringBuffer.

Remarks

Consoul does not memorize the exact strings that are pushed (CSPushLine) or set (CSSetLine) into the window queue. Consoul parses the content that is pushed into an intermediary script. When functions like CSGetZoneText or CSGetLineText are called, Consoul rebuilds the returned content from its internal scripts, thus there may be subtle differences between the original content that was pushed and the content that is returned by these functions.

The inverse of this function is CSReplaceZone.

Last updated: May 13 2022.