Stream#

Qualified name: delphivcl.Stream

class Stream#

Bases: Object

TStream is the base class type for stream objects that can read from or write to various kinds of storage media, such as disk files, dynamic memory, and so on. Use specialized stream objects to read from, write to, or copy information stored in a particular medium. Each descendant of TStream implements methods for transferring information to and from a particular storage medium, such as a disk file, dynamic memory, and so on. In addition to methods for reading, writing, and copying bytes to and from the stream, stream objects permit applications to seek to an arbitrary position in the stream. Properties of TStream provide information about the stream, such as its size and the current position in the stream. TStream also introduces methods that work in conjunction with components and filers for loading and saving components in simple and inherited forms. These methods are called automatically by global routines that initiate component streaming. They can also be called directly to initiate the streaming process. Note, however, that component streaming always involves two additional objects:

A component object that is passed as a parameter to the stream’s methods. A filer object that is automatically created by the stream, and associated with the stream. Descendant stream objects, such as memory and file streams used for component streaming, are created automatically by the global functions ReadComponentRes and WriteComponentRes. For streaming other kinds of information, choose a descendent class according to the specific data and storage needs. These include:

TFileStream – for working with files. TStringStream – for manipulating in-memory strings. TMemoryStream – for working with a memory buffer. TWinSocketStream – for reading and writing over a socket connection. TOleStream – for using a COM interface to read and write.

Methods

`CopyFrom`	Copies a specified number of bytes from one stream to another.
`FixupResourceHeader`	Patches the resource header for a resource that has been written to the stream.
`Free`	Frees the Wrapped Delphi Object
`InheritsFrom`	Returns True if Delphi Object is or inherits from ClassName
`Read`	Methods responsible for reading up to Count bytes of data from the stream into Buffer.
`Read64`	Embarcadero Technologies does not currently have any additional information.
`ReadBuffer`	Reads Count bytes from the stream into Buffer.
`ReadBufferData`	Methods responsible for reading fixed Count or SizeOf(Buffer) number of bytes from the stream into Buffer.
`ReadBytes`	Read content as bytes.
`ReadComponent`	Initiates streaming of components and their properties.
`ReadComponentRes`	Reads components and their properties from a stream in a resource file format.
`ReadData`	Methods responsible for reading up to Count but not more than SizeOf(Buffer) bytes from the stream into Buffer.
`ReadFloat`	Read content as float.
`ReadInt`	Read content as integer.
`ReadResHeader`	Reads a resource-file header from the stream.
`ReadString`	Read content as string.
`Seek`	Moves to a specified position in the streamed resource.
`Seek32`	Embarcadero Technologies does not currently have any additional information.
`SetProps`	Sets several properties in one call
`ToList`	If the object is a container (TStrings, TComponent...), it returns the content of the sequence as a Python list object.
`ToTuple`	If the object is a container (TStrings, TComponent...), it returns the content of the sequence as a Python tuple object.
`Write`	Methods responsible for writing up to Count bytes from Buffer to the stream.
`Write64`	Embarcadero Technologies does not currently have any additional information.
`WriteBuffer`	Writes Count bytes from Buffer onto the stream.
`WriteBufferData`	Writes up to 4 four or Count bytes from Buffer onto the stream.
`WriteBytes`	Write content as bytes.
`WriteComponent`	Initiates the writing of components and their properties to a stream.
`WriteComponentRes`	Writes components and their properties to a stream from a resource file format.
`WriteData`	Methods responsible for writing up to Count bytes from Buffer to the stream.
`WriteDescendent`	Streams components and their properties in inherited forms.
`WriteDescendentRes`	Streams components and their properties in inherited forms.
`WriteFloat`	Write content as float.
`WriteInt`	Write content as integer.
`WriteResourceHeader`	Writes a resource-file header to the stream.
`WriteString`	Write content as string.

Attributes

`ClassName`	Returns the TObject.ClassName
`Position`	Indicates the current offset into the stream for reading and writing.
`Size`	Indicates the size in bytes of the stream.

ClassName#: Returns the TObject.ClassName

