le_update_interface.h

    1 
    2 
    3 /*
    4  * ====================== WARNING ======================
    5  *
    6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    7  * DO NOT MODIFY IN ANY WAY.
    8  *
    9  * ====================== WARNING ======================
   10  */
   11 
   12 /**
   13  * @page c_update Update API
   14  *
   15  * @ref le_update_interface.h "API Reference" <br>
   16  * @ref legatoServicesUpdate <br>
   17  * @ref legatoServicesUpdatePack <br>
   18  * @ref conceptsUpdates <br>
   19  * @ref getStartedUpdate
   20  *
   21  *
   22  * This API uses @ref legatoServicesUpdatePack to update a target device software/firmware.
   23  *
   24  * Update packs can contain one or more @e tasks to be performed by the
   25  * @ref basicRuntimeArch_updateDaemon.
   26  *
   27  * From the client view, the update service follows this state machine
   28  * while doing an update:
   29  *
   30  *@image html updateApi.png
   31  *
   32  * @section API_Usage_Guideline API Usage Guidelines
   33  *
   34  * Typically, the API is used like this:
   35  *
   36  * 1. Client calls le_update_Start() providing a file descriptor for the update service to
   37  *    read the update pack and a notification callback function to call with updates.
   38  *
   39  * 2. Progress reports are sent to the client periodically through the notification function.
   40  *
   41  * 3. If the update fails, le_update_GetErrorCode() can be used to find out more info.
   42  *
   43  * 4. When the client is finished with the update, the client MUST call le_update_End() to
   44  *    relocate resources.
   45  *
   46  * To cancel an update before it finishes, call le_update_End().
   47  *
   48  * If the client disconnects before ending the update session, the session will automatically end.
   49  * If the update is still in progress, it may be cancelled (if it's not too late).
   50  *
   51  *
   52  * @section update_example Sample Code
   53  *
   54  * This C code sample calls an update service provider API to perform an update:
   55  *
   56  * @code
   57  *
   58  * void SoftwareUpdate(void)
   59  * {
   60  *     int fd = 0;  // Update data coming via STDIN
   61  *
   62  *     // Register for progress notifications.
   63  *     le_update_AddProgressHandler(UpdateProgressHandler, NULL);
   64  *
   65  *     // Start update process(asynchronous). Completion will be notified via callback function.
   66  *     le_result_t result = le_update_Start(fd);
   67  *     if (result != LE_OK)
   68  *     {
   69  *          fprintf(stderr, "Update refused by server.  Try again later.\n");
   70  *
   71  *          // NOTE: It's okay to not delete the update here because we are exiting, so the handle
   72  *          //       will be deleted automatically.
   73  *
   74  *          exit(EXIT_FAILURE);
   75  *     }
   76  * }
   77  *
   78  *
   79  * // Sample callback function implementation.
   80  * static void UpdateProgressHandler
   81  * (
   82  *     le_update_State_t updateState,   ///< Current state of the update.
   83  *     uint32 percentDone,              ///< Percent done for current state.
   84  *     void* contextPtr                 ///< Context pointer (NULL).
   85  * )
   86  * {
   87  *     switch(updateState)
   88  *     {
   89  *         case LE_UPDATE_STATE_UNPACKING:
   90  *             fprintf(stdout, "Unpacking: %d%% \n", percentDone);
   91  *             break;
   92  *
   93  *         case LE_UPDATE_STATE_DOWNLOAD_SUCCESS:
   94  *             le_update_Install();
   95  *             break;
   96  *
   97  *         case LE_UPDATE_STATE_APPLYING:
   98  *             fprintf(stdout, "Applying: %d%% \n", percentDone);
   99  *             break;
  100  *
  101  *         case LE_UPDATE_STATE_SUCCESS:
  102  *             fprintf(stdout, "\nSUCCESS\n");
  103  *             exit(EXIT_SUCCESS);
  104  *
  105  *         case LE_UPDATE_STATE_FAILED:
  106  *             fprintf(stderr, "\nFAILED: error code %d\n", le_update_GetErrorCode());
  107  *             exit(EXIT_FAILURE);
  108  *     }
  109  * }
  110  *
  111  * @endcode
  112  *
  113  * @section Update_API_System_Info Installed System Information
  114  *
  115  * It is possible to get the index and hash for all of the currently installed systems.  The
  116  * following is an example of how one would list all installed systems and their hashes.
  117  *
  118  * @code
  119  *
  120  * int32_t systemIndex = le_update_GetCurrentSysIndex();
  121  *
  122  * do
  123  * {
  124  *     char hashBuffer[LE_LIMIT_MD5_STR_LEN + 1];
  125  *
  126  *     if (le_update_GetSystemHash(systemIndex, hashBuffer, sizeof(hashBuffer)) == LE_OK)
  127  *     {
  128  *         LE_INFO("System: %d -- %s", systemIndex, hashBuffer);
  129  *     }
  130  *     else
  131  *     {
  132  *         LE_ERROR("System: %d -- NOT FOUND", systemIndex);
  133  *     }
  134  * }
  135  * while ((systemIndex = le_update_GetPreviousSystemIndex(systemIndex)) != -1);
  136  *
  137  * @endcode
  138  *
  139  * Copyright (C) Sierra Wireless Inc.
  140  */
  141 /**
  142  * @file le_update_interface.h
  143  *
  144  * Legato @ref c_update include file.
  145  *
  146  * Copyright (C) Sierra Wireless Inc.
  147  */
  148 
  149 #ifndef LE_UPDATE_INTERFACE_H_INCLUDE_GUARD
  150 #define LE_UPDATE_INTERFACE_H_INCLUDE_GUARD
  151 
  152 
  153 #include "legato.h"
  154 
  155 // Interface specific includes
  156 #include "le_limit_interface.h"
  157 
  158 
  159 //--------------------------------------------------------------------------------------------------
  160 /**
  161  * Type for handler called when a server disconnects.
  162  */
  163 //--------------------------------------------------------------------------------------------------
  164 typedef void (*le_update_DisconnectHandler_t)(void *);
  165 
  166 //--------------------------------------------------------------------------------------------------
  167 /**
  168  *
  169  * Connect the current client thread to the service providing this API. Block until the service is
  170  * available.
  171  *
  172  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  173  * called before any other functions in this API.  Normally, ConnectService is automatically called
  174  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  175  *
  176  * This function is created automatically.
  177  */
  178 //--------------------------------------------------------------------------------------------------
  179 void le_update_ConnectService
  180 (
  181     void
  182 );
  183 
  184 //--------------------------------------------------------------------------------------------------
  185 /**
  186  *
  187  * Try to connect the current client thread to the service providing this API. Return with an error
  188  * if the service is not available.
  189  *
  190  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  191  * called before any other functions in this API.  Normally, ConnectService is automatically called
  192  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  193  *
  194  * This function is created automatically.
  195  *
  196  * @return
  197  *  - LE_OK if the client connected successfully to the service.
  198  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  199  *    bound.
  200  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  201  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  202  */
  203 //--------------------------------------------------------------------------------------------------
  204 le_result_t le_update_TryConnectService
  205 (
  206     void
  207 );
  208 
  209 //--------------------------------------------------------------------------------------------------
  210 /**
  211  * Set handler called when server disconnection is detected.
  212  *
  213  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  214  * to continue without exiting, it should call longjmp() from inside the handler.
  215  */
  216 //--------------------------------------------------------------------------------------------------
  217 void le_update_SetServerDisconnectHandler
  218 (
  219     le_update_DisconnectHandler_t disconnectHandler,
  220     void *contextPtr
  221 );
  222 
  223 //--------------------------------------------------------------------------------------------------
  224 /**
  225  *
  226  * Disconnect the current client thread from the service providing this API.
  227  *
  228  * Normally, this function doesn't need to be called. After this function is called, there's no
  229  * longer a connection to the service, and the functions in this API can't be used. For details, see
  230  * @ref apiFilesC_client.
  231  *
  232  * This function is created automatically.
  233  */
  234 //--------------------------------------------------------------------------------------------------
  235 void le_update_DisconnectService
  236 (
  237     void
  238 );
  239 
  240 
  241 //--------------------------------------------------------------------------------------------------
  242 /**
  243  * Different states in the update state machine. The state machine is maintained to track the
  244  * update task underway.
  245  *
  246  * Example:
  247  *     for successful installation task, state transitions look like:
  248  *
  249  *@verbatim
  250     --> UNPACKING --> DOWNLOAD_SUCCESS --> APPLYING --> SUCCESS.
  251             |                                 |
  252             +---------------------------------+-------> FAILED.
  253 @endverbatim
  254  */
  255 //--------------------------------------------------------------------------------------------------
  256 typedef enum
  257 {
  258     LE_UPDATE_STATE_UNPACKING = 0,
  259         ///< Unpacking update data.
  260     LE_UPDATE_STATE_DOWNLOAD_SUCCESS = 1,
  261         ///< Update data downloaded successfully.
  262     LE_UPDATE_STATE_APPLYING = 2,
  263         ///< Applying update(i.e. installation/removal operation going on).
  264     LE_UPDATE_STATE_SUCCESS = 3,
  265         ///< Successfully completed all update task.
  266     LE_UPDATE_STATE_FAILED = 4
  267         ///< Update failed due to some error or deletion request.
  268 }
  269 le_update_State_t;
  270 
  271 
  272 //--------------------------------------------------------------------------------------------------
  273 /**
  274  * Error code used to provide diagnostic information after a failed update.
  275  *
  276  * @note
  277  *     Additional information may also be available in the target device's system log.
  278  */
  279 //--------------------------------------------------------------------------------------------------
  280 typedef enum
  281 {
  282     LE_UPDATE_ERR_NONE = 0,
  283         ///< No error.
  284     LE_UPDATE_ERR_BAD_PACKAGE = 1,
  285         ///< Encountered bad update package. Check logs.
  286     LE_UPDATE_ERR_INTERNAL_ERROR = 2,
  287         ///< Something failed while doing update.  Check logs.
  288     LE_UPDATE_ERR_SECURITY_FAILURE = 3
  289         ///< Error while doing security check of the package.
  290 }
  291 le_update_ErrorCode_t;
  292 
  293 
  294 //--------------------------------------------------------------------------------------------------
  295 /**
  296  * Reference type used by Add/Remove functions for EVENT 'le_update_Progress'
  297  */
  298 //--------------------------------------------------------------------------------------------------
  299 typedef struct le_update_ProgressHandler* le_update_ProgressHandlerRef_t;
  300 
  301 
  302 //--------------------------------------------------------------------------------------------------
  303 /**
  304  * The client callback function (handler) passed to le_update_Start() must look like this.
  305  */
  306 //--------------------------------------------------------------------------------------------------
  307 typedef void (*le_update_ProgressHandlerFunc_t)
  308 (
  309     le_update_State_t updateState,
  310         ///< Current state of update.
  311     uint32_t percentDone,
  312         ///< Percent done for current state. For example, in state
  313         ///< UNPACKING, a percentDone of 80 means that 80% of the update
  314         ///< data has been unpacked.
  315     void* contextPtr
  316         ///<
  317 );
  318 
  319 //--------------------------------------------------------------------------------------------------
  320 /**
  321  * Add handler function for EVENT 'le_update_Progress'
  322  *
  323  * Register for notification of the progress of a given update.
  324  */
  325 //--------------------------------------------------------------------------------------------------
  326 le_update_ProgressHandlerRef_t le_update_AddProgressHandler
  327 (
  328     le_update_ProgressHandlerFunc_t handlerPtr,
  329         ///< [IN] Progress handler
  330     void* contextPtr
  331         ///< [IN]
  332 );
  333 
  334 //--------------------------------------------------------------------------------------------------
  335 /**
  336  * Remove handler function for EVENT 'le_update_Progress'
  337  */
  338 //--------------------------------------------------------------------------------------------------
  339 void le_update_RemoveProgressHandler
  340 (
  341     le_update_ProgressHandlerRef_t handlerRef
  342         ///< [IN]
  343 );
  344 
  345 //--------------------------------------------------------------------------------------------------
  346 /**
  347  * Starts an update.
  348  *
  349  * Progress is reported via the progress handler callback.
  350  *
  351  * @return
  352  *      - LE_OK if accepted.
  353  *      - LE_BUSY if another update is in progress.
  354  *      - LE_UNAVAILABLE if the system is still in "probation" (not marked "good" yet).
  355  */
  356 //--------------------------------------------------------------------------------------------------
  357 le_result_t le_update_Start
  358 (
  359     int fd
  360         ///< [IN] Open file descriptor from which the update can be read.
  361 );
  362 
  363 //--------------------------------------------------------------------------------------------------
  364 /**
  365  * Install the update
  366  *
  367  * @return
  368  *      - LE_OK if installation started.
  369  *      - LE_BUSY if package download is not finished yet.
  370  *      - LE_FAULT if there is an error. Check logs
  371  */
  372 //--------------------------------------------------------------------------------------------------
  373 le_result_t le_update_Install
  374 (
  375     void
  376 );
  377 
  378 //--------------------------------------------------------------------------------------------------
  379 /**
  380  * Ends an update session.  If the update isn't finished yet, cancels it.
  381  */
  382 //--------------------------------------------------------------------------------------------------
  383 void le_update_End
  384 (
  385     void
  386 );
  387 
  388 //--------------------------------------------------------------------------------------------------
  389 /**
  390  * Function to get error code when update fails.
  391  *
  392  * @return
  393  *      - Error code of encountered error.
  394  *      - ERR_NONE if update is in any other state.
  395  */
  396 //--------------------------------------------------------------------------------------------------
  397 le_update_ErrorCode_t le_update_GetErrorCode
  398 (
  399     void
  400 );
  401 
  402 //--------------------------------------------------------------------------------------------------
  403 /**
  404  * Get the index of the currently running system.
  405  *
  406  * @return The index of the running system.
  407  */
  408 //--------------------------------------------------------------------------------------------------
  409 int32_t le_update_GetCurrentSysIndex
  410 (
  411     void
  412 );
  413 
  414 //--------------------------------------------------------------------------------------------------
  415 /**
  416  * Gets the hash ID for a given system.
  417  *
  418  * @return
  419  *      - LE_OK if no problems are encountered.
  420  *      - LE_NOT_FOUND if the given index does not correspond to an available system.
  421  *      - LE_OVERFLOW if the supplied buffer is too small.
  422  *      - LE_FORMAT_ERROR if there are problems reading the hash for the system.
  423  */
  424 //--------------------------------------------------------------------------------------------------
  425 le_result_t le_update_GetSystemHash
  426 (
  427     int32_t systemIndex,
  428         ///< [IN] The system to read the hash for.
  429     char* hashStr,
  430         ///< [OUT] Buffer to hold the system hash string.
  431     size_t hashStrSize
  432         ///< [IN]
  433 );
  434 
  435 //--------------------------------------------------------------------------------------------------
  436 /**
  437  * Get the index for the previous system in the chain, using the current system as a starting point.
  438  *
  439  * @return The index to the system that's previous to the given system.  -1 is returned if the
  440  *         previous system was not found.
  441  */
  442 //--------------------------------------------------------------------------------------------------
  443 int32_t le_update_GetPreviousSystemIndex
  444 (
  445     int32_t systemIndex
  446         ///< [IN] Get the system that's older than this system.
  447 );
  448 
  449 #endif // LE_UPDATE_INTERFACE_H_INCLUDE_GUARD
