Class: TFileStream

Declaration: FileSystemInterface.h

Taxonomy Categories:

Member Functions:

Flush
GetPosition
GetLogicalEndOfStream
GetPhysicalEndOfStream
Seek
SetLogicalEndOfStream
GetEndOfFile
SetEndOfFile
~TFileStream
InitializeFileStream
SetPhysicalEndOfStream
HandleBufferFull
HandleBufferEmpty
AllocateForRead
AllocateForWrite
HandleReadBufferEmpty
HandleWriteBufferFull
TFileStream

Interface Category:

API.

Inherits From:

MOpenFile, TRandomAccessStream

Inherited By:

None.

Purpose:

Read or write a file via a stream.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Do not derive from this class.

Concurrency:

Not multithread safe. This is a handle class.

Resource Use:

No special requirements.

Member Function: TFileStream::Flush

virtual void Flush ()

Interface Category:

API.

Purpose:

Flushes changes to disk: buffered data is written to disk.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemVolumeAccessError if the volume is full or a media error occurs. Throws TFileSystemAccessDenied if the caller does not have permission to write to the file.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileStream::GetPosition

virtual StreamPosition GetPosition () const

Interface Category:

API.

Purpose:

Obtains the current read/write pointer for the stream.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The current read/write pointer for the stream.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileStream::GetLogicalEndOfStream

virtual StreamPosition GetLogicalEndOfStream () const

Interface Category:

API.

Purpose:

Obtains the logical size of the stream (file).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The logical size of the stream (file).

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileStream::GetPhysicalEndOfStream

virtual StreamPosition GetPhysicalEndOfStream () const

Interface Category:

API.

Purpose:

Obtains the physical size of the stream (file).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The physical size of the stream (file).

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

This is identical to GetLogicalEndOfStream and GetEndOfFile.

Member Function: TFileStream::Seek

virtual void Seek (StreamPosition position)

Interface Category:

API.

Purpose:

Sets the read/write pointer for the stream.

Calling Context:

Call this function directly.

Parameters:

StreamPosition position -Where to set the read/write pointer.

Return Value:

None.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemAccessDenied if the position is beyond the current logical end-of-file, and the caller is not privileged to write to the file. Throws TFileSystemVolumeAccessError if the position is beyond the current logical end-of-file, and there is insufficient room on the volume to expand the file.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileStream::SetLogicalEndOfStream

virtual void SetLogicalEndOfStream (StreamPosition)

Interface Category:

API.

Purpose:

Sets the logical size of the stream (file).

Calling Context:

Call this function directly.

Parameters:

StreamPosition -The new logical end of the stream.

Return Value:

None.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemAccessDenied if the caller is not privileged to write to the file. Throws TFileSystemVolumeAccessError if the position is beyond the current logical end-of-file, and there is insufficient room on the volume to expand the file.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

This is identical to SetEndOfFile and SetPhysicalEndOfStream.

Member Function: TFileStream::GetEndOfFile

FileSystemEntitySize GetEndOfFile () const

Interface Category:

API.

Purpose:

Gets the logical size of the file (stream).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The logical size of the file (stream).

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

This is identical to GetLogicalEndOfStream and GetPhysicalEndOfStream.

Member Function: TFileStream::SetEndOfFile

void SetEndOfFile (FileSystemEntitySize endOfFile)

Interface Category:

API.

Purpose:

Sets the logical size of the file (stream).

Calling Context:

Call this function directly.

Parameters:

FileSystemEntitySize endOfFile -The new end of the file.

Return Value:

None.

Exceptions:

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

This is identical to SetLogicalEndOfStream and SetPhysicalEndOfStream.

Member Function: TFileStream::~TFileStream

virtual ~ TFileStream ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileStream::InitializeFileStream

void InitializeFileStream (const TFile & file, MOpenFile :: EPermissionsForMe forMe, MOpenFile :: EPermissionsForOthers forOthers, FileSystemEntitySize bufferSize)

Interface Category:

API.

Purpose:

Initializes the stream (allows delayed initialization by derived class constructors).

Calling Context:

Called by the default copy constructor of a derived class.