CopyFrom(Source: Stream, Count: Int64, BufferSize: Integer) → Int64#: Copies a specified number of bytes from one stream to another. Use CopyFrom to copy data from one stream to a different one. Using CopyFrom eliminates the need to create, read into, write from, and free a buffer when copying data. CopyFrom copies Count bytes from the stream specified by Source into the stream. It then moves the current position by Count bytes and returns the number of bytes copied. If Count is 0, CopyFrom sets Source position to 0 before reading and then copies the entire contents of Source into the stream. If Count is greater than or less than 0, CopyFrom reads from the current position in Source. Because the CopyFrom method uses ReadBuffer and WriteBuffer to do the effective copying, if the Count is greater than the SourceStream size, ReadBuffer throws an exception stating that a stream read error has occured.

FixupResourceHeader(FixupInfo: Integer)#: Patches the resource header for a resource that has been written to the stream. Do not call FixupResourceHeader? it is used internally. The WriteDescendentRes method calls FixupResourceHeader after writing a component to the stream. This method then uses the current position to determine the size of the resource just written and adjust the resource header accordingly. The FixupInfo parameter is the value returned by WriteResourceHeader when it writes the resource header (before WriteDescendentRes streams out the component.)

Free()#: Frees the Wrapped Delphi Object

InheritsFrom(ClassName)#: Returns True if Delphi Object is or inherits from ClassName

Position#: Indicates the current offset into the stream for reading and writing. Use Position to obtain the current position of the stream. This is the number of bytes from the beginning of the streamed data.

Read(Buffer, Count: Integer) → Integer#: Methods responsible for reading up to Count bytes of data from the stream into Buffer. Descendant stream classes can define its own Read methods that read data from its particular storage medium (such as memory or a disk file) into a Buffer buffer. Read is used in cases where the number of bytes to read from the stream is not necessarily fixed. Read attempts to read, into Buffer, up to Count bytes from the stream, starting at the current position, and then advances the current position in the stream by the number of bytes actually transferred. Read returns the number of bytes actually read, which may be less than Count. Offset specifies a zero-based position in Buffer from which to write the first byte into Buffer. All the other data-reading methods of a stream (ReadBuffer, ReadData) call Read to do their actual reading. Methods responsible for reading up to Count bytes of data from the stream into Buffer. Descendant stream classes can define its own Read methods that read data from its particular storage medium (such as memory or a disk file) into a Buffer buffer. Read is used in cases where the number of bytes to read from the stream is not necessarily fixed. Read attempts to read, into Buffer, up to Count bytes from the stream, starting at the current position, and then advances the current position in the stream by the number of bytes actually transferred. Read returns the number of bytes actually read, which may be less than Count. Offset specifies a zero-based position in Buffer from which to write the first byte into Buffer. All the other data-reading methods of a stream (ReadBuffer, ReadData) call Read to do their actual reading. Methods responsible for reading up to Count bytes of data from the stream into Buffer. Descendant stream classes can define its own Read methods that read data from its particular storage medium (such as memory or a disk file) into a Buffer buffer. Read is used in cases where the number of bytes to read from the stream is not necessarily fixed. Read attempts to read, into Buffer, up to Count bytes from the stream, starting at the current position, and then advances the current position in the stream by the number of bytes actually transferred. Read returns the number of bytes actually read, which may be less than Count. Offset specifies a zero-based position in Buffer from which to write the first byte into Buffer. All the other data-reading methods of a stream (ReadBuffer, ReadData) call Read to do their actual reading.

Read64(Buffer: Array<System.Byte>, Offset: Int64, Count: Int64) → Int64#: Embarcadero Technologies does not currently have any additional information.

