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