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 enum
48 {
49  LE_FS_RDONLY = 0x1, ///< Read only
50  LE_FS_WRONLY = 0x2, ///< Write only
51  LE_FS_RDWR = 0x4, ///< Read/Write
52  LE_FS_CREAT = 0x8, ///< Create a new file
53  LE_FS_TRUNC = 0x10, ///< Truncate
54  LE_FS_APPEND = 0x20, ///< Append
55  LE_FS_SYNC = 0x40 ///< Synchronized
56 }
57 le_fs_AccessMode_t;
58 
59 
60 //--------------------------------------------------------------------------------------------------
61 /**
62  * Offset position used when seeking in a file.
63  */
64 //--------------------------------------------------------------------------------------------------
65 typedef enum
66 {
67  LE_FS_SEEK_SET = 0, ///< From the current position
68  LE_FS_SEEK_CUR = 1, ///< From the beginning of the file
69  LE_FS_SEEK_END = 2 ///< From the end of the file
70 }
71 le_fs_Position_t;
72 
73 
74 //--------------------------------------------------------------------------------------------------
75 /**
76  * Reference of a file
77  */
78 //--------------------------------------------------------------------------------------------------
79 typedef struct le_fs_File* le_fs_FileRef_t;
80 
81 
82 //--------------------------------------------------------------------------------------------------
83 /**
84  * This function is called to create or open an existing file.
85  *
86  * @return
87  * - LE_OK The function succeeded.
88  * - LE_BAD_PARAMETER A parameter is invalid.
89  * - LE_OVERFLOW The file path is too long.
90  * - LE_NOT_FOUND The file does not exists or a directory in the path does not exist
91  * - LE_NOT_PERMITTED Access denied to the file or to a directory in the path
92  * - LE_UNSUPPORTED The prefix cannot be added and the function is unusable
93  * - LE_FAULT The function failed.
94  */
95 //--------------------------------------------------------------------------------------------------
96 le_result_t le_fs_Open
97 (
98  const char* filePath, ///< [IN] File path
99  le_fs_AccessMode_t accessMode, ///< [IN] Access mode for the file
100  le_fs_FileRef_t* fileRefPtr ///< [OUT] File reference (if successful)
101 );
102 
103 //--------------------------------------------------------------------------------------------------
104 /**
105  * This function is called to close an opened file.
106  *
107  * @return
108  * - LE_OK The function succeeded.
109  * - LE_FAULT The function failed.
110  */
111 //--------------------------------------------------------------------------------------------------
112 le_result_t le_fs_Close
113 (
114  le_fs_FileRef_t fileRef ///< [IN] File reference
115 );
116 
117 //--------------------------------------------------------------------------------------------------
118 /**
119  * This function is called to read the requested data length from an opened file.
120  * The data is read at the current file position.
121  *
122  * @return
123  * - LE_OK The function succeeded.
124  * - LE_BAD_PARAMETER A parameter is invalid.
125  * - LE_FAULT The function failed.
126  */
127 //--------------------------------------------------------------------------------------------------
128 le_result_t le_fs_Read
129 (
130  le_fs_FileRef_t fileRef, ///< [IN] File reference
131  uint8_t* bufPtr, ///< [OUT] Buffer to store the data read in the file
132  size_t* bufSizePtr ///< [INOUT] Size to read and size really read on file
133 );
134 
135 //--------------------------------------------------------------------------------------------------
136 /**
137  * This function is called to write the requested data length to an opened file.
138  * The data is written at the current file position.
139  *
140  * @return
141  * - LE_OK The function succeeded.
142  * - LE_BAD_PARAMETER A parameter is invalid.
143  * - LE_UNDERFLOW The write succeed but was not able to write all bytes
144  * - LE_FAULT The function failed.
145  */
146 //--------------------------------------------------------------------------------------------------
147 le_result_t le_fs_Write
148 (
149  le_fs_FileRef_t fileRef, ///< [IN] File reference
150  const uint8_t* bufPtr, ///< [IN] Buffer to write in the file
151  size_t bufSize ///< [IN] Size of the buffer to write
152 );
153 
154 //--------------------------------------------------------------------------------------------------
155 /**
156  * This function is called to change the file position of an opened file.
157  *
158  * @return
159  * - LE_OK The function succeeded.
160  * - LE_BAD_PARAMETER A parameter is invalid.
161  * - LE_FAULT The function failed.
162  */
163 //--------------------------------------------------------------------------------------------------
164 le_result_t le_fs_Seek
165 (
166  le_fs_FileRef_t fileRef, ///< [IN] File reference
167  int32_t offset, ///< [IN] Offset to apply
168  le_fs_Position_t position, ///< [IN] Offset is relative to this position
169  int32_t* currentOffsetPtr ///< [OUT] Offset from the beginning after the seek operation
170 );
171 
172 //--------------------------------------------------------------------------------------------------
173 /**
174  * This function is called to get the size of a file.
175  *
176  * @return
177  * - LE_OK The function succeeded.
178  * - LE_BAD_PARAMETER A parameter is invalid.
179  * - LE_OVERFLOW The file path is too long.
180  * - LE_UNSUPPORTED The prefix cannot be added and the function is unusable
181  * - LE_FAULT The function failed.
182  */
183 //--------------------------------------------------------------------------------------------------
184 le_result_t le_fs_GetSize
185 (
186  const char* filePath, ///< [IN] File path
187  size_t* sizePtr ///< [OUT] File size (if successful)
188 );
189 
190 //--------------------------------------------------------------------------------------------------
191 /**
192  * This function is called to delete a file.
193  *
194  * @return
195  * - LE_OK The function succeeded.
196  * - LE_BAD_PARAMETER A parameter is invalid.
197  * - LE_OVERFLOW The file path is too long.
198  * - LE_NOT_FOUND The file does not exist or a directory in the path does not exist
199  * - LE_NOT_PERMITTED The access right fails to delete the file or access is not granted to a
200  * a directory in the path
201  * - LE_UNSUPPORTED The prefix cannot be added and the function is unusable
202  * - LE_FAULT The function failed.
203  */
204 //--------------------------------------------------------------------------------------------------
205 le_result_t le_fs_Delete
206 (
207  const char* filePath ///< [IN] File path
208 );
209 
210 //--------------------------------------------------------------------------------------------------
211 /**
212  * This function is called to rename an existing file.
213  * If rename fails, the file will keep its original name.
214  *
215  * @return
216  * - LE_OK The function succeeded.
217  * - LE_BAD_PARAMETER A parameter is invalid.
218  * - LE_OVERFLOW A file path is too long.
219  * - LE_FAULT The function failed.
220  */
221 //--------------------------------------------------------------------------------------------------
222 le_result_t le_fs_Move
223 (
224  const char* srcPath, ///< [IN] Path to file to rename
225  const char* destPath ///< [IN] New path to file
226 );
227 
228 //--------------------------------------------------------------------------------------------------
229 /**
230  * Removes a directory located at storage managed by file system service by first recursively
231  * removing sub-directories, files, symlinks, hardlinks, devices, etc. Symlinks are not followed,
232  * only the links themselves are deleted.
233  *
234  * A file or device may not be able to be removed if it is busy, in which case an error message
235  * is logged and LE_FAULT is returned.
236  *
237  * @return
238  * - LE_OK The function succeeded.
239  * - LE_BAD_PARAMETER A parameter is invalid.
240  * - LE_UNSUPPORTED The prefix cannot be added and the function is unusable
241  * - LE_FAULT There is an error.
242  */
243 //--------------------------------------------------------------------------------------------------
244 le_result_t le_fs_RemoveDirRecursive
245 (
246  const char* dirPathPtr ///< [IN] Directory path
247 );
248 
249 //--------------------------------------------------------------------------------------------------
250 /**
251  * This function checks whether a regular file exists at the provided path under file system service
252  * storage.
253  *
254  * @return
255  * - true If file exists and it is a regular file.
256  * - false Otherwise.
257  */
258 //--------------------------------------------------------------------------------------------------
259 bool le_fs_Exists
260 (
261  const char* filePathPtr ///< [IN] File path
262 );
263 
264 #endif // LE_FS_H_INCLUDE_GUARD
le_result_t
Definition: le_basics.h:35