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
le_result_t
Definition: le_basics.h:35