Indy 9 | Content | Index | Reference

TIdStream
Hierarchy, Methods, See Also, Unit: IdStream
Implements additional functionality for TStream-based input/output operations.

    TIdStream = class(TStream)

Unit
IdStream
Description
TIdStream is a TStream descendant that implements additional functionality for input/output operations. TIdStream is often used to cast a TStream instance to TIdStream to allow access to the additional methods for stream-based input and output. Note: TIdStream cannot contain new data members; when TStream is cast to a TIdStream instance, the new data members would not contain valid values.

TIdStream implements ReadLn and WriteLn to provide support for line-oriented input and output. TIdStream also reimplements the Write method to support String-based input parameters and additional error checking before writing input values.

TIdStream.BOF
TIdStream, See Also
Indicates the stream is positioned at it's beginning.

    function BOF: Boolean;

Return Value
Boolean - True when positioned at the beginning of the stream.
Description
BOF is a Boolean function used to indicate when the TIdStream is positioned at the beginning of the stream. BOF contains True when the current stream position is less than or equal to zero (0).

Use EOF to determine when the stream is positioned at it's maximum size. Use Skip or Seek to change the curent stream position.

TIdStream.EOF
TIdStream, See Also
Indicates the stream is positioned at it's end.

    function EOF: Boolean;

Return Value
Boolean - True when positioned at the end of the stream.
Description
EOF is a Boolean function used to indicate when the TIdStream is positioned at the end of the stream. EOF contains True when the current stream position is greater than or equal to the current size of the stream.

Use BOF to determine when the stream is positioned at it's beginning. Use Skip or Seek to change the curent stream position.

TIdStream.FindEOL
TIdStream, See Also
Locates the end of a text line in the stream.

    class function FindEOL(ABuf: PChar; var VLineBufSize: Integer; var VCrEncountered: Boolean): Integer;

Parameters
ABuf: PChar
Buffer to be searched for a line of text.
var VLineBufSize: Integer
Size of the buffer or line to be extracted from the buffer.
var VCrEncountered: Boolean
CR or LF dound in the buffer.
Return Value
Integer - Number of bytes to the end of the line or the end of the buffer.
Description
FindEOL is an Integer class function used to locate the end of a text line in the buffer indicated by ABuf. VLineBufSize is a variable parameter that contains the size of ABuf on entry, and will be updated to reflect the character following the CR or LF characters when they are encounterd in ABuf. VCrEncountered is a variable parameter that indicates if the CR of LF characters were encountered in ABuf.

FindEOL is used in ReadLn to locate the end of a text line in the TIdStream.

TIdStream.ReadInteger
TIdStream, See Also
Reads a 16-bit integer value from the current stream position.

    function ReadInteger(const AConvert: Boolean = TRUE): Integer;

Parameters
const AConvert: Boolean = TRUE
Indicates that integer valyues must be converted from it's network byte ordering.
Description
ReadInteger is an Integer function used to read a 16-bit integer value from the current stream position. ReadInteger calls ReadBuffer to acquire the return value. When AConvert is True, the value is converted from network (or Internet) byte order to it's host-dependent representation using TIdStack.WSNToHL.

TIdStream.ReadLn
TIdStream, See Also
Reads a line of text from the current stream position.

    function ReadLn(AMaxLineLength: Integer = -1; AExceptionIfEOF: Boolean = FALSE): String;

Parameters
AMaxLineLength: Integer = -1
Maximum line length to read from the stream. Default value is -1.
AExceptionIfEOF: Boolean = FALSE
Raise an exception if EOF is reached. Default value is FALSE.
Description
ReadLn is a String function used to read a single line of text from the current stream position. For TIdTCPStream and descendant classes, the Connection is used to perform the ReadLn operation.

ReadLn will acquire a string value from the stream until EOL characters are encountered, or until the number of characters in AMaxLineLength is read from the stream. When AMaxLineLength is -1, the value in MaxInt is used as the maximum line length.

ReadLn calls ReadBuffer using a 2,048 byte buffer (or smaller when the stream size permits) to read text values from the stream. ReadLn can raise a EIdEndOfStream exception if an unexpected end of stream is encountered while reading values from the stream.

TIdStream.ReadString
TIdStream, See Also
Reads a Pascal-style string from the current stream position.

    function ReadString(const AConvert: Boolean = TRUE): String;

Parameters
const AConvert: Boolean = TRUE
Indicates the string length must be converted from network byte order.
Description
ReadString is a String function used to read a Pascal-style string from the current stream position. ReadString calls ReadInteger to determine the length of string in the stream. When Aconvert is True, the string length will be converted from it's network (or Internet) byte order to a host-dependent representation of the integer value. When the string length is greater than zero (0), ReadString calls ReadBuffer to acquire the return value for the method. Otherwise the return value is an empty string ('').

