Class RFileBuf

class RFileBuf : public TStreamBuf;

Description

A stream buffer hosted by a file. Instances of this class are used by file based persistent stores, i.e. CFileStore type objects. An RFileBuf object is associated with a file and the file is said to be attached to the stream buffer.

An RFileBuf object is also used by RFileReadStream and RFileWriteStream objects to provide buffered file I/O.

The stream buffer has intermediate buffering capabilities.

When used as the basis for a file store, it hosts multiple streams through the TStreamExchange and RShareBuf classes

Derivation

• MStreamBuf - A stream buffer that provides a generic I/O interface for streamed data

• TStreamBuf - Adds buffering capabilities to a stream buffer

• RFileBuf - A stream buffer hosted by a file

Members

Defined in RFileBuf:
Attach(), Close(), Create(), Detach(), DoReadL(), DoReadL(), DoRelease(), DoSeekL(), DoSynchL(), DoWriteL(), DoWriteL(), File(), Open(), OverflowL(), RFileBuf(), RFileBuf(), Reattach(), Replace(), Reset(), Reset(), SetBuf(), SetBuf(), SetBuf(), SetSizeL(), Temp(), UnderflowL()

Inherited from MStreamBuf:
ERead, EWrite, PushL(), Read(), ReadL(), Release(), SeekL(), SizeL(), Synch(), SynchL(), TMark, TRead, TWrite, TellL(), Write(), WriteL()

Inherited from TStreamBuf:
Avail(), End(), Ptr(), SetEnd(), SetPtr(), TArea

See also:

• CFileStore
• RFileReadStream
• RFileWriteStream

IMPORT_C RFileBuf();

Description

Constructs the object with a default intermediate buffer size.

The size of the intermediate buffer is the value of the constant KDefaultFileBufSize.

IMPORT_C RFileBuf(TInt aSize);

Description

Constructs the object with the specified intermediate buffer size.

If the intermediate buffer size is zero, then the class provides an MStreamBuf interface to unbuffered file I/O.

Parameters

TInt aSize The size of the intermediate buffer.

IMPORT_C void Reset();

Description

Frees the intermediate buffer.

If there is any read data in the intermediate buffer, then the function reverts the read position within the stream.

The intermediate buffer must not contain any outstanding write data, otherwise the function raises a STORE-File 6 panic.

inline void Reset(TInt aSize);

Description

Frees the intermediate buffer and changes the size of any future intermediate buffer to the specified value.

The intermediate buffer must not contain any outstanding write data, otherwise the function raises a STORE-File 6 panic.

Parameters

TInt aSize The size of any future intermediate buffer.

IMPORT_C TInt Open(RFs &aFs, const TDesC &aName, TUint aFileMode);

Description

Opens the specified file and attaches it to this stream buffer.

If the file cannot be opened, then it is not attached to this stream buffer.

Parameters

RFs &aFs Handle to a file server session through which the file is opened. const TDesC &aName The name of the file to be opened. TUint aFileMode The mode in which the file is to be accessed. The mode is defined by the TFileMode type.

Return value

TInt KErrNone, if successful, otherwise one of the other system wide error codes.

See also:

• Attach()
• TFileMode
• RFile

IMPORT_C TInt Create(RFs &aFs, const TDesC &aName, TUint aFileMode);

Description

Creates a file with the specified name and attaches it to this stream buffer.

The file must not already exist.

If the file cannot be created and opened, then it is not attached to this stream buffer.

Parameters

RFs &aFs Handle to a file server session through which the file is created. const TDesC &aName The name of the file to be created. TUint aFileMode The mode in which the file is to be accessed. The mode is defined by the TFileMode type.

Return value

TInt KErrNone, if successful, otherwise one of the other system wide error codes.

See also:

• Attach()
• TFileMode
• RFile

IMPORT_C TInt Replace(RFs &aFs, const TDesC &aName, TUint aFileMode);

Description

Replaces the file with the specified name and attaches it to this stream buffer.

If there is an existing file with the same name, then this function overwrites it. If the file does not already exist, it is created.

If the file cannot be replaced, then it is not attached to this stream buffer.

Parameters

RFs &aFs Handle to a file server session through which the file is replaced. const TDesC &aName The name of the file to be replaced. TUint aFileMode The mode in which the file is to be accessed. The mode is defined by the TFileMode type.

Return value