ReadBuffer(Buffer, Count: NativeInt)#: Reads Count bytes from the stream into Buffer. Use ReadBuffer to read Count bytes from the stream into a Buffer buffer in cases where the number of bytes to read is known and fixed, for example when reading in structures. ReadBuffer is used internally for loading from a stream and copying from a stream. Read attempts to read exactly Count bytes from the stream, starting at the current position, and then advances the current position in the stream by the number of bytes actually transferred. Offset specifies a zero-based position in Buffer from which to write the first byte into Buffer. ReadBuffer calls Read to do the actual reading. If Count bytes cannot be read from the stream, an EReadError exception is raised. Reads Count bytes from the stream into Buffer. Use ReadBuffer to read Count bytes from the stream into a Buffer buffer in cases where the number of bytes to read is known and fixed, for example when reading in structures. ReadBuffer is used internally for loading from a stream and copying from a stream. Read attempts to read exactly Count bytes from the stream, starting at the current position, and then advances the current position in the stream by the number of bytes actually transferred. Offset specifies a zero-based position in Buffer from which to write the first byte into Buffer. ReadBuffer calls Read to do the actual reading. If Count bytes cannot be read from the stream, an EReadError exception is raised. Reads Count bytes from the stream into Buffer. Use ReadBuffer to read Count bytes from the stream into a Buffer buffer in cases where the number of bytes to read is known and fixed, for example when reading in structures. ReadBuffer is used internally for loading from a stream and copying from a stream. Read attempts to read exactly Count bytes from the stream, starting at the current position, and then advances the current position in the stream by the number of bytes actually transferred. Offset specifies a zero-based position in Buffer from which to write the first byte into Buffer. ReadBuffer calls Read to do the actual reading. If Count bytes cannot be read from the stream, an EReadError exception is raised.

ReadBufferData(Buffer: Boolean)#

Methods responsible for reading fixed Count or SizeOf(Buffer) number of bytes from the stream into Buffer. Use ReadBufferData to read exactly the fixed Count or SizeOf(Buffer) number of bytes from the stream into a typed Buffer. ReadBufferData raises an EReadError exception if ReadBufferData cannot read exactly the specified number of bytes. ReadBufferData works using the following algorithms:

When ReadBufferData does not have the Count parameter, then ReadBufferData tries to read the SizeOf(Buffer) number of bytes, then advances the current position in the stream by the number of bytes transferred. If the number of bytes transferred is not = SizeOf(Buffer), then ReadBufferData raises an EReadError exception. When ReadBufferData has the Count parameter, then ReadBufferData calls ReadData to read the Count bytes. If a reported number of transferred bytes is not equal to Count, then ReadBufferData raises an EReadError exception. ReadBufferData calls ReadData to do the actual reading. Methods responsible for reading fixed Count or SizeOf(Buffer) number of bytes from the stream into Buffer. Use ReadBufferData to read exactly the fixed Count or SizeOf(Buffer) number of bytes from the stream into a typed Buffer. ReadBufferData raises an EReadError exception if ReadBufferData cannot read exactly the specified number of bytes. ReadBufferData works using the following algorithms:

ReadBytes()#: Read content as bytes.

ReadComponent(Instance: Component) → Component#: Initiates streaming of components and their properties. ReadComponent is called indirectly by the global routine ReadComponentRes, by the ReadComponentRes method, or it can be called directly to initiate component streaming. ReadComponent reads data values from the stream and assigns them to Instance’s properties. It then constructs a reader object and calls the reader’s ReadRootComponent method to read the Instance’s property values and construct child objects defined in the stream as children of Instance. ReadComponent returns the component. If Instance is nil (Delphi) or NULL (C++), ReadComponent constructs a component based on the type information in the stream and returns the newly-constructed component.

ReadComponentRes(Instance: Component) → Component#: Reads components and their properties from a stream in a resource file format. ReadComponentRes is called automatically by the global routine ReadComponentResFile. It can also be called directly if the current position of the stream points to a component written using the WriteComponentRes method. ReadComponentResFile creates a file stream object, which then calls its ReadComponentRes method. ReadComponentRes first calls the ReadResHeader method to read a resource header from the stream. If the stream does not contain a resource header at the current position, ReadResHeader will raise an EInvalidImage exception. ReadComponentRes then calls ReadComponent to read the properties that must be set on Instance.

ReadData(Buffer: Pointer, Count: NativeInt) → NativeInt#

Methods responsible for reading up to Count but not more than SizeOf(Buffer) bytes from the stream into Buffer. ReadData is used in cases, where the number of bytes to read from the stream is not necessarily fixed. ReadData works using the following algorithms:

