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 // Internal includes for this interface
  159 #include "le_update_common.h"
  160 /** @addtogroup le_update le_update API Reference
  161  * @{
  162  * @file le_update_common.h
  163  * @file le_update_interface.h **/
  164 //--------------------------------------------------------------------------------------------------
  165 /**
  166  * Type for handler called when a server disconnects.
  167  */
  168 //--------------------------------------------------------------------------------------------------
  169 typedef void (*le_update_DisconnectHandler_t)(void *);
  170 
  171 //--------------------------------------------------------------------------------------------------
  172 /**
  173  *
  174  * Connect the current client thread to the service providing this API. Block until the service is
  175  * available.
  176  *
  177  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  178  * called before any other functions in this API.  Normally, ConnectService is automatically called
  179  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  180  *
  181  * This function is created automatically.
  182  */
  183 //--------------------------------------------------------------------------------------------------
  184 void le_update_ConnectService
  185 (
  186     void
  187 );
  188 
  189 //--------------------------------------------------------------------------------------------------
  190 /**
  191  *
  192  * Try to connect the current client thread to the service providing this API. Return with an error
  193  * if the service is not available.
  194  *
  195  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  196  * called before any other functions in this API.  Normally, ConnectService is automatically called
  197  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  198  *
  199  * This function is created automatically.
  200  *
  201  * @return
  202  *  - LE_OK if the client connected successfully to the service.
  203  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  204  *    bound.
  205  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  206  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  207  */
  208 //--------------------------------------------------------------------------------------------------
  209 le_result_t le_update_TryConnectService
  210 (
  211     void
  212 );
  213 
  214 //--------------------------------------------------------------------------------------------------
  215 /**
  216  * Set handler called when server disconnection is detected.
  217  *
  218  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  219  * to continue without exiting, it should call longjmp() from inside the handler.
  220  */
  221 //--------------------------------------------------------------------------------------------------
  222 LE_FULL_API void le_update_SetServerDisconnectHandler
  223 (
  224     le_update_DisconnectHandler_t disconnectHandler,
  225     void *contextPtr
  226 );
  227 
  228 //--------------------------------------------------------------------------------------------------
  229 /**
  230  *
  231  * Disconnect the current client thread from the service providing this API.
  232  *
  233  * Normally, this function doesn't need to be called. After this function is called, there's no
  234  * longer a connection to the service, and the functions in this API can't be used. For details, see
  235  * @ref apiFilesC_client.
  236  *
  237  * This function is created automatically.
  238  */
  239 //--------------------------------------------------------------------------------------------------
  240 void le_update_DisconnectService
  241 (
  242     void
  243 );
  244 
  245 
  246 //--------------------------------------------------------------------------------------------------
  247 /**
  248  * Different states in the update state machine. The state machine is maintained to track the
  249  * update task underway.
  250  *
  251  * Example:
  252  *     for successful installation task, state transitions look like:
  253  *
  254  *@verbatim
  255     --> UNPACKING --> DOWNLOAD_SUCCESS --> APPLYING --> SUCCESS.
  256             |                                 |
  257             +---------------------------------+-------> FAILED.
  258 @endverbatim
  259  */
  260 //--------------------------------------------------------------------------------------------------
  261 
  262 
  263 //--------------------------------------------------------------------------------------------------
  264 /**
  265  * Error code used to provide diagnostic information after a failed update.
  266  *
  267  * @note
  268  *     Additional information may also be available in the target device's system log.
  269  */
  270 //--------------------------------------------------------------------------------------------------
  271 
  272 
  273 //--------------------------------------------------------------------------------------------------
  274 /**
  275  * The client callback function (handler) passed to le_update_Start() must look like this.
  276  */
  277 //--------------------------------------------------------------------------------------------------
  278 
  279 
  280 //--------------------------------------------------------------------------------------------------
  281 /**
  282  * Reference type used by Add/Remove functions for EVENT 'le_update_Progress'
  283  */
  284 //--------------------------------------------------------------------------------------------------
  285 
  286 
  287 //--------------------------------------------------------------------------------------------------
  288 /**
  289  * Add handler function for EVENT 'le_update_Progress'
  290  *
  291  * Register for notification of the progress of a given update.
  292  */
  293 //--------------------------------------------------------------------------------------------------
  294 le_update_ProgressHandlerRef_t le_update_AddProgressHandler
  295 (
  296     le_update_ProgressHandlerFunc_t handlerPtr,
  297         ///< [IN] Progress handler
  298     void* contextPtr
  299         ///< [IN]
  300 );
  301 
  302 //--------------------------------------------------------------------------------------------------
  303 /**
  304  * Remove handler function for EVENT 'le_update_Progress'
  305  */
  306 //--------------------------------------------------------------------------------------------------
  307 void le_update_RemoveProgressHandler
  308 (
  309     le_update_ProgressHandlerRef_t handlerRef
  310         ///< [IN]
  311 );
  312 
  313 //--------------------------------------------------------------------------------------------------
  314 /**
  315  * Starts an update.
  316  *
  317  * Progress is reported via the progress handler callback.
  318  *
  319  * @return
  320  *      - LE_OK if accepted.
  321  *      - LE_BUSY if another update is in progress.
  322  *      - LE_UNAVAILABLE if the system is still in "probation" (not marked "good" yet).
  323  */
  324 //--------------------------------------------------------------------------------------------------
  325 le_result_t le_update_Start
  326 (
  327     int fd
  328         ///< [IN] Open file descriptor from which the update can be read.
  329 );
  330 
  331 //--------------------------------------------------------------------------------------------------
  332 /**
  333  * Install the update
  334  *
  335  * @return
  336  *      - LE_OK if installation started.
  337  *      - LE_BUSY if package download is not finished yet.
  338  *      - LE_FAULT if there is an error. Check logs
  339  */
  340 //--------------------------------------------------------------------------------------------------
  341 le_result_t le_update_Install
  342 (
  343     void
  344 );
  345 
  346 //--------------------------------------------------------------------------------------------------
  347 /**
  348  * Ends an update session.  If the update isn't finished yet, cancels it.
  349  */
  350 //--------------------------------------------------------------------------------------------------
  351 void le_update_End
  352 (
  353     void
  354 );
  355 
  356 //--------------------------------------------------------------------------------------------------
  357 /**
  358  * Function to get error code when update fails.
  359  *
  360  * @return
  361  *      - Error code of encountered error.
  362  *      - ERR_NONE if update is in any other state.
  363  */
  364 //--------------------------------------------------------------------------------------------------
  365 le_update_ErrorCode_t le_update_GetErrorCode
  366 (
  367     void
  368 );
  369 
  370 //--------------------------------------------------------------------------------------------------
  371 /**
  372  * Get the index of the currently running system.
  373  *
  374  * @return The index of the running system.
  375  */
  376 //--------------------------------------------------------------------------------------------------
  377 int32_t le_update_GetCurrentSysIndex
  378 (
  379     void
  380 );
  381 
  382 //--------------------------------------------------------------------------------------------------
  383 /**
  384  * Gets the hash ID for a given system.
  385  *
  386  * @return
  387  *      - LE_OK if no problems are encountered.
  388  *      - LE_NOT_FOUND if the given index does not correspond to an available system.
  389  *      - LE_OVERFLOW if the supplied buffer is too small.
  390  *      - LE_FORMAT_ERROR if there are problems reading the hash for the system.
  391  */
  392 //--------------------------------------------------------------------------------------------------
  393 le_result_t le_update_GetSystemHash
  394 (
  395     int32_t systemIndex,
  396         ///< [IN] The system to read the hash for.
  397     char* hashStr,
  398         ///< [OUT] Buffer to hold the system hash string.
  399     size_t hashStrSize
  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 
  419 #endif // LE_UPDATE_INTERFACE_H_INCLUDE_GUARD
le_update_ErrorCode_t
le_update_ErrorCode_t
Definition: le_update_common.h:70
le_update_SetServerDisconnectHandler
LE_FULL_API void le_update_SetServerDisconnectHandler(le_update_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_update_common.h
le_result_t
le_result_t
Definition: le_basics.h:46
le_update_GetCurrentSysIndex
int32_t le_update_GetCurrentSysIndex(void)
le_update_Start
le_result_t le_update_Start(int fd)
le_update_GetPreviousSystemIndex
int32_t le_update_GetPreviousSystemIndex(int32_t systemIndex)
le_update_AddProgressHandler
le_update_ProgressHandlerRef_t le_update_AddProgressHandler(le_update_ProgressHandlerFunc_t handlerPtr, void *contextPtr)
le_update_Install
le_result_t le_update_Install(void)
le_update_GetErrorCode
le_update_ErrorCode_t le_update_GetErrorCode(void)
le_update_End
void le_update_End(void)
le_update_DisconnectHandler_t
void(* le_update_DisconnectHandler_t)(void *)
Definition: le_update_interface.h:169
le_update_RemoveProgressHandler
void le_update_RemoveProgressHandler(le_update_ProgressHandlerRef_t handlerRef)
le_limit_interface.h
le_update_GetSystemHash
le_result_t le_update_GetSystemHash(int32_t systemIndex, char *hashStr, size_t hashStrSize)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
legato.h
le_update_TryConnectService
le_result_t le_update_TryConnectService(void)
le_update_ConnectService
void le_update_ConnectService(void)
le_update_ProgressHandlerFunc_t
void(* le_update_ProgressHandlerFunc_t)(le_update_State_t updateState, uint32_t percentDone, void *contextPtr)
Definition: le_update_common.h:98
le_update_ProgressHandlerRef_t
struct le_update_ProgressHandler * le_update_ProgressHandlerRef_t
Definition: le_update_common.h:89
le_update_DisconnectService
void le_update_DisconnectService(void)