le_fs_interface.h

Go to the documentation of this file.
    1 /*
    2  * ====================== WARNING ======================
    3  *
    4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    5  * DO NOT MODIFY IN ANY WAY.
    6  *
    7  * ====================== WARNING ======================
    8  */
    9 
   10 /**
   11  * @page c_fs File System service
   12  *
   13  * @ref le_fs_interface.h "API Reference"
   14  *
   15  * <HR>
   16  *
   17  * The File System (FS) service allows accessing the file system on different platforms:
   18  * - providing a Read/Write space to create/store/read files.
   19  * - on Read Only platforms, the /tmp/data/le_fs is used as base of the FS sevice.
   20  *
   21  * The File System service offers the following file operations:
   22  * - open a file with le_fs_Open()
   23  * - close a file with le_fs_Close()
   24  * - read in a file with le_fs_Read()
   25  * - write in a file with le_fs_Write()
   26  * - change the current position in a file with le_fs_Seek()
   27  * - get the size of a file with le_fs_GetSize()
   28  * - delete a file with le_fs_Delete()
   29  * - move a file with le_fs_Move()
   30  *
   31  * The files and directories tree used by the fsDaemon may be set by the user with the config
   32  * tree variable fsService:/fsPrefixPath.
   33  * If it is not set, the path /data/le_fs is used if writeable. Else, it uses /tmp/data/le_fs.
   34  *
   35  * @section le_fs_binding IPC interfaces binding
   36  *
   37  * All the functions of this API are provided by the @b fsService application service.
   38  *
   39  * Here's a code sample binding to File System service:
   40  * @verbatim
   41    bindings:
   42    {
   43       clientExe.clientComponent.le_fs -> fsService.le_fs
   44    }
   45    @endverbatim
   46  *
   47  * <HR>
   48  *
   49  * Copyright (C) Sierra Wireless Inc.
   50  */
   51 /**
   52  * @file le_fs_interface.h
   53  *
   54  * Legato @ref c_fs API.
   55  *
   56  * <HR>
   57  *
   58  * Copyright (C) Sierra Wireless Inc.
   59  */
   60 
   61 #ifndef LE_FS_INTERFACE_H_INCLUDE_GUARD
   62 #define LE_FS_INTERFACE_H_INCLUDE_GUARD
   63 
   64 
   65 #include "legato.h"
   66 
   67 //--------------------------------------------------------------------------------------------------
   68 /**
   69  *
   70  * Connect the current client thread to the service providing this API. Block until the service is
   71  * available.
   72  *
   73  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   74  * called before any other functions in this API.  Normally, ConnectService is automatically called
   75  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   76  *
   77  * This function is created automatically.
   78  */
   79 //--------------------------------------------------------------------------------------------------
   80 void le_fs_ConnectService
   81 (
   82     void
   83 );
   84 
   85 //--------------------------------------------------------------------------------------------------
   86 /**
   87  *
   88  * Try to connect the current client thread to the service providing this API. Return with an error
   89  * if the service is not available.
   90  *
   91  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   92  * called before any other functions in this API.  Normally, ConnectService is automatically called
   93  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   94  *
   95  * This function is created automatically.
   96  *
   97  * @return
   98  *  - LE_OK if the client connected successfully to the service.
   99  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  100  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  101  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  102  */
  103 //--------------------------------------------------------------------------------------------------
  104 le_result_t le_fs_TryConnectService
  105 (
  106     void
  107 );
  108 
  109 //--------------------------------------------------------------------------------------------------
  110 /**
  111  *
  112  * Disconnect the current client thread from the service providing this API.
  113  *
  114  * Normally, this function doesn't need to be called. After this function is called, there's no
  115  * longer a connection to the service, and the functions in this API can't be used. For details, see
  116  * @ref apiFilesC_client.
  117  *
  118  * This function is created automatically.
  119  */
  120 //--------------------------------------------------------------------------------------------------
  121 void le_fs_DisconnectService
  122 (
  123     void
  124 );
  125 
  126 
  127 //--------------------------------------------------------------------------------------------------
  128 /**
  129  * File access modes used when opening a file.
  130  */
  131 //--------------------------------------------------------------------------------------------------
  132 typedef enum
  133 {
  134     LE_FS_RDONLY = 0x1,
  135         ///< Read only
  136 
  137     LE_FS_WRONLY = 0x2,
  138         ///< Write only
  139 
  140     LE_FS_RDWR = 0x4,
  141         ///< Read/Write
  142 
  143     LE_FS_CREAT = 0x8,
  144         ///< Create a new file
  145 
  146     LE_FS_TRUNC = 0x10,
  147         ///< Truncate
  148 
  149     LE_FS_APPEND = 0x20,
  150         ///< Append
  151 
  152     LE_FS_SYNC = 0x40
  153         ///< Synchronized
  154 }
  155 le_fs_AccessMode_t;
  156 
  157 
  158 //--------------------------------------------------------------------------------------------------
  159 /**
  160  * Define the maximal bit mask for file access mode.
  161  *
  162  * @note This maximal value should be coherent with @ref le_fs_AccessMode_t
  163  */
  164 //--------------------------------------------------------------------------------------------------
  165 #define LE_FS_ACCESS_MODE_MAX 127
  166 
  167 
  168 //--------------------------------------------------------------------------------------------------
  169 /**
  170  * Offset position used when seeking in a file.
  171  */
  172 //--------------------------------------------------------------------------------------------------
  173 typedef enum
  174 {
  175     LE_FS_SEEK_SET = 0,
  176         ///< From the current position
  177 
  178     LE_FS_SEEK_CUR = 1,
  179         ///< From the beginning of the file
  180 
  181     LE_FS_SEEK_END = 2
  182         ///< From the end of the file
  183 }
  184 le_fs_Position_t;
  185 
  186 
  187 //--------------------------------------------------------------------------------------------------
  188 /**
  189  * Maximum number of characters permitted for a file path.
  190  */
  191 //--------------------------------------------------------------------------------------------------
  192 #define LE_FS_PATH_MAX_LEN 128
  193 
  194 
  195 //--------------------------------------------------------------------------------------------------
  196 /**
  197  * Maximum number of bytes to read/write in one API call.
  198  */
  199 //--------------------------------------------------------------------------------------------------
  200 #define LE_FS_DATA_MAX_SIZE 8192
  201 
  202 
  203 //--------------------------------------------------------------------------------------------------
  204 /**
  205  * Reference of a file
  206  */
  207 //--------------------------------------------------------------------------------------------------
  208 typedef struct le_fs_File* le_fs_FileRef_t;
  209 
  210 //--------------------------------------------------------------------------------------------------
  211 /**
  212  * This function is called to create or open an existing file.
  213  *
  214  * @return
  215  *  - LE_OK             The function succeeded.
  216  *  - LE_BAD_PARAMETER  A parameter is invalid.
  217  *  - LE_OVERFLOW       The file path is too long.
  218  *  - LE_NOT_FOUND      The file does not exists or a directory in the path does not exist
  219  *  - LE_NOT_PERMITTED  Access denied to the file or to a directory in the path
  220  *  - LE_UNSUPPORTED    The prefix cannot be added and the function is unusable
  221  *  - LE_FAULT          The function failed.
  222  */
  223 //--------------------------------------------------------------------------------------------------
  224 le_result_t le_fs_Open
  225 (
  226     const char* filePath,
  227         ///< [IN] File path
  228 
  229     le_fs_AccessMode_t accessMode,
  230         ///< [IN] Access mode for the file
  231 
  232     le_fs_FileRef_t* fileRefPtr
  233         ///< [OUT] File reference (if successful)
  234 );
  235 
  236 //--------------------------------------------------------------------------------------------------
  237 /**
  238  * This function is called to close an opened file.
  239  *
  240  * @return
  241  *  - LE_OK         The function succeeded.
  242  *  - LE_FAULT      The function failed.
  243  */
  244 //--------------------------------------------------------------------------------------------------
  245 le_result_t le_fs_Close
  246 (
  247     le_fs_FileRef_t fileRef
  248         ///< [IN] File reference
  249 );
  250 
  251 //--------------------------------------------------------------------------------------------------
  252 /**
  253  * This function is called to read the requested data length from an opened file.
  254  * The data is read at the current file position.
  255  *
  256  * @return
  257  *  - LE_OK             The function succeeded.
  258  *  - LE_BAD_PARAMETER  A parameter is invalid.
  259  *  - LE_FAULT          The function failed.
  260  */
  261 //--------------------------------------------------------------------------------------------------
  262 le_result_t le_fs_Read
  263 (
  264     le_fs_FileRef_t fileRef,
  265         ///< [IN] File reference
  266 
  267     uint8_t* bufPtr,
  268         ///< [OUT] Buffer to store the data read in the file
  269 
  270     size_t* bufNumElementsPtr
  271         ///< [INOUT]
  272 );
  273 
  274 //--------------------------------------------------------------------------------------------------
  275 /**
  276  * This function is called to write the requested data length to an opened file.
  277  * The data is written at the current file position.
  278  *
  279  * @return
  280  *  - LE_OK             The function succeeded.
  281  *  - LE_BAD_PARAMETER  A parameter is invalid.
  282  *  - LE_UNDERFLOW      The write succeed but was not able to write all bytes
  283  *  - LE_FAULT          The function failed.
  284  */
  285 //--------------------------------------------------------------------------------------------------
  286 le_result_t le_fs_Write
  287 (
  288     le_fs_FileRef_t fileRef,
  289         ///< [IN] File reference
  290 
  291     const uint8_t* bufPtr,
  292         ///< [IN] Buffer to write in the file
  293 
  294     size_t bufNumElements
  295         ///< [IN]
  296 );
  297 
  298 //--------------------------------------------------------------------------------------------------
  299 /**
  300  * This function is called to change the file position of an opened file.
  301  *
  302  * @return
  303  *  - LE_OK             The function succeeded.
  304  *  - LE_BAD_PARAMETER  A parameter is invalid.
  305  *  - LE_FAULT          The function failed.
  306  */
  307 //--------------------------------------------------------------------------------------------------
  308 le_result_t le_fs_Seek
  309 (
  310     le_fs_FileRef_t fileRef,
  311         ///< [IN] File reference
  312 
  313     int32_t offset,
  314         ///< [IN] Offset to apply
  315 
  316     le_fs_Position_t position,
  317         ///< [IN] Offset is relative to this position
  318 
  319     int32_t* currentOffsetPtr
  320         ///< [OUT] Offset from the beginning after the seek operation
  321 );
  322 
  323 //--------------------------------------------------------------------------------------------------
  324 /**
  325  * This function is called to get the size of a file.
  326  *
  327  * @return
  328  *  - LE_OK             The function succeeded.
  329  *  - LE_BAD_PARAMETER  A parameter is invalid.
  330  *  - LE_OVERFLOW       The file path is too long.
  331  *  - LE_UNSUPPORTED    The prefix cannot be added and the function is unusable
  332  *  - LE_FAULT          The function failed.
  333  */
  334 //--------------------------------------------------------------------------------------------------
  335 le_result_t le_fs_GetSize
  336 (
  337     const char* filePath,
  338         ///< [IN] File path
  339 
  340     size_t* sizePtr
  341         ///< [OUT] File size (if successful)
  342 );
  343 
  344 //--------------------------------------------------------------------------------------------------
  345 /**
  346  * This function is called to delete a file.
  347  *
  348  * @return
  349  *  - LE_OK             The function succeeded.
  350  *  - LE_BAD_PARAMETER  A parameter is invalid.
  351  *  - LE_OVERFLOW       The file path is too long.
  352  *  - LE_NOT_FOUND      The file does not exist or a directory in the path does not exist
  353  *  - LE_NOT_PERMITTED  The access right fails to delete the file or access is not granted to a
  354  *                      a directory in the path
  355  *  - LE_UNSUPPORTED    The prefix cannot be added and the function is unusable
  356  *  - LE_FAULT          The function failed.
  357  */
  358 //--------------------------------------------------------------------------------------------------
  359 le_result_t le_fs_Delete
  360 (
  361     const char* filePath
  362         ///< [IN] File path
  363 );
  364 
  365 //--------------------------------------------------------------------------------------------------
  366 /**
  367  * This function is called to rename an existing file.
  368  * If rename fails, the file will keep its original name.
  369  *
  370  * @return
  371  *  - LE_OK             The function succeeded.
  372  *  - LE_BAD_PARAMETER  A parameter is invalid.
  373  *  - LE_OVERFLOW       A file path is too long.
  374  *  - LE_FAULT          The function failed.
  375  */
  376 //--------------------------------------------------------------------------------------------------
  377 le_result_t le_fs_Move
  378 (
  379     const char* srcPath,
  380         ///< [IN] Path to file to rename
  381 
  382     const char* destPath
  383         ///< [IN] New path to file
  384 );
  385 
  386 
  387 #endif // LE_FS_INTERFACE_H_INCLUDE_GUARD
  388 