When ReadData does not have the Count parameter, then ReadData tries to read the SizeOf(Buffer) number of bytes, then advances the current position in the stream by the number of bytes transferred. ReadData returns the number of bytes read. When ReadData has the Count parameter, then: If Count > SizeOf(Buffer), then ReadData tries to read the SizeOf(Buffer) number of bytes. ReadData advances the current position in the stream by Count number of bytes. ReadData returns Count. If Count <= SizeOf(Buffer), then ReadData tries to read up to the Count number of bytes from the stream. ReadData advances the current position in the stream by the number of bytes transferred. ReadData returns the number of bytes read. ReadData methods call Read to do their actual reading. Methods responsible for reading up to Count but not more than SizeOf(Buffer) bytes from the stream into Buffer. ReadData is used in cases, where the number of bytes to read from the stream is not necessarily fixed. ReadData works using the following algorithms:

ReadFloat()#: Read content as float.

ReadInt()#: Read content as integer.

ReadResHeader()#: Reads a resource-file header from the stream. Do not call ReadResHeader directly. It is called automatically by ReadComponentRes before reading a component from a resource file. After reading the resource-file header, ReadResHeader moves the current position of the stream to just beyond the header. If the stream does not contain a valid resource-file header, ReadResHeader raises an EInvalidImage exception.

ReadString()#: Read content as string.

Seek(Offset: Integer, Origin: Word) → Integer#

Moves to a specified position in the streamed resource. Call Seek to move the current position of the stream in its particular storage medium (such as memory or a disk file). The Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:

Value

Meaning

soBeginning

Offset is from the beginning of the resource. Seek moves to the position Offset. Offset must be >= 0.

soCurrent

Offset is from the current position in the resource. Seek moves to Position + Offset.

soEnd

Offset is from the end of the resource. Offset must be <= 0 to indicate a number of bytes before the end of the file.

Seek returns the new value of the Position property. Seek is called by the Position and Size properties.

Note: As implemented in TStream, the two versions (the 32-bit or 64-bit syntax) call each other. Descendent stream classes must override at least one of these versions, and the override must not call the inherited default implementation. Moves to a specified position in the streamed resource. Call Seek to move the current position of the stream in its particular storage medium (such as memory or a disk file). The Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:

Value

Meaning

soBeginning

Offset is from the beginning of the resource. Seek moves to the position Offset. Offset must be >= 0.

soCurrent

Offset is from the current position in the resource. Seek moves to Position + Offset.

soEnd

Offset is from the end of the resource. Offset must be <= 0 to indicate a number of bytes before the end of the file.

Seek returns the new value of the Position property. Seek is called by the Position and Size properties.

Value

Meaning

soBeginning

Offset is from the beginning of the resource. Seek moves to the position Offset. Offset must be >= 0.

soCurrent

Offset is from the current position in the resource. Seek moves to Position + Offset.

soEnd

Offset is from the end of the resource. Offset must be <= 0 to indicate a number of bytes before the end of the file.

Seek returns the new value of the Position property. Seek is called by the Position and Size properties.

Seek32(Offset: Integer, Origin: SeekOrigin) → Int64#: Embarcadero Technologies does not currently have any additional information.

SetProps(prop1=val1, prop2=val2...)#: Sets several properties in one call

Size#

Indicates the size in bytes of the stream. Use Size to find the size of the stream. Size is used internally in routines that read and write to and from the stream. Setting the Size property of TStream does nothing. However, descendants of TStream can override this property to allow applications to change the size of the resource accessed using the stream. The Size property typically indicates the size of the stream in bytes. But a descendent of TStream can use -1 to indicate an unknown size. When the size is unknown, use the return value from TStream.Read to determine end of the stream.

Example of Stream Size using DataSnap and DBX When you are reading a DataSnap stream in blocks, the actual TStream descendant that is used to read the stream is TDBXStreamReaderStream. TDBXStreamReaderStream overrides methods of TStream such as the method System.Classes.TStream.GetSize, which is the reader for the property Size. DBX connections support reading streams in block. The default block size is 32K. Streams can be passed from the client to the server, or from the server to the client. When the receiver is reading the stream (whether the receiver is the client or the server), the stream is passed from the sender to the receiver in blocks. When the stream is large enough to require multiple block readings, the Size property of the receiver’s stream will be -1, which indicates that the size of the stream is unknown. As the receiver reads the stream, DataSnap makes a request to the sender for the next block, as needed. To read the stream, the client calls the Read() method until the return value is less than the value requested. The following code shows how to read a stream to the end, by checking the return value from Read():

