type TStream = object( TObj )

Simple stream object. Can be opened for file, or as memory stream (see NewReadFileStream, NewWriteFileStream, NewMemoryStream, etc.). And, another type of streaming object can be derived (without inheriting new object type, just by writing another New...Stream method, which calls _NewStream and pass methods record to it).

 

function _NewStream( const StreamMethods: TStreamMethods ): PStream;

Use this method only to define your own stream type. See also declared below (in KOL.pas) methods used to implement standard KOL streams. You can use it in your code to create streams, which are partially based on standard methods.

 

function NewFileStream( const FileName: KOLString; Options: DWORD ): PStream;

Creates file stream for read and write. Exact set of open attributes should be passed through Options parameter (see FileCreate where those flags are listed).

 

function NewFileStreamWithEvent( const FileName: KOLString; Options: DWORD ): PStream;

Creates file stream for read and write. Exact set of open attributes should be passed through Options parameter (see FileCreate where those flags are listed). Also, resulting stream is supporting OnChangePos event.

 

function NewReadFileStream( const FileName: KOLString ): PStream;

Creates file stream for read only.

 

function NewReadFileStreamWithEvent( const FileName: KOLString ): PStream;

Creates file stream for read only, supporting OnChangePos event.

 

function NewWriteFileStream( const FileName: KOLString ): PStream;

Creates file stream for write only. Truncating of file (if needed) is provided automatically.

 

function NewWriteFileStreamWithEvent( const FileName: KOLString ): PStream;

Creates file stream for write only. Truncating of file (if needed) is provided automatically. Created stream supports OnChangePos event.

 

function NewReadWriteFileStream( const FileName: KOLString ): PStream;

Creates stream for read and write file. To truncate file, if it is necessary, change Size property.

 

function NewReadFileStreamW( const FileName: KOLWideString ): PStream;

Creates file stream for read only.

 

function NewWriteFileStreamW( const FileName: KOLWideString ): PStream;

Creates file stream for write only. Truncating of file (if needed) is provided automatically.

 

function NewReadWriteFileStreamW( const FileName: KOLWideString ): PStream;

Creates stream for read and write file. To truncate file, if it is necessary, change Size property.

 

function NewExFileStream( F: HFile ): PStream;

Creates read only stream to read from opened file or pipe from the current position. When stream is destroyed, file handle still not closed (your code should do this) and file position is not changed (after the last read operation).

 

function NewMemoryStream: PStream;

Creates memory stream (read and write).

 

function NewMemoryStreamWithEvent: PStream;

Creates memory stream (read and write). Created stream support OnChangePos event.

 

function NewExMemoryStream( ExistingMem: Pointer; Size: DWORD ): PStream;