TInt KErrNone, if successful, otherwise one of the other system wide error codes.

See also:

• Attach()
• TFileMode
• RFile

IMPORT_C TInt Temp(RFs &aFs, const TDesC &aPath, TFileName &aName, TUint aFileMode);

Description

Creates and opens a temporary file with a unique name and attaches it to this stream buffer.

Parameters

RFs &aFs Handle to a file server session through which the file is created. const TDesC &aPath The directory in which the file is created. TFileName &aName On return, contains the full path and file name of the file. The filename is guaranteed to be unique within the specified directory. TUint aFileMode The mode in which the file is to be accessed. The mode is defined by the TFileMode type.

Return value

TInt

See also:

• Attach()
• TFileMode
• RFile

IMPORT_C void Attach(RFile &aFile, TInt aPos=0);

Description

Attaches the specified file to this stream buffer.

The function also re-sets the intermediate buffer's read and write marks to the beginning of the intermediate buffer and sets the read and write stream positions to the specified offset within the file.

Parameters

RFile &aFile The file to be attached. TInt aPos The offset within the file to which the read and write stream positions are set. By default this is zero.

See also:

• Detach()
• Reattach()

IMPORT_C void Close();

Description

Writes any outstanding data from the intermediate buffer before freeing the intermediate buffer and closing the attached file.

inline void Detach();

Description

Detaches the file from this stream buffer.

The intermediate buffer's read and write marks are not changed, and the stream positions are not changed. This means that the contents of the file should not change while it is detached.

See also:

• Attach()
• Reattach()

inline void Reattach(RFile &aFile);

Description

Re-attaches the specified file to this stream buffer.

The intermediate buffer's read and write marks are not changed, and the stream positions are not changed.

The file should be the one that was detached using the Detach() function.

Parameters

RFile &aFile The file to be re-attached.

See also:

• Attach()
• Detach()

IMPORT_C void SetSizeL(TInt aSize);

Description

Changes the size of the file attached to this buffer to the specified value.

Writes any outstanding data from the intermediate buffer to the stream hosted by the file. Any data in the intermediate buffer that would lie beyond the end of the truncated file, is not written.

Parameters

TInt aSize The new size of the file.

inline RFile &File() const;

Description

Gets a reference to the file attached to this stream buffer.

Return value

RFile & The file attached to this stream buffer.

protected: virtual IMPORT_C TInt UnderflowL(TInt aMaxLength);

Description

Re-fills the intermediate buffer and resets the start and end points of the read area.

The implementation of this function depends on the way the stream itself is implemented. For example, the in-memory streams have simple implementations.

Parameters

TInt aMaxLength The maximum amount of data required for the intermediate buffer.

Return value

TInt The amount of data available in the intermediate buffer.

protected: virtual IMPORT_C void OverflowL();

Description

Empties the intermediate buffer and resets the start and end points of the write area.

The implementation of this function depends on the way the stream itself is implemented. For example, the in-memory streams have simple implementations.

protected: virtual IMPORT_C void DoRelease();

Description

Frees resources before abandoning the stream buffer.

It is called by Release().

This implementation is empty, but classes derived from MStreamBuf can provide their own implementation, if necessary.

See also:

• MStreamBuf::Release()

protected: virtual IMPORT_C void DoSynchL();

Description

Synchronises the stream buffer with the stream, leaving if any error occurs.

In effect, this ensures that buffered data is delivered to the stream.

It is called by SynchL().

This implementation is empty, but classes derived from MStreamBuf can provide their own implementation, if necessary.

See also:

• MStreamBuf::SynchL()

protected: virtual IMPORT_C TInt DoReadL(TAny *aPtr, TInt aMaxLength);

Description

Reads data from the intermediate buffer into the specified memory location.

The function calls the virtual function UnderfLowL() to give concrete implementations the chance to refill the intermediate buffer, and satisfy the caller's requirements.

This implementation overrides the one supplied by the base class MStreamBuf, and is called by, MStreamBuf::ReadL(TAny*,TInt).

Parameters

TAny *aPtr A pointer to the target memory location for the data read from the intermediate buffer. TInt aMaxLength The maximum number of bytes to be read.

Return value

TInt The number of bytes read. This may be less than the amount requested.

See also:

• MStreamBuf::ReadL()
• MStreamBuf::DoReadL()

