Programming C++Builder Using Streams to Read or Write Data or Copy in C++Builder

Streams are classes that let you read and write data. They provide a common interface for reading and writing to different media such as memory, strings, sockets, and BLOB fields in databases. There are several stream classes, which all descend from TStream. Each stream class is specific to one media type. For example, TMemoryStream reads from or writes to a memory image, TFileStream reads from or writes to a file.
The following topics describe the methods common to all stream classes:

Using streams to read or write data.

Stream classes all share several methods for reading and writing data. These methods are distinguished by whether they perform the following:

  • Return the number of bytes read or written.
  • Require the number of bytes to be known.
  • Raise an exception on error.

Stream methods for reading and writing

The Read method reads a specified number of bytes from the stream, starting at its current Position, into a buffer. Read then advances the current position by the number of bytes actually transferred. The prototype for Read is

virtual int __fastcall Read(void *Buffer, int Count);

Read is useful when the number of bytes in the file is not known. Read returns the number of bytes actually transferred, which may be less than Count if the stream did not contain
Count bytes of data past the current position.
The Write method writes Count bytes from a buffer to the stream, starting at the current Position. The prototype for Write is:

virtual int __fastcall Write(const void *Buffer, int Count);

After writing to the file, Write advances the current position by the number bytes written, and returns the number of bytes actually written, which may be less than Count if the end of the buffer is encountered or the stream can抰 accept any more bytes.
The counterpart procedures are ReadBuffer and WriteBuffer which, unlike Read and Write, do not return the number of bytes read or written. These procedures are useful in cases where the number of bytes is known and required, for example when reading in structures. ReadBuffer and WriteBuffer raise an exception (EReadError and EWriteError) if the byte count can not be matched exactly. This is in contrast to the Read and Write methods, which can return a byte count that differs from the requested value. The prototypes for ReadBuffer and WriteBuffer are:

virtual int __fastcall ReadBuffer(void *Buffer, int Count);
virtual int __fastcall WriteBuffer(const void *Buffer, int Count);

These methods call the Read and Write methods to perform the actual reading and writing.

Reading and writing components

TStream defines specialized methods, ReadComponent and WriteComponent, for reading and writing components. You can use them in your applications as a way to save components and their properties when you create or alter them at runtime.
ReadComponent and WriteComponent are the methods that the IDE uses to read components from or write them to form files. When streaming components to or from a form file, stream classes work with the TFiler classes, TReader and TWriter, to read objects from the form file or write them out to disk. For more information about using the component streaming system, see TStream, TFiler, TReader, TWriter, and TComponent classes.

Copying data from one stream to another.

See an example below:

When copying data from one stream to another, you do not need to explicitly read and then write the data. Instead, you can use the CopyFrom method, as illustrated in the following example.
The application includes two edit controls (From and To) and a Copy File button.

void __fastcall TForm1::CopyFileClick(TObject *Sender)
  TStream* stream1= new TFileStream(From->Text,fmOpenRead | fmShareDenyWrite);
    TStream* stream2 = new TFileStream(To->Text, fmOpenWrite | fmShareDenyRead);
      stream2 -> CopyFrom(stream1, stream1->Size);
      delete stream2;
    delete stream1;

Specifying the stream position and size.

In addition to methods for reading and writing, streams permit applications to seek to an arbitrary position in the stream or change the size of the stream. Once you seek to a specified position, the next read or write operation starts reading from or writing to the stream at that position.

Seeking to a specific position

The Seek method is the most general mechanism for moving to a particular position in the stream. There are two overloads for the Seek method:

virtual int __fastcallSeek(int Offset, Word Origin);
virtual __int64 __fastcallSeek(const __int64Offset, TSeekOrigin Origin);

Both overloads work the same way. The difference is that one version uses a 32-bit integer to represent positions and offsets, while the other uses a 64-bit integer.
The Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:

Value Meaning
soFromBeginning Offset is from the beginning of the resource. Seek moves to the position Offset. Offset must be >= 0.
soFromCurrent Offset is from the current position in the resource. Seek moves to Position + Offset.
soFromEnd 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 resets the current stream position, moving it by the indicated offset. Seek returns the new current position in the stream.

Using Position and Size properties

All streams have properties that hold the current position and size of the stream. These are used by the Seek method, as well as all the methods that read from or write to the stream.
The Position property indicates the current offset, in bytes, into the stream (from the beginning of the streamed data).
The Size property indicates the size of the stream in bytes. It can be used to determine the number of bytes available for reading, or to truncate the data in the stream.

Size is used internally by routines that read and write to and from the stream.
Setting the Size property changes the size of the data in the stream. For example, on a file stream, setting Size inserts an end of file marker to truncate the file. If the Size of the stream cannot be changed, an exception is raised. For example, trying to change the Size of a read-only file stream raises an exception.

Add comment

Security code

Programming - C++Builder