var

LBuffer: TArray<Byte>; LReadCount: Integer;

begin

SetLength(LBuffer, 1024*10); // 10K buffer for this example. The buffer size can be larger or smaller. repeat

LReadCount := AStream.Read(LBuffer[0], Length(LBuffer)); if LReadCount > 0 then begin

// Process buffer

end;

until LReadCount < Length(LBuffer);

ToList()#: If the object is a container (TStrings, TComponent…), it returns the content of the sequence as a Python list object.

ToTuple()#: If the object is a container (TStrings, TComponent…), it returns the content of the sequence as a Python tuple object.

Write(Buffer, Count: Integer) → Integer#: Methods responsible for writing up to Count bytes from Buffer to the stream. Write attempts to write up to Count bytes from the Buffer to the current position in the stream, and returns the number of bytes written. After writing to the stream, Write advances the current position by the number of bytes written. Offset specifies a zero-based position in Buffer of the first byte to write. All other data-writing methods of a stream (WriteBuffer, WriteData) call Write to do their actual writing. Each descendent stream object defines a Write method that writes data to its particular storage medium (such as memory or a disk file). Methods responsible for writing up to Count bytes from Buffer to the stream. Write attempts to write up to Count bytes from the Buffer to the current position in the stream, and returns the number of bytes written. After writing to the stream, Write advances the current position by the number of bytes written. Offset specifies a zero-based position in Buffer of the first byte to write. All other data-writing methods of a stream (WriteBuffer, WriteData) call Write to do their actual writing. Each descendent stream object defines a Write method that writes data to its particular storage medium (such as memory or a disk file). Methods responsible for writing up to Count bytes from Buffer to the stream. Write attempts to write up to Count bytes from the Buffer to the current position in the stream, and returns the number of bytes written. After writing to the stream, Write advances the current position by the number of bytes written. Offset specifies a zero-based position in Buffer of the first byte to write. All other data-writing methods of a stream (WriteBuffer, WriteData) call Write to do their actual writing. Each descendent stream object defines a Write method that writes data to its particular storage medium (such as memory or a disk file).

Write64(Buffer: Array<System.Byte>, Offset: Int64, Count: Int64) → Int64#: Embarcadero Technologies does not currently have any additional information.

WriteBuffer(Buffer, Count: NativeInt)#: Writes Count bytes from Buffer onto the stream. WriteBuffer attempts to write Count bytes from the Buffer to the current position in the stream, then WriteBuffer advances the current position by Count. If the stream fails to write all the requested bytes, an EWriteError exception is raised. Offset specifies a zero-based position in Buffer of the first byte to write. Use WriteBuffer to save data to a stream. WriteBuffer is used in cases, where the number of bytes to write is known and required, for example when writing in structures. Use WriteBuffer for standard file I/O streaming. WriteBuffer is used internally for writing to a stream. It is used by other objects, such as strings and lists, for writing strings stored in a buffer. WriteBuffer calls Write to handle the actual writing. Writes Count bytes from Buffer onto the stream. WriteBuffer attempts to write Count bytes from the Buffer to the current position in the stream, then WriteBuffer advances the current position by Count. If the stream fails to write all the requested bytes, an EWriteError exception is raised. Offset specifies a zero-based position in Buffer of the first byte to write. Use WriteBuffer to save data to a stream. WriteBuffer is used in cases, where the number of bytes to write is known and required, for example when writing in structures. Use WriteBuffer for standard file I/O streaming. WriteBuffer is used internally for writing to a stream. It is used by other objects, such as strings and lists, for writing strings stored in a buffer. WriteBuffer calls Write to handle the actual writing. Writes Count bytes from Buffer onto the stream. WriteBuffer attempts to write Count bytes from the Buffer to the current position in the stream, then WriteBuffer advances the current position by Count. If the stream fails to write all the requested bytes, an EWriteError exception is raised. Offset specifies a zero-based position in Buffer of the first byte to write. Use WriteBuffer to save data to a stream. WriteBuffer is used in cases, where the number of bytes to write is known and required, for example when writing in structures. Use WriteBuffer for standard file I/O streaming. WriteBuffer is used internally for writing to a stream. It is used by other objects, such as strings and lists, for writing strings stored in a buffer. WriteBuffer calls Write to handle the actual writing.

