#include <s32file.h>
| class RFileBuf : public TStreamBuf |
| Public Member Functions | |
|---|---|
| RFileBuf() | |
| RFileBuf(TInt) | |
| RFileBuf(TCapture< RFileBuf >) | |
| IMPORT_C void | Attach(RFile &, TInt) |
| IMPORT_C void | Close() |
| IMPORT_C TInt | Create(RFs &, const TDesC &, TUint) |
| void | Detach() |
| RFile & | File() |
| IMPORT_C TInt | Open(RFs &, const TDesC &, TUint) |
| void | Reattach(RFile &) |
| IMPORT_C TInt | Replace(RFs &, const TDesC &, TUint) |
| IMPORT_C void | Reset() |
| void | Reset(TInt) |
| IMPORT_C void | SetSizeL(TInt) |
| IMPORT_C TInt | Temp(RFs &, const TDesC &, TFileName &, TUint) |
| Protected Member Functions | |
|---|---|
| virtual IMPORT_C TInt | DoReadL(TAny *, TInt) |
| virtual IMPORT_C TInt | DoReadL(TDes8 &, TInt, TRequestStatus &) |
| virtual IMPORT_C void | DoRelease() |
| virtual IMPORT_C TStreamPos | DoSeekL(TMark, TStreamLocation, TInt) |
| virtual IMPORT_C void | DoSynchL() |
| virtual IMPORT_C void | DoWriteL(const TAny *, TInt) |
| virtual IMPORT_C TInt | DoWriteL(const TDesC8 &, TInt, TRequestStatus &) |
| virtual IMPORT_C void | OverflowL() |
| void | SetBuf(TRead, TUint8 *, TUint8 *) |
| void | SetBuf(TWrite, TUint8 *, TUint8 *) |
| void | SetBuf(TArea, TUint8 *, TUint8 *) |
| virtual IMPORT_C TInt | UnderflowL(TInt) |
| Inherited Enumerations | |
|---|---|
| MStreamBuf:TRead | |
| MStreamBuf:TWrite | |
| Inherited Type Definitions | |
|---|---|
| MStreamBuf::TMark | |
| TStreamBuf::TArea | |
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.
Open(), Close(), Attach(), Detach(), File() and Reattach() usage patterns:
Pattern 1: RFileBuf owns the file step 1a: Open()/Create()/Temp() is used to connect the buffer to a file step 1b: Use the file buffer step 1c: Close() releases this resource.
Pattern 2: RFile is opened elsewhere and ownership is handed over to RFileBuf This may happen if the file is already opened by another API, or from another process for example step 2a: Attach() is used to hand ownership of the opened file to the buffer. After Attach() the supplied file handle is NULLed. step 2b: Use the file buffer step 2c: Close() releases the file resource.
Pattern 3: RFileBuf is used transiently to manage an existing opened file: step 3a: Attach() is used to bind the buffer to the already open file. After Attach() the supplied file handle is NULLed. step 3b: Use the file buffer step 3c: RFileBuf::File() is used to retrieve the file handle again, then Detach() is called to disconnect the buffer from the file. At this point, the destruction of the file buffer will have no effect on the file. The retrieved file handle in step 3c must be used to close the file.
Pattern 4: Transient direct file access to a buffered file step 4a: RFileBuf::File() is used to retrieve the file handle. [Optional: Detach() is used to disconnect the file buffer] step 4b: Use the file directly. Note that writing to the file may cause coherency problems with the RFileBuf buffer - in which case you need to Reset() the buffer as well. step 4c: [Optional: Reattach() is used to hand the file back to the buffer]. Use of the buffer is resumed
See also: CFileStore RFileReadStream RFileWriteStream
| IMPORT_C | RFileBuf | ( | ) |
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 | ) |
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.
| Parameter | Description |
|---|---|
| aSize | The size of the intermediate buffer. |
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.
See also: Detach() Reattach()
| Parameter | Description |
|---|---|
| aFile | The file to be attached. |
| aPos | The offset within the file to which the read and write stream positions are set. By default this is zero. |
| IMPORT_C void | Close | ( | ) |
Reimplemented from MStreamBuf::Close()
Writes any outstanding data from the intermediate buffer before freeing the intermediate buffer and closing the attached file.
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.
| Parameter | Description |
|---|---|
| aFs | Handle to a file server session through which the file is created. |
| aName | The name of the file to be created. |
| aFileMode | The mode in which the file is to be accessed. The mode is defined by the TFileMode type. |
Returns: KErrNone, if successful, otherwise one of the other system wide error codes.
| void | Detach | ( | ) | [inline] |
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()
Reimplemented from TStreamBuf::DoReadL(TAny *,TInt)
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).
See also: MStreamBuf::ReadL() MStreamBuf::DoReadL()
| Parameter | Description |
|---|---|
| aPtr | A pointer to the target memory location for the data read from the intermediate buffer. |
| aMaxLength | The maximum number of bytes to be read. |
Returns: The number of bytes read. This may be less than the amount requested.
| IMPORT_C TInt | DoReadL | ( | TDes8 & | aDes, |
| TInt | aMaxLength, | |||
| TRequestStatus & | aStatus | |||
| ) | [protected, virtual] | |||
Reimplemented from MStreamBuf::DoReadL(TDes8 &,TInt,TRequestStatus &)
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.
See also: MStreamBuf::ReadL()
| Parameter | Description |
|---|---|
| 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. |
| 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. |
| aStatus | The request status that indicates the completion status of this asynchronous request. |
Returns: 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.
| IMPORT_C void | DoRelease | ( | ) | [protected, virtual] |
Reimplemented from MStreamBuf::DoRelease()
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()
| IMPORT_C TStreamPos | DoSeekL | ( | TMark | aMark, |
| TStreamLocation | aLocation, | |||
| TInt | anOffset | |||
| ) | [protected, virtual] | |||
Reimplemented from MStreamBuf::DoSeekL(TMark,TStreamLocation,TInt)
| IMPORT_C void | DoSynchL | ( | ) | [protected, virtual] |
Reimplemented from MStreamBuf::DoSynchL()
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()
Reimplemented from TStreamBuf::DoWriteL(const TAny *,TInt)
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).
See also: MStreamBuf::WriteL() MStreamBuf::DoWriteL()
| Parameter | Description |
|---|---|
| aPtr | A pointer to the source memory location for the data to be written to the intermediate buffer. |
| aLength | The number of bytes to be written. |
Returns: The number of bytes written.
| IMPORT_C TInt | DoWriteL | ( | const TDesC8 & | aDes, |
| TInt | aMaxLength, | |||
| TRequestStatus & | aStatus | |||
| ) | [protected, virtual] | |||
Reimplemented from MStreamBuf::DoWriteL(const TDesC8 &,TInt,TRequestStatus &)
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.
See also: MStreamBuf::WriteL()
| Parameter | Description |
|---|---|
| aDes | The source descriptor for the data to be written into the stream buffer. |
| 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. |
| aStatus | The request status that indicates the completion status of this asynchronous request. |
Returns: 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.
| RFile & | File | ( | ) | const [inline] |
Gets a reference to the file attached to this stream buffer.
Returns: The file attached to this stream buffer.
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.
| Parameter | Description |
|---|---|
| aFs | Handle to a file server session through which the file is opened. |
| aName | The name of the file to be opened. |
| aFileMode | The mode in which the file is to be accessed. The mode is defined by the TFileMode type. |
Returns: KErrNone, if successful, otherwise one of the other system wide error codes.
| IMPORT_C void | OverflowL | ( | ) | [protected, virtual] |
Reimplemented from TStreamBuf::OverflowL()
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.
| void | Reattach | ( | RFile & | aFile | ) | [inline] |
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.
| Parameter | Description |
|---|---|
| aFile | The file to be re-attached. |
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.
| Parameter | Description |
|---|---|
| aFs | Handle to a file server session through which the file is replaced. |
| aName | The name of the file to be replaced. |
| aFileMode | The mode in which the file is to be accessed. The mode is defined by the TFileMode type. |
Returns: KErrNone, if successful, otherwise one of the other system wide error codes.
| IMPORT_C void | Reset | ( | ) |
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.
| void | Reset | ( | TInt | aSize | ) | [inline] |
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.
| Parameter | Description |
|---|---|
| aSize | The size of any future intermediate buffer. |
Reimplemented from TStreamBuf::SetBuf(TRead,TUint8 *,TUint8 *)
Sets the start and end points of the read area within the intermediate buffer.
See also: MStreamBuf::TRead TStreamBuf::SetBuf
| Parameter | Description |
|---|---|
| aPtr | The start point. |
| anEnd | The end point. |
Reimplemented from TStreamBuf::SetBuf(TWrite,TUint8 *,TUint8 *)
Sets the start and end points of the read area within the intermediate buffer.
See also: MStreamBuf::TWrite TStreamBuf::SetBuf
| Parameter | Description |
|---|---|
| aPtr | The start point. |
| anEnd | The end point. |
Reimplemented from TStreamBuf::SetBuf(TArea,TUint8 *,TUint8 *)
Sets the start and end points of the read area within the intermediate buffer.
See also: MStreamBuf::TArea TStreamBuf::SetBuf
| Parameter | Description |
|---|---|
| aPtr | The start point. |
| anEnd | The end point. |
| IMPORT_C void | SetSizeL | ( | TInt | aSize | ) |
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.
| Parameter | Description |
|---|---|
| aSize | The new size of the file. |
Creates and opens a temporary file with a unique name and attaches it to this stream buffer.
| Parameter | Description |
|---|---|
| aFs | Handle to a file server session through which the file is created. |
| aPath | The directory in which the file is created. |
| aName | On return, contains the full path and file name of the file. The filename is guaranteed to be unique within the specified directory. |
| aFileMode | The mode in which the file is to be accessed. The mode is defined by the TFileMode type. |
Reimplemented from TStreamBuf::UnderflowL(TInt)
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.
| Parameter | Description |
|---|---|
| aMaxLength | The maximum amount of data required for the intermediate buffer. |
Returns: The amount of data available in the intermediate buffer.