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