WriteBufferData(Buffer: Integer, Count: NativeInt)#

Writes up to 4 four or Count bytes from Buffer onto the stream. WriteBufferData works using the following algorithms:

If Count <= 4, then WriteBufferData tries to write up to Count bytes to the stream starting at the current position and advances the current position in the stream by the number of bytes transferred. If Count > 4, then WriteBufferData tries to write up to 4 four bytes to the stream, starting at the current position, and then advances the current position in the stream until Count number of bytes from the initial position that was before the starting of WriteBufferData execution.

WriteBytes()#: Write content as bytes.

WriteComponent(Instance: Component)#: Initiates the writing of components and their properties to a stream. WriteComponent is used internally in the component streaming system, but can also be called directly when writing components to memory streams or database blobs. WriteComponent constructs a writer object and calls its WriteRootComponent method to write the component specified by Instance, and its owned objects, to the stream.

WriteComponentRes(ResName: string, Instance: Component)#: Writes components and their properties to a stream from a resource file format. WriteComponentRes is used internally in the streaming system, but can also be called directly when sending data to other applications on disk. WriteComponentRes is used for streaming components that need data, such as a bitmap or icon to be stored in a resource-file format. WriteComponentRes calls WriteDescendentRes, passing in nil (Delphi) or NULL (C++) as the Ancestor. Therefore, WriteDescendentRes initiates the remainder of the streaming process for a component that, in this case, is not a descendant. To read a component written with WriteComponentRes, call the ReadComponentRes method.

WriteData(Buffer: Array<System.Byte>, Count: NativeInt) → NativeInt#

Methods responsible for writing up to Count bytes from Buffer to the stream. WriteData is used in cases, where the number of bytes to write to the stream is not necessarily fixed. WriteData works using the following algorithms:

When WriteData does not have the Count parameter, then WriteData tries to write the SizeOf(Buffer) number of bytes. WriteData advances the current position in the stream by the number of bytes transferred. WriteData returns the number of bytes written. When WriteData has the Count parameter, then: If Count > SizeOf(Buffer), then WriteData tries to write the SizeOf(Buffer) number of bytes. WriteData advances the current position in the stream by the Count number of bytes. If Count <= SizeOf(Buffer), then WriteData tries to write up to the Count number of bytes to the stream and then advances the current position in the stream by the number of bytes transferred. WriteData returns the number of bytes written, which may be less than Count. WriteData methods call Write to do their actual writing. Methods responsible for writing up to Count bytes from Buffer to the stream. WriteData is used in cases, where the number of bytes to write to the stream is not necessarily fixed. WriteData works using the following algorithms:

WriteDescendent(Instance: Component, Ancestor: Component)#: Streams components and their properties in inherited forms. Do not call WriteDescendent directly. WriteDescendent is called automatically by WriteComponent. WriteDescendent constructs a writer object, then calls the writer object’s WriteDescendent method to write the component passed in Instance to the stream. Instance is either an inherited form descended from Ancestor or nil (Delphi) or NULL (C++). However, WriteDescendent is never used to write owned components, only to initiate streaming on the root component.

WriteDescendentRes(ResName: string, Instance: Component, Ancestor: Component)#: Streams components and their properties in inherited forms. Do not call WriteDescendentRes directly. WriteDescendentRes is called automatically by WriteComponentRes. WriteDescendentRes writes a resource-file header to the stream, using the resource name passed in ResName as the name of the resource. It then calls WriteDescendent to write Instance to the stream as a descendant of Ancestor.

WriteFloat()#: Write content as float.

WriteInt()#: Write content as integer.

WriteResourceHeader(ResName: string, FixupInfo: Integer)#: Writes a resource-file header to the stream. Do not call WriteResourceHeader; it is used internally. The WriteDescendentRes method calls WriteResourceHeader before writing a component to the stream. This method writes the resource-file header, using the value passed as ResName for the name of the resource. It returns a position in FixupInfo that must be used to adjust the header after the size of the resource is known. WriteDescendentRes calls FixupResourceHeader with the value returned as FixupInfo after streaming out the component.

WriteString()#: Write content as string.