inc/FIoMemoryMappedFile.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FIoMemoryMappedFile.h
  20  * @brief       This is the header file for the %MemoryMappedFile class.
  21  *
  22  * This header file contains the declarations of the %MemoryMappedFile class.
  23  */
  24
  25 #ifndef _FIO_MEMORY_MAPPED_FILE_H_
  26 #define _FIO_MEMORY_MAPPED_FILE_H_
  27
  28 #include <FOspConfig.h>
  29 #include <FBaseObject.h>
  30
  31 namespace Tizen { namespace Io
  32 {
  33
  34 /**
  35  * @enum        MemoryMappedFileFlag
  36  *
  37  * Defines flags providing information about the handling of a memory mapped file.
  38  *
  39  * @since       2.0
  40  */
  41 enum MemoryMappedFileFlag
  42 {
  43         MEMORY_MAPPED_FILE_FLAG_SHARED = 0x01,  /**< Changes are shared with other processes mapping the same file */
  44         MEMORY_MAPPED_FILE_FLAG_PRIVATE = 0x02, /**< Changes are not visible to other processes mapping the same file */
  45         MEMORY_MAPPED_FILE_FLAG_FIXED = 0x10    /**< This forces the system to use the specified mapping address exactly,
  46                                                                                           which should be a multiple of the page size */
  47 };
  48
  49 /**
  50  * @enum        MemoryMappedFileSyncFlag
  51  *
  52  * Defines synchronization flags of a memory mapped file.
  53  *
  54  * @since       2.0
  55  */
  56 enum MemoryMappedFileSyncFlag
  57 {
  58         MEMORY_MAPPED_FILE_SYNC_FLAG_ASYNC = 0x01,              /**< Asynchronous update */
  59         MEMORY_MAPPED_FILE_SYNC_FLAG_SYNC = 0x02                /**< Synchronous update */
  60 };
  61
  62 /**
  63  * @class       MemoryMappedFile
  64  * @brief       This class provides features mapping a file to virtual address space.
  65  *
  66  * @since       2.0
  67  *
  68  * @final       This class is not intended for extension.
  69  *
  70  * The %MemoryMappedFile class provides features for using a memory mapped file,
  71  * which maps the data of a file to an application's virtual address space.
  72  *
  73  * @code
  74  *
  75  * #include <FBase.h>
  76  * #include <FIo.h>
  77  * #include <FApp.h>
  78  *
  79  * using namespace Tizen::Base;
  80  * using namespace Tizen::Base::Collection;
  81  * using namespace Tizen::Io;
  82  * using namespace Tizen::App;
  83  *
  84  * result
  85  * MyApp::Execute(void)
  86  * {
  87  *      String filePath(App::GetInstance()->GetAppDataPath() + L”myFile.txt”);
  88  *      file.Construct(filePath, “w+);
  89  *
  90  *      String testMsg(L”MemoryMappedFileTest”);
  91  *      file.Write(testMsg);
  92  *      file.Flush();
  93  *
  94  *      long long mapLength = 4096;
  95  *      MemoryMappedFile mapFile;
  96  *      mapFile.Construct(file);
  97  *      void* pMappedAddr = mapFile.Map(null, mapLength, MEMORY_PROTECTION_MODE_READ | MEMORY_PROTECTION_MODE_WRITE, MEMORY_MAPPED_FILE_FLAG_SHARED, 0);
  98  *
  99  *      char* pBuffer = new char[testMsg.GetLength() + 1];
 100  *      memcpy(pBuffer, pMappedAddr, testMsg.GetLength());
 101  *
 102  * }
 103  *
 104  * @endcode
 105  */
 106 class _OSP_EXPORT_ MemoryMappedFile
 107         : public Tizen::Base::Object
 108 {
 109
 110 public:
 111         /**
 112         * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 113         *
 114         * @since        2.0
 115         */
 116         MemoryMappedFile(void);
 117
 118         /**
 119         * This destructor overrides Tizen::Base::Object::~Object().
 120         *
 121         * @since        2.0
 122         */
 123         ~MemoryMappedFile(void);
 124
 125         /**
 126         * Initializes this instance of %MemoryMappedFile with a specified file.
 127         *
 128         * @since                2.0
 129         *
 130         * @return               An error code
 131         * @param[in]    file                            The File instance for memory mapping
 132         * @exception    E_SUCCESS                       The method is successful.
 133         * @exception    E_INVALID_ARG           The specified @c file is not opened for reading. @n
 134         *                                                                       The opening mode should not be "w" or "a".
 135         * @remarks              The specified @c file should be initialized by the Io::File::Construct() method.
 136         * @see                  Tizen::Io::File
 137         */
 138         result Construct(const File& file);
 139
 140         /**
 141         * Creates a new mapping for the specified file in the virtual address space of the calling process.
 142         *
 143         * @since                2.0
 144         *
 145         * @return               The mapped address space, @n
 146         *                               else @c null pointer if this method fails
 147         * @param[in]    address                                 A starting address of the mapping @n
 148         *                                                                               If the specified @c address is @c null, the system chooses the address.
 149         *                                                                               It should be a multiple of the page size.
 150         * @param[in]    length                                  The length of the mapping space
 151         * @param[in]    protection                              The memory protection of the mapping @n
 152         *                                                                               It is either Base::Runtime::MEMORY_PROTECTION_MODE_NONE or the bitwise-inclusive OR of one
 153         *                                                                               or more of the other modes in Base::Runtime::MemoryProtectionMode.
 154         * @param[in]    flag                                    The flag providing information about the handling of a memory mapped file @n
 155         *                                                                               It is the bitwise-inclusive OR of the flags in Tizen::Io::MemoryMappedFileFlag.
 156         * @param[in]    offset                                  The start offset of the specified file @n
 157         *                                                                               It should be a multiple of the page size.
 158         * @exception    E_SUCCESS                               The method is successful.
 159         * @exception    E_ILLEGAL_ACCESS                The specified @c flag is MEMORY_MAPPED_FILE_FLAG_SHARED and the specified @c
 160         *                                                                               protection is MEMORY_PROTECTION_MODE_WRITE, but the specified file of
 161         *                                                                               MemoryMappedFile::Construct() is not opened with read-write mode.
 162         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 163         *                                                                               - The specified @c address or @c offset is not aligned on a page boundary. @n
 164         *                                                                               - The specified @c length is not positive. @n
 165         *                                                                               - The specified @c protection, @c flag, or @c offset @ is invalid. @n
 166         *                                                                               - The specified @c flag cannot contain both MEMORY_MAPPED_FILE_FLAG_PRIVATE and
 167         *                                                                                 MEMORY_MAPPED_FILE_FLAG_SHARED.
 168         * @exception    E_MAX_EXCEEDED                  The number of mapped regions has exceeded the maximum limit.
 169         * @exception    E_OBJECT_LOCKED                 The mapped file has been locked.
 170         * @exception    E_OUT_OF_MEMORY                 Either of the following conditions has occurred: @n
 171         *                                                                               - The memory is insufficient. @n
 172         *                                                                               - The specified @c flag is MEMORY_MAPPED_FILE_FLAG_FIXED, and the specified address
 173         *                                                                                 range exceeds that allowed for the address space of a current process.
 174         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 175         *                                                                               - The underlying file system does not support memory mapping. @n
 176         *                                                                               - The specified @c protection is MEMORY_PROTECTION_MODE_EXEC, but the mapped file
 177         *                                                                                 exists on a file system that has been mounted no-exec.
 178         * @remarks              The specific error code can be accessed using the GetLastResult() method. @n
 179         *                               When this instance is destructed, all mappings are deleted automatically.
 180         * @see                  Tizen::Base::Runtime::MemoryManager
 181         */
 182         void* Map(void* address, long long length, unsigned long protection, unsigned long flag, long long offset);
 183
 184         /**
 185         * Deletes the mapping of the specified address space. @n
 186         * Further references to the addresses within the range result in generation of an invalid memory access. @n
 187         * This method flushes all changes of a shared mapping to the correlated file on the permanent storage.
 188         *
 189         * @since                2.0
 190         *
 191         * @return               An error code
 192         * @param[in]    address                         The memory mapping address to unmap
 193         * @param[in]    length                          The length of the mapping space
 194         * @exception    E_SUCCESS                       The method is successful.
 195         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 196         *                                                                       - The specified @c address is not aligned on a page boundary. @n
 197         *                                                                       - The specified @c length is not positive. @n
 198         *                                                                       - The specified address range is out of the valid address space of a current process.
 199         * @remarks              When this instance is destructed, all mappings of the instance are not unmapped automatically.
 200         */
 201         result Unmap(void* address, long long length);
 202
 203         /**
 204         * Flushes all changes of an address range to the correlated file on the permanent storage.
 205         *
 206         * @since                2.0
 207         *
 208         * @return               An error code
 209         * @param[in]    address                         The memory mapping address to synchronize
 210         * @param[in]    length                          The length of the mapping space
 211         * @param[in]    syncFlag                        The synchronization option
 212         * @exception    E_SUCCESS                       The method is successful.
 213         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 214         *                                                                       - The specified @c address is not aligned on a page boundary. @n
 215         *                                                                       - The specified @c length is not positive. @n
 216         *                                                                       - The specified @c syncFlag is invalid. @n
 217         *                                                                       - The specified @c address space is not mapped.
 218         * @exception    E_IO                            Either of the following conditions has occurred: @n
 219         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 220         *                                                                       - %File corruption is detected.
 221         * @remarks              The specific page size of a current file system is provided by Tizen::System::SystemInfo class with
 222         *                               "StorageInfo" key.
 223         * @see                  Tizen::Io::MemoryMappedFileSyncFlag
 224     * @see              Tizen::System::SystemInfo
 225         */
 226         result Sync(void* address, long long length, MemoryMappedFileSyncFlag syncFlag);
 227
 228 private:
 229         /**
 230         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 231         *
 232         * @since        2.0
 233         */
 234         MemoryMappedFile(const MemoryMappedFile& rhs);
 235
 236         /**
 237         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 238         *
 239         * @since        2.0
 240         */
 241         MemoryMappedFile& operator =(const MemoryMappedFile& rhs);
 242
 243         class _MemoryMappedFileImpl* __pMemoryMappedFileImpl;
 244
 245         friend class _MemoryMappedFileImpl;
 246
 247 }; // MemoryMappedFile
 248
 249 }} // Tizen::Io
 250
 251 #endif // _FIO_MEMORY_MAPPED_FILE_H_
 252