Parameters:

const TFile & file -The file to be streamed.
MOpenFile :: EPermissions permissions -Read/write permissions for the open-file operation.
FileSystemEntitySize bufferSize =kDefaultBufferSize -The size of the internal data buffer.
MOpenFile :: EPermissionsForMe forMe -Access permissions for the caller.
MOpenFile :: EPermissionsForOthers forOthers -Access permissions for subsequent attempts to open the file.
FileSystemEntitySize bufferSize -The suggested buffer size for reads and writes.

Return Value:

None.

Exceptions:

Throws TFileSystemEntityNotAvailable if the entity cannot be found. Throws TFileSystemAccessDenied if the caller is not privileged to open the file with the requested permissions.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileStream::SetPhysicalEndOfStream

virtual void SetPhysicalEndOfStream (StreamPosition)

Interface Category:

API.

Purpose:

Sets the physical size of the stream (file). For use by derived classes; clients can call SetLogicalEndOfStream or SetEndOfFile to change the file size.

Calling Context:

Not normally called except by derived classes.

Parameters:

StreamPosition -The new physical end of stream.

Return Value:

None.

Exceptions:

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

This is identical to SetLogicalEndOfStream and SetEndOfFile.

Member Function: TFileStream::HandleBufferFull

virtual void HandleBufferFull (signed char c)
virtual void HandleBufferFull (unsigned char c)
virtual void HandleBufferFull (short c)
virtual void HandleBufferFull (unsigned short c)
virtual void HandleBufferFull (long c)
virtual void HandleBufferFull (unsigned long c)
virtual void HandleBufferFull (float c)
virtual void HandleBufferFull (double c)
virtual void HandleBufferFull (const short c [], size_t count)
virtual void HandleBufferFull (const unsigned short c [], size_t count)
virtual void HandleBufferFull (const long c [], size_t count)
virtual void HandleBufferFull (const unsigned long c [], size_t count)
virtual void HandleBufferFull (const float c [], size_t count)
virtual void HandleBufferFull (const double c [], size_t count)

Interface Category:

API.

Purpose:

Fills the internal buffer from the specified source.

Calling Context:

Not normally called except by derived classes.

Parameters:

signed char c -The source data.
unsigned char c -The source data.
short c -The source data.
unsigned short c -The source data.
long c -The source data.
unsigned long c -The source data.
float c -The source data.
double c -The source data.
const short c [] -The array of source data.
size_t count -The number of items in the source array.
const unsigned short c [] -The array of source data.
size_t count -The number of items in the source array.
const long c [] -The array of source data.
size_t count -The number of items in the source array.
const unsigned long c [] -The array of source data.
size_t count -The number of items in the source array.
const float c [] -The array of source data.
size_t count -The number of items in the source array.
const double c [] -The array of source data.
size_t count -The number of items in the source array.

Return Value:

None.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TFileSystemAccessDenied if the caller is not privileged to write to the file.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileStream::HandleBufferEmpty

virtual void HandleBufferEmpty (signed char & c)
virtual void HandleBufferEmpty (unsigned char & c)
virtual void HandleBufferEmpty (short & c)
virtual void HandleBufferEmpty (unsigned short & c)
virtual void HandleBufferEmpty (long & c)
virtual void HandleBufferEmpty (unsigned long & c)
virtual void HandleBufferEmpty (float & c)
virtual void HandleBufferEmpty (double & c)
virtual void HandleBufferEmpty (short c [], size_t count)
virtual void HandleBufferEmpty (unsigned short c [], size_t count)
virtual void HandleBufferEmpty (long c [], size_t count)
virtual void HandleBufferEmpty (unsigned long c [], size_t count)
virtual void HandleBufferEmpty (float c [], size_t count)
virtual void HandleBufferEmpty (double c [], size_t count)

Interface Category:

API.

Purpose:

Empties the internal buffer by transferring its contents to the specified destination.

Calling Context:

Not normally called except by derived classes.

Parameters:

