Using File Streams

The TFileStream class enables applications to read from and write to a file on disk. Because TFileStream is a stream object, it shares the common stream methods. You can use these methods to read from or write to the file, copy data to or from other stream classes, and read or write components values. See Using streams for details on the capabilities that files streams inherit by being stream classes.

In addition, file streams give you access to the file handle, so that you can use them with global file handling routines that require the file handle.

Creating and opening files using file streams

To create or open a file and get access to its handle, you simply instantiate a TFileStream. This opens or creates a specified file and provides methods to read from or write to it. If the file cannot be opened, the TFileStream constructor raises an exception.

Copy Code

constructor Create(const filename: string; Mode: Word);

Copy Code

__fastcall TFileStream(const AnsiString FileName, Word Mode);

The Mode parameter specifies how the file should be opened when creating the file stream. The Mode parameter consists of an open mode and a share mode OR'ed together. The open mode must be one of the following values:

Open modes

Value	Meaning
fmCreate	TFileStream a file with the given name. If a file with the given name exists, open the file in write mode.
fmOpenRead	Open the file for reading only.
fmOpenWrite	Open the file for writing only. Writing to the file completely replaces the current contents.
fmOpenReadWrite	Open the file to modify the current contents rather than replace them.

The share mode can be one of the following values with the restrictions listed below:

Share modes

Value	Meaning
fmShareCompat	Sharing is compatible with the way FCBs are opened (VCL applications only).
fmShareExclusive	Other applications can not open the file for any reason.
fmShareDenyWrite	Other applications can open the file for reading but not for writing.
fmShareDenyRead	Other applications can open the file for writing but not for reading (VCL applications only).
fmShareDenyNone	No attempt is made to prevent other applications from reading from or writing to the file.

Note that which share mode you can use depends on which open mode you used. The following table shows shared modes that are available for each open mode.

Shared modes available for each open mode

Open Mode	fmShareCompat (VCL)	fmShareExclusive	fmShareDenyWrite	fmShareDenyRead (VCL)	fmShareDenyNone
fmOpenRead	Can't use	Can't use	Available	Can't use	Available
fmOpenWrite	Available	Available	Can't use	Available	Available
fmOpenReadWrite	Available	Available	Available	Available	Available

The file open and share mode constants are defined in the SysUtils unit.

Using the file handle

When you instantiate TFileStream you get access to the file handle. The file handle is contained in the Handle property. On Windows, Handle is a Windows file handle. Handle is read-only and reflects the mode in which the file was opened. If you want to change the attributes of the file Handle, you must create a new file stream object.

Some file manipulation routines take a file handle as a parameter. Once you have a file stream, you can use the Handle property in any situation in which you would use a file handle. Be aware that, unlike handle streams, file streams close file handles when the object is destroyed.