le_update_interface.h

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