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