Creates memory stream on base of existing memory. It is not possible to write out of top bound given by Size (i.e. memory can not be resized, or reallocated. When stream object is destroyed this memory is not freed.

 

function NewMemBlkStream( BlkSize: Integer ): PStream;

Creates memory stream which consists from blocks of given size. Contrary to a memory stream, contents of the blocks stream should not be accessed directly via fMemory but therefore it is possible to access its parts by portions written to blocks still those were written contigously. To do so, get an address of just written portion for further usage via field fJustWrittenBlkAddress. It is guarantee that blocks of memory allocated during write process never are relocated until destruction the stream.

 

function NewMemBlkStream_WriteOnly( BlkSize: Integer ): PStream;

Same as NewMemoryStream

 

function NewConcatStream( Stream1, Stream2: PStream ): PStream;

Creates a stream which is a concatenation of two source stream. After the call, both source streams are belonging to the resulting stream and these will be destroyed together with the resulting stream. (So forget about it). After the call, first stream will not be changed in size via methods of concatenated stream (and it is not recommended to use further Stream1 and Stream2 methods too). But Stream2 can still be increased, if it allows doing so when some data are appended or Size of resulting stream is changed (but not less then Stream1.Size). Nature and physical location of Stream1 and Stream2 are not important and can be absolutely different. But it is supposed that both streams are not compressed and its Size is known always and Seek operation is valid. This function accepts recursive (multi-level) usage: resulting concatenation stream can be used as a left or right parameter to create another concatenation stream later, so it is possible to build a tree of streams concatenated, concatenating this way several different streams and use it as a single data streaming object.

 

function NewSubStream( BaseStream: PStream; const FromPos, Size: TStrmSize ): PStream;

Creates a stream which is a subpart of BaseStream passes, starting from FromPos and with given Size. Like in function NewConcatStream, passes BaseStream become owned by newly created sub-stream object, and will be destroyed automatically together with a sub-stream. If you want to provide more long life time for a base stream (e.g. if you plan to use it after a sub-stream based on it is destroyed), use method RefInc for base stream once to prevent it from destroying when the sub-stream is destroyed. Note: be careful and avoid direct calling methods and properties of the base stream, while you have a sub-stream created on base it, since the sub-stream actually redirects all the requests to the parent base stream. Sub-stream accepts setting Size to greater value later, and if some data are written to it, it is written actually to the base stream, and when it is written beyond the end position, this will increase size of the base stream too (and if it is a file stream, this also will increase size of the file on which the base stream was created). This function accepts recursive (multi-level) usage: it is possible to create later another sub-stream on base of existing sub-stream, still it is actully can be treated as usual stream.

 

function Stream2Stream( Dst, Src: PStream; const Count: TStrmSize ): TStrmSize;

Copies Count (or less, if the rest of Src is not sufficiently long) bytes from Src to Dst, but with optimizing in cases, when Src or/and Dst are memory streams (intermediate buffer is not allocated).

 

function Stream2StreamEx( Dst, Src: PStream; const Count: TStrmSize ): TStrmSize;

Copies Count bytes from Src to Dst, but without any optimization. Unlike Stream2Stream function, it can be applied to very large streams. See also Stream2StreamExBufSz.

 

function Stream2StreamExBufSz( Dst, Src: PStream; const Count: TStrmSize; BufSz: DWORD ): TStrmSize;

Copies Count bytes from Src to Dst using buffer of given size, but without other optimizations. Unlike Stream2Stream function, it can be applied to very large streams

 

function Resource2Stream( DestStrm: PStream; Inst: HInst; ResName: PKOLChar; ResType: PKOLChar ): Integer;

Loads given resource to DestStrm. Useful for non-standard resources to load it into memory (use memory stream for such purpose). Use one of following resource types to pass as ResType:

 

 

For example:

 

var MemStrm: PStream;
   JpgObj: PJpeg;
......
MemStrm := NewMemoryStream;
JpgObj := NewJpeg;
......
Resource2Stream( MemStrm, hInstance, 'MYJPEG', RT_RCDATA );
MemStrm.Position := 0;
JpgObj.LoadFromStream( MemStrm );
MemStrm.Free;
......

 

 

TStream properties

 

property Size: TStrmSize;

Returns stream size. For some custom streams, can be slow operation, or even always return undefined value (-1 recommended).

 

property Position: TStrmSize;

Current position

 

property Memory: Pointer;    

Only for memory stream.

 

property Handle: THandle;    

Only for file stream. It is possible to check that Handle <> INVALID_HANDLE_VALUE to ensure that file stream is created OK.

 

property Methods: PStreamMethods;    

Pointer to TStreamMethods record. Useful to implement custom-defined streams, which can access its fCustom field, or even to change methods when necessary.

 

property Data: TStreamData;    

Pointer to TStreamData record. Useful to implement custom-defined streams, which can access Data fields directly when implemented.

 

property Capacity: TStrmSize;

Amound of memory allocated for data (MemoryStream).

Properties, inherited from TObj

 

TStream methods

 

function Read( var Buffer; const Count: TStrmSize ): TStrmSize;

Reads Count bytes from a stream. Returns number of bytes read.

 

function Seek( const MoveTo: TStrmMove; MoveMethod: TMoveMethod ): TStrmSize;

Allows to change current position or to obtain it. Property Position uses this method both for get and set position.

 

function Write( var Buffer; const Count: TStrmSize ): TStrmSize;

Writes Count bytes from Buffer, starting from current position in a stream. Returns how much bytes are written.

 

function WriteVal( Value: DWORD; Count: DWORD ): DWORD;

Writes maximum 4 bytes of Value to a stream. Allows writing constants easier than via Write.

 

function WriteStr( S: AnsiString ): DWORD;

Writes string to the stream, not including ending #0. Exactly Length( S ) characters are written.

 

function WriteStrZ( S: AnsiString ): DWORD;

Writes string, adding #0. Number of bytes written is returned.

 

function WriteWStrZ( S: KOLWideString ): DWORD;

Writes string, adding #0. Number of bytes written is returned.

 

function ReadStrZ: AnsiString;

Reads string, finished by #0. After reading, current position in the stream is set to the byte, follows #0.

 

function ReadWStrZ: KOLWideString;

Reads string, finished by #0. After reading, current position in the stream is set to the byte, follows #0.

 

function ReadStr: AnsiString;

Reads string, finished by #13, #10 or #13#10 symbols. Terminating symbols #13 and/or #10 are not added to the end of returned string though stream positioned follow it.

 

function ReadStrLen( Len: Integer ): AnsiString;

Reads string of the given length Len.

 

function WriteStrEx( S: AnsiString ): DWord;

Writes string S to stream, also saving its size for future use by ReadStrEx* functions. Returns number of actually written characters.

 

function ReadStrExVar( var S: AnsiString ): DWord;

Reads string from stream and assigns it to S. Returns number of actually read characters. Note: String must be written by using WriteStrEx function. Return value is count of characters READ, not the length of string.

 

function ReadStrEx: AnsiString;

Reads string from stream and returns it.

 

function WriteStrPas( S: AnsiString ): DWORD;

Writes a string in Pascal short string format - 1 byte length, then string itself without trailing #0 char. S parameter length should not exceed 255 chars, rest chars are truncated while writing. Total amount of bytes written is returned.

 

function ReadStrPas: AnsiString;

Reads 1 byte from a stream, then treat it as a length of following string which is read and returned. A purpose of this function is reading strings written using WriteStrPas.

 

procedure SeekAsync( MoveTo: TStrmMove; MoveMethod: TMoveMethod );

Changes current position asynchronously. To wait for finishing the operation, use method Wait.

 

procedure ReadAsync( var Buffer; Count: DWord );

Reads Count bytes from a stream asynchronously. To wait finishing the operation, use method Wait.

 

procedure WriteAsync( var Buffer; Count: DWord );

Writes Count bytes from Buffer, starting from current position in a stream - asynchronously. To wait finishing the operation, use method Wait.

 

function Busy: Boolean;

Returns TRUE until finishing the last asynchronous operation started by calling SeekAsync, ReadAsync, WriteAsync methods.

 

procedure Wait;

Waits for finishing the last asynchronous operation.

 

procedure SaveToFile( const Filename: KOLString; const Start, CountSave: TStrmSize );

Methods, inherited from TObj

 

 

TStream events

 

property OnChangePos: TOnEvent;

To allow using this event, create stream with special constructing function like NewMemoryStreamWithEvent or NewReadFileStreamWithEvent, or replace reading / writing methods to certain supporting OnChangePos event.