le_update_End
void le_update_End(void)
le_update_DisconnectHandler_t
void(* le_update_DisconnectHandler_t)(void *)
Definition: le_update_interface.h:164
LE_UPDATE_STATE_FAILED
Update failed due to some error or deletion request. 
Definition: le_update_interface.h:266
le_result_t
le_result_t
Definition: le_basics.h:35
le_update_ErrorCode_t
le_update_ErrorCode_t
Definition: le_update_interface.h:280
LE_UPDATE_STATE_APPLYING
Applying update(i.e. installation/removal operation going on). 
Definition: le_update_interface.h:262
le_update_RemoveProgressHandler
void le_update_RemoveProgressHandler(le_update_ProgressHandlerRef_t handlerRef)
le_update_SetServerDisconnectHandler
void le_update_SetServerDisconnectHandler(le_update_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_update_Start
le_result_t le_update_Start(int fd)
le_update_ProgressHandlerRef_t
struct le_update_ProgressHandler * le_update_ProgressHandlerRef_t
Definition: le_update_interface.h:299
LE_UPDATE_ERR_INTERNAL_ERROR
Something failed while doing update. Check logs. 
Definition: le_update_interface.h:286
LE_UPDATE_STATE_SUCCESS
Successfully completed all update task. 
Definition: le_update_interface.h:264
le_update_ProgressHandlerFunc_t
void(* le_update_ProgressHandlerFunc_t)(le_update_State_t updateState, uint32_t percentDone, void *contextPtr)
Definition: le_update_interface.h:308
le_update_TryConnectService
le_result_t le_update_TryConnectService(void)
le_update_AddProgressHandler
le_update_ProgressHandlerRef_t le_update_AddProgressHandler(le_update_ProgressHandlerFunc_t handlerPtr, void *contextPtr)
le_update_State_t
le_update_State_t
Definition: le_update_interface.h:256
le_update_GetCurrentSysIndex
int32_t le_update_GetCurrentSysIndex(void)
le_update_GetSystemHash
le_result_t le_update_GetSystemHash(int32_t systemIndex, char *hashStr, size_t hashStrSize)
LE_UPDATE_STATE_DOWNLOAD_SUCCESS
Update data downloaded successfully. 
Definition: le_update_interface.h:260
le_limit_interface.h
LE_UPDATE_ERR_SECURITY_FAILURE
Error while doing security check of the package. 
Definition: le_update_interface.h:288
le_update_ConnectService
void le_update_ConnectService(void)
le_update_DisconnectService
void le_update_DisconnectService(void)
legato.h
le_update_Install
le_result_t le_update_Install(void)
LE_UPDATE_STATE_UNPACKING
Unpacking update data. 
Definition: le_update_interface.h:258
le_update_GetPreviousSystemIndex
int32_t le_update_GetPreviousSystemIndex(int32_t systemIndex)
le_update_GetErrorCode
le_update_ErrorCode_t le_update_GetErrorCode(void)
LE_UPDATE_ERR_NONE
No error. 
Definition: le_update_interface.h:282
LE_UPDATE_ERR_BAD_PACKAGE
Encountered bad update package. Check logs. 
Definition: le_update_interface.h:284