le_fs.h

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