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  *
   22  *
   23  * <HR>
   24  *
   25  * Copyright (C) Sierra Wireless Inc.
   26  */
   27 
   28 #ifndef LE_FS_H_INCLUDE_GUARD
   29 #define LE_FS_H_INCLUDE_GUARD
   30 
   31 //--------------------------------------------------------------------------------------------------
   32 /**
   33  * Define the maximal bit mask for file access mode.
   34  *
   35  * @note This maximal value should be coherent with @ref le_fs_AccessMode_t
   36  */
   37 //--------------------------------------------------------------------------------------------------
   38 #define LE_FS_ACCESS_MODE_MAX 127
   39 
   40 //--------------------------------------------------------------------------------------------------
   41 /**
   42  * Maximum number of characters permitted for a file path.
   43  */
   44 //--------------------------------------------------------------------------------------------------
   45 #define LE_FS_PATH_MAX_LEN    PATH_MAX
   46 
   47 //--------------------------------------------------------------------------------------------------
   48 /**
   49  * File access modes used when opening a file.
   50  */
   51 //--------------------------------------------------------------------------------------------------
   52 typedef enum
   53 {
   54     LE_FS_RDONLY = 0x1,        ///< Read only
   55     LE_FS_WRONLY = 0x2,        ///< Write only
   56     LE_FS_RDWR   = 0x4,        ///< Read/Write
   57     LE_FS_CREAT  = 0x8,        ///< Create a new file
   58     LE_FS_TRUNC  = 0x10,       ///< Truncate
   59     LE_FS_APPEND = 0x20,       ///< Append
   60     LE_FS_SYNC   = 0x40        ///< Synchronized
   61 }
   62 le_fs_AccessMode_t;
   63 
   64 
   65 //--------------------------------------------------------------------------------------------------
   66 /**
   67  * Offset position used when seeking in a file.
   68  */
   69 //--------------------------------------------------------------------------------------------------
   70 typedef enum
   71 {
   72     LE_FS_SEEK_SET = 0, ///< From the current position
   73     LE_FS_SEEK_CUR = 1, ///< From the beginning of the file
   74     LE_FS_SEEK_END = 2  ///< From the end of the file
   75 }
   76 le_fs_Position_t;
   77 
   78 
   79 //--------------------------------------------------------------------------------------------------
   80 /**
   81  * Reference of a file
   82  */
   83 //--------------------------------------------------------------------------------------------------
   84 typedef struct le_fs_File* le_fs_FileRef_t;
   85 
   86 
   87 //--------------------------------------------------------------------------------------------------
   88 /**
   89  * This function is called to create or open an existing file.
   90  *
   91  * @return
   92  *  - LE_OK             The function succeeded.
   93  *  - LE_BAD_PARAMETER  A parameter is invalid.
   94  *  - LE_OVERFLOW       The file path is too long.
   95  *  - LE_NOT_FOUND      The file does not exists or a directory in the path does not exist
   96  *  - LE_NOT_PERMITTED  Access denied to the file or to a directory in the path
   97  *  - LE_UNSUPPORTED    The prefix cannot be added and the function is unusable
   98  *  - LE_FAULT          The function failed.
   99  */
  100 //--------------------------------------------------------------------------------------------------
  101 le_result_t le_fs_Open
  102 (
  103     const char* filePath,          ///< [IN] File path
  104     le_fs_AccessMode_t accessMode, ///< [IN] Access mode for the file
  105     le_fs_FileRef_t* fileRefPtr    ///< [OUT] File reference (if successful)
  106 );
  107 
  108 //--------------------------------------------------------------------------------------------------
  109 /**
  110  * This function is called to close an opened file.
  111  *
  112  * @return
  113  *  - LE_OK         The function succeeded.
  114  *  - LE_FAULT      The function failed.
  115  */
  116 //--------------------------------------------------------------------------------------------------
  117 le_result_t le_fs_Close
  118 (
  119     le_fs_FileRef_t fileRef ///< [IN] File reference
  120 );
  121 
  122 //--------------------------------------------------------------------------------------------------
  123 /**
  124  * This function is called to read the requested data length from an opened file.
  125  * The data is read at the current file position.
  126  *
  127  * @return
  128  *  - LE_OK             The function succeeded.
  129  *  - LE_BAD_PARAMETER  A parameter is invalid.
  130  *  - LE_FAULT          The function failed.
  131  */
  132 //--------------------------------------------------------------------------------------------------
  133 le_result_t le_fs_Read
  134 (
  135     le_fs_FileRef_t fileRef, ///< [IN] File reference
  136     uint8_t* bufPtr,         ///< [OUT] Buffer to store the data read in the file
  137     size_t* bufSizePtr       ///< [INOUT] Size to read and size really read on file
  138 );
  139 
  140 //--------------------------------------------------------------------------------------------------
  141 /**
  142  * This function is called to write the requested data length to an opened file.
  143  * The data is written at the current file position.
  144  *
  145  * @return
  146  *  - LE_OK             The function succeeded.
  147  *  - LE_BAD_PARAMETER  A parameter is invalid.
  148  *  - LE_UNDERFLOW      The write succeed but was not able to write all bytes
  149  *  - LE_FAULT          The function failed.
  150  */
  151 //--------------------------------------------------------------------------------------------------
  152 le_result_t le_fs_Write
  153 (
  154     le_fs_FileRef_t fileRef, ///< [IN] File reference
  155     const uint8_t* bufPtr,   ///< [IN] Buffer to write in the file
  156     size_t bufSize           ///< [IN] Size of the buffer to write
  157 );
  158 
  159 //--------------------------------------------------------------------------------------------------
  160 /**
  161  * This function is called to change the file position of an opened file.
  162  *
  163  * @return
  164  *  - LE_OK             The function succeeded.
  165  *  - LE_BAD_PARAMETER  A parameter is invalid.
  166  *  - LE_FAULT          The function failed.
  167  */
  168 //--------------------------------------------------------------------------------------------------
  169 le_result_t le_fs_Seek
  170 (
  171     le_fs_FileRef_t fileRef,   ///< [IN] File reference
  172     int32_t offset,            ///< [IN] Offset to apply
  173     le_fs_Position_t position, ///< [IN] Offset is relative to this position
  174     int32_t* currentOffsetPtr  ///< [OUT] Offset from the beginning after the seek operation
  175 );
  176 
  177 //--------------------------------------------------------------------------------------------------
  178 /**
  179  * This function is called to get the size of a file.
  180  *
  181  * @return
  182  *  - LE_OK             The function succeeded.
  183  *  - LE_BAD_PARAMETER  A parameter is invalid.
  184  *  - LE_OVERFLOW       The file path is too long.
  185  *  - LE_UNSUPPORTED    The prefix cannot be added and the function is unusable
  186  *  - LE_FAULT          The function failed.
  187  */
  188 //--------------------------------------------------------------------------------------------------
  189 le_result_t le_fs_GetSize
  190 (
  191     const char* filePath, ///< [IN] File path
  192     size_t* sizePtr       ///< [OUT] File size (if successful)
  193 );
  194 
  195 //--------------------------------------------------------------------------------------------------
  196 /**
  197  * This function is called to delete a file.
  198  *
  199  * @return
  200  *  - LE_OK             The function succeeded.
  201  *  - LE_BAD_PARAMETER  A parameter is invalid.
  202  *  - LE_OVERFLOW       The file path is too long.
  203  *  - LE_NOT_FOUND      The file does not exist or a directory in the path does not exist
  204  *  - LE_NOT_PERMITTED  The access right fails to delete the file or access is not granted to a
  205  *                      a directory in the path
  206  *  - LE_UNSUPPORTED    The prefix cannot be added and the function is unusable
  207  *  - LE_FAULT          The function failed.
  208  */
  209 //--------------------------------------------------------------------------------------------------
  210 le_result_t le_fs_Delete
  211 (
  212     const char* filePath ///< [IN] File path
  213 );
  214 
  215 //--------------------------------------------------------------------------------------------------
  216 /**
  217  * This function is called to rename an existing file.
  218  * If rename fails, the file will keep its original name.
  219  *
  220  * @return
  221  *  - LE_OK             The function succeeded.
  222  *  - LE_BAD_PARAMETER  A parameter is invalid.
  223  *  - LE_OVERFLOW       A file path is too long.
  224  *  - LE_FAULT          The function failed.
  225  */
  226 //--------------------------------------------------------------------------------------------------
  227 le_result_t le_fs_Move
  228 (
  229     const char* srcPath, ///< [IN] Path to file to rename
  230     const char* destPath ///< [IN] New path to file
  231 );
  232 
  233 #endif // LE_FS_H_INCLUDE_GUARD
le_result_t
le_result_t
Definition: le_basics.h:35