#include <f32filemap.h>
| class RFileMap : public RSubSessionBase |
| Public Member Functions | |
|---|---|
| EFSRV_IMPORT_C TUint8 * | Base() |
| EFSRV_IMPORT_C void | Close() |
| EFSRV_IMPORT_C TInt | Flush() |
| EFSRV_IMPORT_C void | Flush(TRequestStatus &) |
| EFSRV_IMPORT_C TInt | Open(RFs &, const TDesC &, TUint, TUint64, TUint64, TUint) |
| EFSRV_IMPORT_C TInt | Open(RFile &, TUint64, TUint64, TUint, TOwnerType) |
| EFSRV_IMPORT_C TInt | PageSizeInBytes() |
A handle to a sub-session for memory mapped files.
Memory mapped files enable a program to access file data as if it is normal memory. The client receives a pointer to area of memory which appears to the program as if it contains the contents of the file. Reading and writing to the file is accomplished simply by accessing the memory locations pointed to.
Reading from and writing to a file via a file mapping can be more efficient than accessing a file via read and write calls to the RFile API as data is read from the file on demand in pages, and these pages are cached in the systems paging cache.
Without memory mapped files, similar efficiency is possible by implementing a page-based buffering scheme. However, this would not provide the effect of file data transparently appearing as an area of memory.
RFileMap provides clients with the ability to:
Open a memory mapped file sub-session.
Read and write to a mapped area of memory.
Explicitly flush dirty data to disk.
Memory mapped files is an extension to the demand paging system on Symbian OS and as a result the size of file mappings are multiples of the ARM page size which can be obtained by calling RFileMap::PageSizeInBytes().
RFileMap supports the mapping of files on removable media. This is not enabled by default and needs to be enabled by setting the correct flag from TFileMapMode when opening the mapping. When mapping files on removable media, the client also needs to consider how to cope with a media dismount as after a dismount, any subsequent access to the file mapping's memory area will cause the accessing thread to panic.
| EFSRV_IMPORT_C TUint8 * | Base | ( | ) |
Gets a pointer to the base of the file mapping's region.
Note - The returned pointer is process specific and should not be used by other processes. Other processes wishing to memory map the same file region should open their own RFileMap.
| EFSRV_IMPORT_C void | Close | ( | ) |
Close the file mapping.
If this is a writable file mapping it will cause any dirty data mapped by this mapping to be written to the file.
| EFSRV_IMPORT_C TInt | Flush | ( | ) |
Flush any dirty data currently buffered in RAM to the file.
This is a synchronous method, the flush operation will complete before it returns.
| EFSRV_IMPORT_C void | Flush | ( | TRequestStatus & | aStatus | ) |
Flush any dirty data currently buffered in RAM to the file.
This is an asynchronous function, the method will return immediately and aStatus will be completed once the flush operation has finished.
| Parameters | |
|---|---|
| aStatus | A reference to a TRequestStatus object that will be completed once the flush has finished. Once aStatus has been completed TRequestStatus::Int() should be used to determine the result of the flush operation. |
| EFSRV_IMPORT_C TInt | Open | ( | RFs & | aFs, |
| const TDesC & | aName, | |||
| TUint | aFileMode, | |||
| TUint64 | aOffset, | |||
| TUint64 | aSize, | |||
| TUint | aMapMode | |||
| ) | ||||
Open and map a section of a file of the specified name.
When opening a file mapping, you must specify the file server session to use for operations with that file mapping. If you do not close the file mapping explicitly, it is closed when the file server session associated with it is closed.
Multiple mappings on the same file can exist provided the correct share mode is supplied. In the case where the mapped regions overlap, changes made in one mapped region will be visible in the others.
The mapped region, defined by the combination of aOffset and aSize used, must fall completely within the file being mapped. For example, if aOffset is set to one page from the end of the file, then the maximum valid size of the mapped region will be the size of a single page. To map an entire file, aOffset must be set to zero and aSize to the size of the file.
When a file mapping is open, it will not be possible to change the size of the file in such a way that the mapped region no longer falls within the file. For example, if any file mapping exists on a file, a call to RFs::SetSize() which shrinks the file to the point that the new end point of the file falls within the mapped region will fail. It is possible to grow the file (and shrink it again by the same amount). Once the mapping(s) are closed, shrinking of the file will be possible again.
Restrictions exist on whether file mappings can be opened when file server plugins and extensions have already been mounted on a particular drive. These are:
If an open file mapping exists on a drive, a plugin which modifies file data or metadata will fail to mount on that drive (RFs::MountPlugin() will fail). In the case where KPluginAutoAttach is used to mount the plugin, the modifier plugin will mount on all applicable drives except ones with open file mappings. RFs::MountPlugin() will return KErrNone if the plugin succeeds in being mounted on any drive. Once the file mappings have been closed, it will be possible to mount the plugins again.
If a modifier plugin has been mounted on a drive (via KPluginAutoAttach or otherwise), a file mapping cannot be opened on that drive and the call to RFileMap::Open() will fail.
Observer plugins which do not change file data or metadata can coexist with file mappings.
If an open file mapping exists on a drive, file server extensions (modifier or not) cannot be mounted on that drive and the call to RFs::MountExtension() will fail.
If a modifier file server extension is mounted on a drive, a file mapping cannot be opened on that drive.
If an observer file extension is mounted on a drive, a file mapping can be opened on that drive.
This method will fail, returning KErrNotSupported, when used to open a file that is stored on a USB On-The-Go drive, e.g. a file stored on a USB memory stick or USB hard drive connected to the device.
See also: TFileMapMode TFileMode
| Parameters | |
|---|---|
| aName | The name of the file. Any path components (i.e. drive letter or directory), which are not specified, are taken from the session path. |
| aFileMode | The mode in which to open the file to be mapped. See TFileMode, only the sharing modes of TFileMode may be set. Setting any other TFileMode flags will cause this method to fail with KErrArgument. |
| aOffset | The offset in bytes from the start of the file where the mapping should start. aOffset must be page aligned otherwise this method will fail with KErrArgument. |
| aSize | The (non-zero) number of bytes of the file to map from aOffset. In practice, the actual size of a mapping is always a multiple page size. If aSize is not a multiple of page size, the size is rounded up to a whole number of pages. Any data beyond the end of the file is filled with zeros. The page size can be obtained by calling RFileMap::PageSizeInBytes(). |
| aMapMode | The mode of the file mapping. See TFileMapMode. |
| Capability | |
|---|---|
| Dependent | If the path for aName is /Sys and the file is opened for writing, i.e. aMapMode has EFileMapWrite set then Tcb capability is required. |
| Dependent | If the path for aName is /Sys and the file is opened for reading, i.e. aMapMode doesn't have EFileMapWrite set then Allfiles capability is required. |
| Dependent | If the path for aName begins with /Private and does not match this process' SID then AllFiles capability is required. |
| Dependent | If the path for aName begins with /Resource and the file is opened for writing, i.e. aMapMode has EFileMapWrite set then Tcb capability is required. |
| EFSRV_IMPORT_C TInt | Open | ( | RFile & | aFile, |
| TUint64 | aOffset, | |||
| TUint64 | aSize, | |||
| TUint | aMapMode, | |||
| TOwnerType | aType = EOwnerProcess | |||
| ) | ||||
Open and map a section of a file of the RFile. Once a file mapping has been opened closing the RFile object used to open the RFileMap will not close the RFileMap.
The sharing mode of aFile will be inherited by the RFileMap object being opened. The sharing mode of aFile will be enforced therefore if opening this RFileMap would violate the sharing mode then this method will fail returning KErrInUse.
Multiple mappings on the same file can exist provided the correct share mode is supplied. In the case where the mapped regions overlap, changes made in one mapped region will be visible in the others.
The read/write permissions of the RFileMap will be set by aMapMode and not inherited from aFile.
Opening this RFileMap will duplicate the RFs of aFile and use this duplicated RFs object. The duplicated RFs object will be closed automatically when the RFileMap object is closed.
The mapped region, defined by the combination of aOffset and aSize used, must fall completely within the file being mapped. For example, if aOffset is set to one page from the end of the file, then the maximum valid size of the mapped region will be the size of a single page. To map an entire file, aOffset must be set to zero and aSize to the size of the file.
When a file mapping is open, it will not be possible to change the size of the file in such a way that the mapped region no longer falls within the file. For example, if any file mapping exists on a file, a call to RFs::SetSize() which shrinks the file to the point that the new end point of the file falls within the mapped region will fail. It is possible to grow the file (and shrink it again by the same amount). Once the mapping(s) are closed, shrinking of the file will be possible again.
Restrictions exist on whether file mappings can be opened when file server plugins and extensions have already been mounted on a particular drive. These are:
If an open file mapping exists on a drive, a plugin which modifies file data or metadata will fail to mount on that drive (RFs::MountPlugin() will fail). In the case where KPluginAutoAttach is used to mount the plugin, the modifier plugin will mount on all applicable drives except ones with open file mappings. RFs::MountPlugin() will return KErrNone if the plugin succeeds in being mounted on any drive. Once the file mappings have been closed, it will be possible to mount the plugins again.
If a modifier plugin has been mounted on a drive (via KPluginAutoAttach or otherwise), a file mapping cannot be opened on that drive and the call to RFileMap::Open() will fail.
Observer plugins which do not change file data or metadata can coexist with file mappings.
If an open file mapping exists on a drive, file server extensions (modifier or not) cannot be mounted on that drive and the call to RFs::MountExtension() will fail.
If a modifier file server extension is mounted on a drive, a file mapping cannot be opened on that drive.
If an observer file extension is mounted on a drive, a file mapping can be opened on that drive.
This method will fail, returning KErrNotSupported, when used to open a file that is stored on a USB On-The-Go drive, e.g. a file stored on a USB memory stick or USB hard drive connected to the device.
See also: TFileMapMode
| Parameters | |
|---|---|
| aFile | The RFile of the file to memory map. |
| aOffset | The offset in bytes from the start of the file where the mapping should start. aOffset must be page aligned otherwise this method will fail with KErrArgument. |
| aSize | The (non-zero) number of bytes of the file to map from aOffset. In practice, the actual size of a mapping is always a multiple page size. If a aSize is not a multiple of page size, the size is rounded up to a whole number of pages. Any data beyond the end of the file is filled with zeros. The page size can be obtained by calling RFileMap::PageSizeInBytes(). |
| aMapMode | The mode of the file mapping. See TFileMapMode. |
| aType | The type of ownership this RFileMap and its associated RFs session will have. This defaults to EOwnerProcess |
| Panic Codes | |
|---|---|
| KERN-EXEC | 0, if aFile and its associated |
| EFSRV_IMPORT_C TInt | PageSizeInBytes | ( | ) |
Returns the size of a page in bytes. The size of a file mapping is always a multiple of the page size.