le_fs.h

1 /**
2  * @page c_fs File System service
3  *
4  * @subpage le_fs.h
5  *
6  * <HR>
7  *
8  * The File System (FS) service allows accessing the file system on different platforms:
9  * - providing a Read/Write space to create/store/read files.
10  * - on Read Only platforms, the /tmp/data/le_fs is used as base of the FS sevice.
11  *
12  * The File System service offers the following file operations:
13  * - open a file with le_fs_Open()
14  * - close a file with le_fs_Close()
15  * - read in a file with le_fs_Read()
16  * - write in a file with le_fs_Write()
17  * - change the current position in a file with le_fs_Seek()
18  * - get the size of a file with le_fs_GetSize()
19  * - delete a file with le_fs_Delete()
20  * - move a file with le_fs_Move()
21  * - recursively deletes a folder with le_fs_RemoveDirRecursive()
22  * - checks whether a regular file exists le_fs_Exists()
23  *
24  *
25  * <HR>
26  *
27  * Copyright (C) Sierra Wireless Inc.
28  */
29 
30 #ifndef LE_FS_H_INCLUDE_GUARD
31 #define LE_FS_H_INCLUDE_GUARD
32 
33 //--------------------------------------------------------------------------------------------------
34 /**
35  * Define the maximal bit mask for file access mode.
36  *
37  * @note This maximal value should be coherent with @ref le_fs_AccessMode_t
38  */
39 //--------------------------------------------------------------------------------------------------
40 #define LE_FS_ACCESS_MODE_MAX 127
41 
42 //--------------------------------------------------------------------------------------------------
43 /**
44  * File access modes used when opening a file.
45  */
46 //--------------------------------------------------------------------------------------------------
47 typedef int le_fs_AccessMode_t;
48 
49 #define LE_FS_RDONLY 0x1 ///< Read only
50 #define LE_FS_WRONLY 0x2 ///< Write only
51 #define LE_FS_RDWR 0x4 ///< Read/Write
52 #define LE_FS_CREAT 0x8 ///< Create a new file
53 #define LE_FS_TRUNC 0x10 ///< Truncate
54 #define LE_FS_APPEND 0x20 ///< Append
55 #define LE_FS_SYNC 0x40 ///< Synchronized
56 
57 //--------------------------------------------------------------------------------------------------
58 /**
59  * Offset position used when seeking in a file.
60  */
61 //--------------------------------------------------------------------------------------------------
62 typedef enum
63 {
64  LE_FS_SEEK_SET = 0, ///< From the current position
65  LE_FS_SEEK_CUR = 1, ///< From the beginning of the file
66  LE_FS_SEEK_END = 2 ///< From the end of the file
67 }
68 le_fs_Position_t;
69 
70 
71 //--------------------------------------------------------------------------------------------------
72 /**
73  * Reference of a file
74  */
75 //--------------------------------------------------------------------------------------------------
76 typedef struct le_fs_File* le_fs_FileRef_t;
77 
78 
79 //--------------------------------------------------------------------------------------------------
80 /**
81  * This function is called to create or open an existing file.
82  *
83  * @return
84  * - LE_OK The function succeeded.
85  * - LE_BAD_PARAMETER A parameter is invalid.
86  * - LE_OVERFLOW The file path is too long.
87  * - LE_NOT_FOUND The file does not exists or a directory in the path does not exist
88  * - LE_NOT_PERMITTED Access denied to the file or to a directory in the path
89  * - LE_UNSUPPORTED The prefix cannot be added and the function is unusable
90  * - LE_FAULT The function failed.
91  */
92 //--------------------------------------------------------------------------------------------------
94 (
95  const char* filePath, ///< [IN] File path
96  le_fs_AccessMode_t accessMode, ///< [IN] Access mode for the file
97  le_fs_FileRef_t* fileRefPtr ///< [OUT] File reference (if successful)
98 );
99 
100 //--------------------------------------------------------------------------------------------------
101 /**
102  * This function is called to close an opened file.
103  *
104  * @return
105  * - LE_OK The function succeeded.
106  * - LE_FAULT The function failed.
107  */
108 //--------------------------------------------------------------------------------------------------
109 LE_API_FILESYSTEM le_result_t le_fs_Close
110 (
111  le_fs_FileRef_t fileRef ///< [IN] File reference
112 );
113 
114 //--------------------------------------------------------------------------------------------------
115 /**
116  * This function is called to read the requested data length from an opened file.
117  * The data is read at the current file position.
118  *
119  * @return
120  * - LE_OK The function succeeded.
121  * - LE_BAD_PARAMETER A parameter is invalid.
122  * - LE_FAULT The function failed.
123  */
124 //--------------------------------------------------------------------------------------------------
126 (
127  le_fs_FileRef_t fileRef, ///< [IN] File reference
128  uint8_t* bufPtr, ///< [OUT] Buffer to store the data read in the file
129  size_t* bufSizePtr ///< [INOUT] Size to read and size really read on file
130 );
131 
132 //--------------------------------------------------------------------------------------------------
133 /**
134  * This function is called to write the requested data length to an opened file.
135  * The data is written at the current file position.
136  *
137  * @return
138  * - LE_OK The function succeeded.
139  * - LE_BAD_PARAMETER A parameter is invalid.
140  * - LE_UNDERFLOW The write succeed but was not able to write all bytes
141  * - LE_FAULT The function failed.
142  */
143 //--------------------------------------------------------------------------------------------------
144 LE_API_FILESYSTEM le_result_t le_fs_Write
145 (
146  le_fs_FileRef_t fileRef, ///< [IN] File reference
147  const uint8_t* bufPtr, ///< [IN] Buffer to write in the file
148  size_t bufSize ///< [IN] Size of the buffer to write
149 );
150 
151 //--------------------------------------------------------------------------------------------------
152 /**
153  * This function is called to change the file position of an opened file.
154  *
155  * @return
156  * - LE_OK The function succeeded.
157  * - LE_BAD_PARAMETER A parameter is invalid.
158  * - LE_FAULT The function failed.
159  */
160 //--------------------------------------------------------------------------------------------------
162 (
163  le_fs_FileRef_t fileRef, ///< [IN] File reference
164  int32_t offset, ///< [IN] Offset to apply
165  le_fs_Position_t position, ///< [IN] Offset is relative to this position
166  int32_t* currentOffsetPtr ///< [OUT] Offset from the beginning after the seek operation
167 );
168 
169 //--------------------------------------------------------------------------------------------------
170 /**
171  * This function is called to get the size of a file.
172  *
173  * @return
174  * - LE_OK The function succeeded.
175  * - LE_BAD_PARAMETER A parameter is invalid.
176  * - LE_OVERFLOW The file path is too long.
177  * - LE_UNSUPPORTED The prefix cannot be added and the function is unusable
178  * - LE_FAULT The function failed.
179  */
180 //--------------------------------------------------------------------------------------------------
181 LE_API_FILESYSTEM le_result_t le_fs_GetSize
182 (
183  const char* filePath, ///< [IN] File path
184  size_t* sizePtr ///< [OUT] File size (if successful)
185 );
186 
187 //--------------------------------------------------------------------------------------------------
188 /**
189  * This function is called to delete a file.
190  *
191  * @return
192  * - LE_OK The function succeeded.
193  * - LE_BAD_PARAMETER A parameter is invalid.
194  * - LE_OVERFLOW The file path is too long.
195  * - LE_NOT_FOUND The file does not exist or a directory in the path does not exist
196  * - LE_NOT_PERMITTED The access right fails to delete the file or access is not granted to a
197  * a directory in the path
198  * - LE_UNSUPPORTED The prefix cannot be added and the function is unusable
199  * - LE_FAULT The function failed.
200  */
201 //--------------------------------------------------------------------------------------------------
202 LE_API_FILESYSTEM le_result_t le_fs_Delete
203 (
204  const char* filePath ///< [IN] File path
205 );
206 
207 //--------------------------------------------------------------------------------------------------
208 /**
209  * This function is called to rename an existing file.
210  * If rename fails, the file will keep its original name.
211  *
212  * @return
213  * - LE_OK The function succeeded.
214  * - LE_BAD_PARAMETER A parameter is invalid.
215  * - LE_OVERFLOW A file path is too long.
216  * - LE_FAULT The function failed.
217  */
218 //--------------------------------------------------------------------------------------------------
220 (
221  const char* srcPath, ///< [IN] Path to file to rename
222  const char* destPath ///< [IN] New path to file
223 );
224 
225 //--------------------------------------------------------------------------------------------------
226 /**
227  * Removes a directory located at storage managed by file system service by first recursively
228  * removing sub-directories, files, symlinks, hardlinks, devices, etc. Symlinks are not followed,
229  * only the links themselves are deleted.
230  *
231  * A file or device may not be able to be removed if it is busy, in which case an error message
232  * is logged and LE_FAULT is returned.
233  *
234  * @return
235  * - LE_OK The function succeeded.
236  * - LE_BAD_PARAMETER A parameter is invalid.
237  * - LE_UNSUPPORTED The prefix cannot be added and the function is unusable
238  * - LE_FAULT There is an error.
239  */
240 //--------------------------------------------------------------------------------------------------
241 LE_API_FILESYSTEM le_result_t le_fs_RemoveDirRecursive
242 (
243  const char* dirPathPtr ///< [IN] Directory path
244 );
245 
246 //--------------------------------------------------------------------------------------------------
247 /**
248  * This function checks whether a regular file exists at the provided path under file system service
249  * storage.
250  *
251  * @return
252  * - true If file exists and it is a regular file.
253  * - false Otherwise.
254  */
255 //--------------------------------------------------------------------------------------------------
256 LE_API_FILESYSTEM bool le_fs_Exists
257 (
258  const char* filePathPtr ///< [IN] File path
259 );
260 
261 //--------------------------------------------------------------------------------------------------
262 /**
263  * Obtain the absolute directory containing the running executable and the name of the executable.
264  *
265  * @return LE_OK on success or an appropriate error on failure.
266  */
267 //--------------------------------------------------------------------------------------------------
268 LE_FULL_API LE_API_FILESYSTEM le_result_t le_fs_GetExecutablePath
269 (
270  char *dirPathPtr, ///< [OUT] Buffer to put executable's directory path in.
271  size_t dirPathSize, ///< [IN] Size of the directory path buffer.
272  char *exeNamePtr, ///< [OUT] Buffer to put the executable's name in.
273  size_t exeNameSize ///< [IN] Size of the executable name buffer.
274 );
275 
276 #endif // LE_FS_H_INCLUDE_GUARD
le_result_t
Definition: le_basics.h:46
#define LE_API_FILESYSTEM
API requires filesystem support.
Definition: le_apiFeatures.h:47
#define LE_FULL_API
Definition: le_apiFeatures.h:40