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