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 class _OSP_EXPORT_ MemoryMappedFile
  74         : public Tizen::Base::Object
  75 {
  76
  77 public:
  78         /**
  79         * 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.
  80         *
  81         * @since        2.0
  82         */
  83         MemoryMappedFile(void);
  84
  85         /**
  86         * This destructor overrides Tizen::Base::Object::~Object().
  87         *
  88         * @since        2.0
  89         */
  90         ~MemoryMappedFile(void);
  91
  92         /**
  93         * Initializes this instance of %MemoryMappedFile with a specified file.
  94         *
  95         * @since                2.0
  96         *
  97         * @return               An error code
  98         * @param[in]    file                            The File instance for memory mapping
  99         * @exception    E_SUCCESS                       The method is successful.
 100         * @exception    E_INVALID_ARG           The specified @c file is not opened for reading. @n
 101         *                                                                       The opening mode should not be "w" or "a".
 102         * @remarks              The specified @c file should be initialized by the Io::File::Construct() method.
 103         * @see                  Tizen::Io::File
 104         */
 105         result Construct(const File& file);
 106
 107         /**
 108         * Creates a new mapping for the specified file in the virtual address space of the calling process.
 109         *
 110         * @since                2.0
 111         *
 112         * @return               The mapped address space, @n
 113         *                               else @c null pointer if this method fails
 114         * @param[in]    address                                 A starting address of the mapping @n
 115         *                                                                               If the specified @c address is @c null, the system chooses the address.
 116         *                                                                               It should be a multiple of the page size.
 117         * @param[in]    length                                  The length of the mapping space
 118         * @param[in]    protection                              The memory protection of the mapping @n
 119         *                                                                               It is either Base::Runtime::MEMORY_PROTECTION_MODE_NONE or the bitwise-inclusive OR of one
 120         *                                                                               or more of the other modes in Base::Runtime::MemoryProtectionMode.
 121         * @param[in]    flag                                    The flag providing information about the handling of a memory mapped file @n
 122         *                                                                               It is the bitwise-inclusive OR of the flags in Tizen::Io::MemoryMappedFileFlag.
 123         * @param[in]    offset                                  The start offset of the specified file @n
 124         *                                                                               It should be a multiple of the page size.
 125         * @exception    E_SUCCESS                               The method is successful.
 126         * @exception    E_ILLEGAL_ACCESS                The specified @c flag is MEMORY_MAPPED_FILE_FLAG_SHARED and the specified @c
 127         *                                                                               protection is MEMORY_PROTECTION_MODE_WRITE, but the specified file of
 128         *                                                                               MemoryMappedFile::Construct() is not opened with read-write mode.
 129         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 130         *                                                                               - The specified @c address or @c offset is not aligned on a page boundary. @n
 131         *                                                                               - The specified @c length is not positive. @n
 132         *                                                                               - The specified @c protection, @c flag, or @c offset @ is invalid. @n
 133         *                                                                               - The specified @c flag cannot contain both MEMORY_MAPPED_FILE_FLAG_PRIVATE and
 134         *                                                                                 MEMORY_MAPPED_FILE_FLAG_SHARED.
 135         * @exception    E_MAX_EXCEEDED                  The number of mapped regions has exceeded the maximum limit.
 136         * @exception    E_OBJECT_LOCKED                 The mapped file has been locked.
 137         * @exception    E_OUT_OF_MEMORY                 Either of the following conditions has occurred: @n
 138         *                                                                               - The memory is insufficient. @n
 139         *                                                                               - The specified @c flag is MEMORY_MAPPED_FILE_FLAG_FIXED, and the specified address
 140         *                                                                                 range exceeds that allowed for the address space of a current process.
 141         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 142         *                                                                               - The underlying file system does not support memory mapping. @n
 143         *                                                                               - The specified @c protection is MEMORY_PROTECTION_MODE_EXEC, but the mapped file
 144         *                                                                                 exists on a file system that has been mounted no-exec.
 145         * @remarks              The specific error code can be accessed using the GetLastResult() method. @n
 146         *                               When this instance is destructed, all mappings are deleted automatically.
 147         * @see                  Tizen::Base::Runtime::MemoryManager
 148         */
 149         void* Map(void* address, long long length, unsigned long protection, unsigned long flag, long long offset);
 150
 151         /**
 152         * Deletes the mapping of the specified address space. @n
 153         * Further references to the addresses within the range result in generation of an invalid memory access. @n
 154         * This method flushes all changes of a shared mapping to the correlated file on the permanent storage.
 155         *
 156         * @since                2.0
 157         *
 158         * @return               An error code
 159         * @param[in]    address                         The memory mapping address to unmap
 160         * @param[in]    length                          The length of the mapping space
 161         * @exception    E_SUCCESS                       The method is successful.
 162         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 163         *                                                                       - The specified @c address is not aligned on a page boundary. @n
 164         *                                                                       - The specified @c length is not positive. @n
 165         *                                                                       - The specified address range is out of the valid address space of a current process.
 166         * @remarks              When this instance is destructed, all mappings of the instance are not unmapped automatically.
 167         */
 168         result Unmap(void* address, long long length);
 169
 170         /**
 171         * Flushes all changes of an address range to the correlated file on the permanent storage.
 172         *
 173         * @since                2.0
 174         *
 175         * @return               An error code
 176         * @param[in]    address                         The memory mapping address to synchronize
 177         * @param[in]    length                          The length of the mapping space
 178         * @param[in]    syncFlag                        The synchronization option
 179         * @exception    E_SUCCESS                       The method is successful.
 180         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 181         *                                                                       - The specified @c address is not aligned on a page boundary. @n
 182         *                                                                       - The specified @c length is not positive. @n
 183         *                                                                       - The specified @c syncFlag is invalid. @n
 184         *                                                                       - The specified @c address space is not mapped.
 185         * @exception    E_IO                            Either of the following conditions has occurred: @n
 186         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 187         *                                                                       - %File corruption is detected.
 188         * @remarks              The specific page size of a current file system is provided by Tizen::System::SystemInfo class with
 189         *                               "StorageInfo" key.
 190         * @see                  Tizen::Io::MemoryMappedFileSyncFlag
 191     * @see              Tizen::System::SystemInfo
 192         */
 193         result Sync(void* address, long long length, MemoryMappedFileSyncFlag syncFlag);
 194
 195 private:
 196         /**
 197         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 198         *
 199         * @since        2.0
 200         */
 201         MemoryMappedFile(const MemoryMappedFile& rhs);
 202
 203         /**
 204         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 205         *
 206         * @since        2.0
 207         */
 208         MemoryMappedFile& operator =(const MemoryMappedFile& rhs);
 209
 210         class _MemoryMappedFileImpl* __pMemoryMappedFileImpl;
 211
 212         friend class _MemoryMappedFileImpl;
 213
 214 }; // MemoryMappedFile
 215
 216 }} // Tizen::Io
 217
 218 #endif // _FIO_MEMORY_MAPPED_FILE_H_
 219