signed char & c -A pointer to the destination of the data.
unsigned char & c -A pointer to the destination of the data.
short & c -A pointer to the destination of the data.
unsigned short & c -A pointer to the destination of the data.
long & c -A pointer to the destination of the data.
unsigned long & c -A pointer to the destination of the data.
float & c -A pointer to the destination of the data.
double & c -A pointer to the destination of the data.
short c [] -A pointer to the destination of the data.
size_t count -The number of data items to be transferred.
unsigned short c [] -A pointer to the destination of the data.
size_t count -The number of data items to be transferred.
long c [] -A pointer to the destination of the data.
size_t count -The number of data items to be transferred.
unsigned long c [] -A pointer to the destination of the data.
size_t count -The number of data items to be transferred.
float c [] -A pointer to the destination of the data.
size_t count -The number of data items to be transferred.
double c [] -A pointer to the destination of the data.
size_t count -The number of data items to be transferred.

Return Value:

None.

Exceptions:

Throws TFileSystemObjectInvalid if the entity is uninitialized. Throws TStreamException::kHitLogicalEndOfStream if an attempt is made to read beyond end-of-file.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileStream::AllocateForRead

virtual void AllocateForRead (StreamPosition)

Interface Category:

API.

Purpose:

An inherited function for increasing the storage provided by the read buffer. This implementation does nothing.

Calling Context:

Not normally called except by derived classes.

Parameters:

StreamPosition desiredByteCount -The number of bytes needed in the read buffer.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileStream::AllocateForWrite

virtual void AllocateForWrite (StreamPosition)

Interface Category:

API.

Purpose:

An inherited function for increasing the storage provided by the write buffer. This implementation does nothing.

Calling Context:

Not normally called except by derived classes.

Parameters:

StreamPosition desiredByteCount -The number of bytes needed in the write buffer.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileStream::HandleReadBufferEmpty

virtual void HandleReadBufferEmpty (void * destination, size_t destinationSize)

Interface Category:

API.

Purpose:

Called to fill the buffer with data from the source.

Calling Context:

Not normally called except by derived classes.

Parameters:

void * destination -The destination for the data.
size_t destinationSize -The amount of data to be read, in bytes.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileStream::HandleWriteBufferFull

virtual void HandleWriteBufferFull (const void * source, size_t sourceSize)

Interface Category:

API.

Purpose:

Called to empty the source by writing the data out.

Calling Context:

Not normally called except by derived classes.

Parameters:

const void * source -The source of the data.
size_t sourceSize -The amount of data to be written, in bytes.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileStream::TFileStream

TFileStream (const TFile & file, MOpenFile :: EPermissionsForMe forMe =MOpenFile :: kReadWrite, MOpenFile :: EPermissionsForOthers forOthers =MOpenFile :: kAllowNone)
TFileStream (const TFile & file, FileSystemEntitySize bufferSize, MOpenFile :: EPermissionsForMe forMe =MOpenFile :: kReadWrite, MOpenFile :: EPermissionsForOthers forOthers =MOpenFile :: kAllowNone)
TFileStream ()

Interface Category:

API.

Purpose:

Constructs a TFileStream for a specified file.
Constructs a TFileStream for a specified file.
Default constructor.

Calling Context:

Call this function directly.
Call this function directly.
Called by the stream-in operators.

Parameters:

const TFile & file -The file to be opened.
MOpenFile :: EPermissionsForMe forMe =MOpenFile :: kReadWrite -Access permissions for the caller.
MOpenFile :: EPermissionsForOthers forOthers =MOpenFile :: kAllowNone -Access permission limitations for subsequent attempts to open the file made while this caller still holds the file open.
const TFile & file -The file to be opened.
FileSystemEntitySize bufferSize -The suggested buffer size.
MOpenFile :: EPermissionsForMe forMe =MOpenFile :: kReadWrite -Access permissions for the caller.
MOpenFile :: EPermissionsForOthers forOthers =MOpenFile :: kAllowNone -Access permission limitations for subsequent attempts to open the file made while this caller still holds the file open.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws TFileSystemEntityNotAvailable if the entity cannot be found. Throws TFileSystemAccessDenied if the caller is not privileged to open the file with the requested permissions.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.