Developer

API Reference

IGETLINE_GetLine()

Brew Release
Brew MP 1.0.2
See Also
IGetLine IGETLINE_UngetLine(), GetLine
Description
This function gets the next logical line of text from the data source. A logical line is a sequence of bytes terminated by a line terminator character sequence (EOL). The currently supported line terminators are CR and CRLF. This function also returns lines that are improperly terminated, and partial lines when the logical line length exceeds the available buffer size. Return codes indicate the reason for return, so the exact binary form of the input stream can be reconstructed, if necessary.
IGETLINE_GetLine() is a synchronous call. It returns what information is available at present. If it needs to buffer more data before it can determine where the next line ends, it will return IGETLINE_WAIT, and the caller will have to try again later. After receiving a return code of IGETLINE_WAIT, the caller can use the IGETLINE_Peekable() member function to be notified of when IGETLINE_GetLine() should be tried again. In all other cases, IGETLINE_GetLine() should be called without waiting on IGETLINE_Peekable() so that it can examine any buffered data and determine whether the caller should wait on IGETLINE_Peekable().
Parameters
  • pIGetLine
    []:
    Pointer to the IGetLine Interface object.
  • pline
    []:
    Pointer to structure to hold results. On
Interface
IGETLINE
Prototype
   int32 IGETLINE_GetLine(IGetLine *  pIGetLine, GetLine *   pline,
                          int32       nTypeEOL);
Return
One of the following exit codes, describing the reason GetLine returned:
  • IGETLINE_WAIT, if the line is not yet complete; try again. In this case,
  • pline describes the available data (the incomplete line), but the data is
  • not processed. Callers should use IGETLINE_Peekable() to be schedule the
  • next call to IGETLINE_GetLine(). In all other cases, the data described
  • in pline is consumed, and IGETLINE_Peekable() should not be used.
  • IGETLINE_Readable() or ISHELL_Resume() can be used instead.

  • IGETLINE_CRLF, the line was terminated at a two-character EOL (CRLF).

  • IGETLINE_CR, the line was terminated at a single-character EOL (CR) [not implemented].

  • IGETLINE_LF, the line was terminated at a single-character EOL (LF).

  • IGETLINE_END, the line ended at end of stream; no EOL seen.

  • IGETLINE_ERROR, the line ended at ERROR; no EOL seen.

  • IGETLINE_FULL, the data was limited by buffer size; no EOL seen; remainder to follow.
Side Effect
None
Comment
In the case of IGETLINE_WAIT, the contents (if any) of the incomplete line are not processed. This means that subsequent calls to IGETLINE_Read(), IGETLINE_Peek(), or IGETLINE_GetLine() will return that data.
In all other cases, the data is consumed. This means that IGETLINE_GetLine() advances the read pointer past the contents of the line, including the line ending, so that subsequent IGETLINE_Read(), IGETLINE_Peek(), or IGETLINE_GetLine() calls will return data that follows the line.
IGETLINE_END or IGETLINE_ERROR are the only two cases that indicate that there will be no more data. IGETLINE_Exhausted() can be handy for this.
IGETLINE_UngetLine() is provided to restore the stream to the exact binary state it was in before the line was consumed. This is mainly provided for HTTP 0.9 compatibility. IGETLINE_UngetLine() should be passed the same length value returned by the previous IGETLINE_GetLine() call, and no other member functions should have been call in the interim, otherwise the results are undetermined.
IGETLINE_LineComplete(code) can be used to test for normal cases where a a line is terminated by a valid EOL sequence or by the end of the stream. Returns TRUE for {IGETLINE_END, IGETLINE_CR, IGETLINE_LF, IGETLINE_CRLF}
In the IGETLINE_WAIT case, IGETLINE_Readable() does not provide appropriate notifications of when to retry IGETLINE_GetLine(). IGETLINE_Readable() indicates readiness for IGETLINE_Read(), and therefore notifies of unbuffered *or* buffered data. Whereas IGETLINE_Read() will succeed whenever there is buffered data, GetLine() in this case will not -- it has already examined the buffered data and determined there is not
enough to complete a line. Calling IGETLINE_Readable() after an IGETLINE_WAIT result can result in repeated callbacks that make no progress, preventing the application from properly yielding time to other applications. IGETLINE_Peekable(), which notifies of new unbuffered data, will properly yield time until IGETLINE_GetLine() needs to be called again.
Before the initial call to IGETLINE_GetLine() or after result codes other than IGETLINE_WAIT, either IGETLINE_Readable() or ISHELL_Resume() can be used to schedule the call to IGETLINE_GetLine(). Either of those functions will allow IGETLINE_GetLine() to examine any buffered data before waiting.
  • Follow