le_fs_Read
le_result_t le_fs_Read(le_fs_FileRef_t fileRef, uint8_t *bufPtr, size_t *bufNumElementsPtr)


LE_FS_APPEND
Append. 
Definition: le_fs_interface.h:149


LE_FS_WRONLY
Write only. 
Definition: le_fs_interface.h:137


le_result_t
le_result_t
Definition: le_basics.h:35


le_fs_TryConnectService
le_result_t le_fs_TryConnectService(void)


LE_FS_TRUNC
Truncate. 
Definition: le_fs_interface.h:146


LE_FS_SYNC
Synchronized. 
Definition: le_fs_interface.h:152


le_fs_GetSize
le_result_t le_fs_GetSize(const char *filePath, size_t *sizePtr)


le_fs_Write
le_result_t le_fs_Write(le_fs_FileRef_t fileRef, const uint8_t *bufPtr, size_t bufNumElements)


LE_FS_SEEK_SET
From the current position. 
Definition: le_fs_interface.h:175


LE_FS_RDWR
Read/Write. 
Definition: le_fs_interface.h:140


le_fs_Open
le_result_t le_fs_Open(const char *filePath, le_fs_AccessMode_t accessMode, le_fs_FileRef_t *fileRefPtr)


le_fs_Delete
le_result_t le_fs_Delete(const char *filePath)


le_fs_ConnectService
void le_fs_ConnectService(void)


le_fs_Seek
le_result_t le_fs_Seek(le_fs_FileRef_t fileRef, int32_t offset, le_fs_Position_t position, int32_t *currentOffsetPtr)



LE_FS_CREAT
Create a new file. 
Definition: le_fs_interface.h:143


LE_FS_SEEK_END
From the end of the file. 
Definition: le_fs_interface.h:181


le_fs_FileRef_t
struct le_fs_File * le_fs_FileRef_t
Definition: le_fs_interface.h:208


LE_FS_RDONLY
Read only. 
Definition: le_fs_interface.h:134


LE_FS_SEEK_CUR
From the beginning of the file. 
Definition: le_fs_interface.h:178


le_fs_Close
le_result_t le_fs_Close(le_fs_FileRef_t fileRef)


le_fs_Move
le_result_t le_fs_Move(const char *srcPath, const char *destPath)


le_fs_DisconnectService
void le_fs_DisconnectService(void)


le_fs_AccessMode_t
le_fs_AccessMode_t
Definition: le_fs_interface.h:132


le_fs_Position_t
le_fs_Position_t
Definition: le_fs_interface.h:173