protected: virtual IMPORT_C TInt DoReadL(TDes8 &aDes, TInt aMaxLength, TRequestStatus &aStatus);

Description

Reads data from the stream buffer into the specified descriptor.

This function is called by ReadL(TDes8&,TInt,TRequestStatus&).

This implementation deals with the request synchronously, and completes the request with KErrNone. Other implementations may choose to deal with this in a true asynchronous manner.

In addition, the read operation itself uses the DoReadL(TAny*,TInt) variant.

Parameters

TDes8 &aDes The target descriptor for the data read from the stream buffer. On return, the length of the descriptor is set to the number of bytes read from the stream buffer. TInt aMaxLength The maximum number of bytes to be read. This value must not be greater than the maximum length of the descriptor, otherwise the function raises a STORE-Stream 2 panic. TRequestStatus &aStatus The request status that indicates the completion status of this asynchronous request.

Return value

TInt The maximum number of bytes to be read, as used in this request. This implementation uses, and returns, the value supplied in aMaxLength. Other implementations may choose to use a different value.

See also:

• MStreamBuf::ReadL()

protected: virtual IMPORT_C void DoWriteL(const TAny *aPtr, TInt aLength);

Description

Writes data from the specified memory location into the intermediate buffer.

The function calls the virtual function OverfLowL() to give concrete implementations the chance to forward the intermediate buffer content to its destination.

This implementation overrides the one supplied by the base class MStreamBuf, and is called by MStreamBuf::WriteL(const TAny*,TInt).

Parameters

const TAny *aPtr A pointer to the source memory location for the data to be written to the intermediate buffer. TInt aLength The number of bytes to be written.

See also:

• MStreamBuf::WriteL()
• MStreamBuf::DoWriteL()

protected: virtual IMPORT_C TInt DoWriteL(const TDesC8 &aDes, TInt aMaxLength, TRequestStatus &aStatus);

Description

Writes data from the specified descriptor into this stream buffer.

This function is called by WriteL(const TDesC8&,TInt,TRequestStatus&).

This implementation deals with the request synchronously, and completes the request with KErrNone. Other implementations may choose to deal with this in a true asynchronous manner.

In addition, the write operation itself uses the DoWriteL(TAny*,TInt) variant.

Parameters

const TDesC8 &aDes The source descriptor for the data to be written into the stream buffer. TInt aMaxLength The number of bytes to be written. This value must not be greater than the maximum length of the descriptor, otherwise the function raises a STORE-Stream 6 panic. TRequestStatus &aStatus The request status that indicates the completion status of this asynchronous request.

Return value

TInt The maximum number of bytes to be written, as used in this request. This implementation uses, and returns, the value supplied in aMaxLength. Other implementations may choose to use a different value.

See also:

• MStreamBuf::WriteL()

protected: virtual IMPORT_C TStreamPos DoSeekL(TMark aMark, TStreamLocation aLocation, TInt anOffset);

Description

Parameters

TMark aMark TStreamLocation aLocation TInt anOffset

Return value

TStreamPos

protected: inline void SetBuf(TRead, TUint8 *aPtr, TUint8 *anEnd);

Description

Sets the start and end points of the read area within the intermediate buffer.

A start point is always within an area; an end point is always the first byte beyond the end of an area.

Parameters

TRead TUint8 *aPtr The start point. TUint8 *anEnd The end point.

See also:

• MStreamBuf::TRead

protected: inline void SetBuf(TWrite, TUint8 *aPtr, TUint8 *anEnd);

Description

Sets the start and end points of the write area within the intermediate buffer.

A start point is always within an area; an end point is always the first byte beyond the end of an area.

Parameters

TWrite TUint8 *aPtr The start point. TUint8 *anEnd The end point.

See also:

• MStreamBuf::TWrite

protected: inline void SetBuf(TArea anArea, TUint8 *aPtr, TUint8 *anEnd);

Description

Sets the start and end points of the read and/or the write area within the intermediate buffer.

A start point is always within an area; an end point is always the first byte beyond the end of an area.

Parameters

TArea anArea The areas within the intermediate buffer for which the start and end points are to be set. These can be the read area and/or the write area, as indicated by the ERead and EWrite bits. Only these bits can be set, otherwise the function raises a STORE-Stream 17 panic. TUint8 *aPtr The start point. TUint8 *anEnd The end point.

See also:

• MStreamBuf::TRead
• MStreamBuf::TWrite