TIdStream.Skip
TIdStream, See Also
Moves the current stream position by the specified number of bytes.

    procedure Skip(ASize: Integer);

Parameters
ASize: Integer
Number of bytes to move the current stream position.
Description
Skip is a convenience procedure used to move the current stream position by the number of bytes specified in ASize. Skip calls the Seek method using ASize to move the stream from the current stream position. ASize can contain a position, negative, or zero (0) value.

Use BOF and EOF to determine when the beginning or end of the stream has been reached after a call to Skip.

TIdStream.This
TIdStream
References the object instance calling the method.

    function This: TIdStream;

Description
This is a TIdStream function used to gain convenient access to the current object instance. The return value for This is the Self identifier that references the object instance in which the method is called.

TIdStream.Write
TIdStream, See Also
Writes the contents of a string to the stream.

    procedure Write(const AData: string); overload; reintroduce;

Parameters
const AData: string
String values to be written to the stream.
Description
Write is an overloaded procedure reintroduced in TIdStream that allows the string value in AData to be written to the stream. When AData contains a string with a non-zero length, Write calls the WriteBuffer method to transfer a specified number of bytes in AData. When AData contains an emptry string (''), no action is performed.

Use WriteLn to write a String value followed by an EOL character sequence.

Use WriteString to write a Delphi-style String value prepended with the length of the character data.

TIdStream.WriteInteger
TIdStream, See Also
Write a 16-bit Integer value to the stream.

    procedure WriteInteger(AValue: Integer; const AConvert: Boolean = True);

Parameters
AValue: Integer
16-bit value to write to the stream.
const AConvert: Boolean = True
Indicates bytes are converted to Network byte order.
Description
WriteInteger is a procedure used to write the 16-bit integer value specified in AValue to the stream. When AConvert is True, the bytes in AVAlue will be converted from their host-dependent byte order to Network (or Internet) byte order using TIdStack.WSHToNL.

WriteInteger call WriteBuffer using the content and size of AValue to transfer values to the stream.

Use ReadInteger to read a 16-bit value from the stream.

TIdStream.WriteLn
TIdStream, See Also
Writes a string value and an end-of-line character sequence to the stream.

    procedure WriteLn(const AData: string = ''); overload;
    procedure WriteLn(const AData: string; const AArgs: array of const); overload;

Parameters
const AData: string = ''
String content or format to be written to the stream.
const AArgs: array of const
Array of arguments for the format string.
Description
WriteLn is an overloaded procedure in TIdStream that writes string content to the stream followed by an EOL character sequence. In the default implementation, WriteLn accepts a single string argument in AData that contains the contents to be written to the stream. The default value for AData is an empty string (''), when omitted.

In an overloaded variant of WriteLn, AData contains a format string and AArgs contains an open array of arguments to be used in a call to the Format function. The return value from Format is written using the default WriteLn implementation.

In both cases, the sLineBreak character sequence is written after the string content.

TIdStream.WriteLn
TIdStream, See Also
Writes a string value and an end-of-line character sequence to the stream.

    procedure WriteLn(const AData: string = ''); overload;
    procedure WriteLn(const AData: string; const AArgs: array of const); overload;

Parameters
const AData: string = ''
String content or format to be written to the stream.
const AArgs: array of const
Array of arguments for the format string.
Description
WriteLn is an overloaded procedure in TIdStream that writes string content to the stream followed by an EOL character sequence. In the default implementation, WriteLn accepts a single string argument in AData that contains the contents to be written to the stream. The default value for AData is an empty string (''), when omitted.

In an overloaded variant of WriteLn, AData contains a format string and AArgs contains an open array of arguments to be used in a call to the Format function. The return value from Format is written using the default WriteLn implementation.

In both cases, the sLineBreak character sequence is written after the string content.

TIdStream.WriteString
TIdStream, See Also
Writes a Delphi-style string to the stream.

    procedure WriteString(const AStr: String; const AConvert: Boolean = True);

Parameters
const AStr: String
String to be written to the stream.
const AConvert: Boolean = True
Converts the length byte order to Network byte order.
Description
WriteString is a procedure used to write a Delphi-style string containing a binary representation of the string length followed by string content to the stream.

AStr is the string to be written to the stream. AConvert indicates that the string length should be converted from it's host-dependent representation to Network (or Internet) byte order.

WriteString calls WriteInteger to output the length of the string content to follow, using AConvert to specifiy the byte ordering required. When the length of AStr is non-zero, WriteString calls WriteBuffer to output the string content of AStr for the specified number of bytes.

Use Write to output string content without the binary length to the stream. Use WriteLn to output string content and an EOL character sequence without the binary length to the stream.

Created with Doc-O-Matic 2 donated to Project JEDI. Commercial license available from the Doc-O-Matic site.