    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 //--------------------------------------------------------------------------------------------------
   93 LE_API_FILESYSTEM le_result_t le_fs_Open
   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 //--------------------------------------------------------------------------------------------------
  125 LE_API_FILESYSTEM le_result_t le_fs_Read
  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 //--------------------------------------------------------------------------------------------------
  161 LE_API_FILESYSTEM le_result_t le_fs_Seek
  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 //--------------------------------------------------------------------------------------------------
  219 LE_API_FILESYSTEM le_result_t le_fs_Move
  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
le_result_t
Definition: le_basics.h:46
LE_API_FILESYSTEM
#define LE_API_FILESYSTEM
API requires filesystem support. 
Definition: le_apiFeatures.h:47
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40