This API is used to control updates (install/remove) for the Legato application/firmware. Update package is combination of manifest and update data. Manifest contains metadata about the update task and all the update data are appended behind manifest. Update data means installation files (most likely tar ball), firmware files etc. Update package can be pictorially viewed as follows:

                                ++++++++++++++++++++++
                                +                    +
                                +   Manifest         +
                                +                    +
                                +                    +
                                ++++++++++++++++++++++
                                +                    +
                                +   Update_data1     +
                                +                    +
                                +                    +
                                ++++++++++++++++++++++
                                +                    +
                                +   Update_data2     +
                                +                    +
                                +                    +
                                ++++++++++++++++++++++
                                +                    +
                                +   Update_data3     +
                                +                    +
                                +                    +
                                ++++++++++++++++++++++
                                          .
                                          .
                                          .
                                          .
                                ++++++++++++++++++++++
                                +                    +
                                +   Update_dataN     +
                                +                    +
                                +                    +
                                ++++++++++++++++++++++

Update service provider follows the following state machine while doing an update:

                      ------------------
            Create()  |                |            Delete()
            --------->|     NEW        |--------------------------------|
                      |                |                                |
                      ------------------                                |
                      Start() |                                         |
                              |                                         |
                              |                                         |
                              |                                         |
          |--------------     |                                         |
          |             |     |                                         |
 ALL_ITEMS_UNPACKED=NO  V     V                                         |
          |           ------------------                                |
          |           |                |   Delete()/Error*              |
          |           |   UNPACKING    |---------------------|          |
          ------------|                |                     |          |
                      ------------------                     V          V
                              |                          ------------------
                              |                          |                |
                      ALL_ITEMS_UNPACKED = YES           |      FAILED    |
                              |                          |                |
                              V                          ------------------
                      ------------------                          ^
                      |                |     Delete()/Error*      |
                |---->|    APPLYING    |--------------------------|
ALL_ITEMS_DONE = NO   |                |
                |     ------------------
                |         |    |
                |_________|    |
                          ALL_ITEMS_DONE = YES
                               |
                               V
                      ------------------
                      |                |
                      |    SUCCESS     |
                      |                |
                      ------------------

*Error:  Any kind of error occurred during update.

API Usage Guideline

This is the typical sequence of calling update API:

[MANDATORY] Client will provide update file descriptor (where manifest string is prepended at the beginning) via le_update_Create() api. Update service provider returns a handle on success.
[OPTIONAL] Client may register any callback function for status update. It's highly recommended to register callback function as client can only know its requested update status via callback function.
[MANDATORY] Client can call le_update_Start() to start update task. It's an asynchronous API. It returns after the update process(reading/parsing manifest, calling appropriate installation or removal tool as per manifest command etc) has started, but doesn't verify if it finished). Update service provider will notify the status of update task to client via callback function. If no callback is registered, the client won't get any notification.
[OPTIONAL] Client may call le_update_GetErrorCode() to get the errors that lead update to failed state. le_update_GetErrorCode() will return LE_UPDATE_ERR_NONE if update is in other state.
[MANDATORY] Client needs to call le_update_Delete() to deallocate resources. If le_update_Delete() is called in the middle of an update, update service provider will stop the update and deallocate resources if safe, otherwise the update service provider will deallocate resources after the current update task is finished. If the manifest contains multiple update items, all of the subsequent update items are deleted as part of deletion process. If the client disconnects before deleting the update handle, the update will automatically be deleted, and if the update is still in progress, it may be cancelled.

Sample Code

This code sample calls an update service provider API to perform an update:

void SoftwareUpdate
(
    void
)
{
    int fd = 0;  // Update data coming via STDIN
    le_update_HandleRef_t Handle;
    // Create an update handle.
    if ((Handle = le_update_Create(fd)) == NULL)
    {
         perror("Update failure, exiting.");
         exit(EXIT_FAILURE);
    }
    // Register callback function.
    if (le_update_AddProgressHandler(Handle, UpdateProgressHandler, NULL) == NULL)
    {
         perror("Can't register status handler");
         exit(EXIT_FAILURE);
    }
    // Start update process(asynchronous). Completion will be notified via callback function.
    if (le_update_Start(Handle) != LE_OK)
    {
         perror("Can't start update task !");
         exit(EXIT_FAILURE);
    }
}
// Sample callback function implementation.
static void UpdateProgressHandler
(
    le_update_State_t updateState,   
    uint percentDone,                
    void* contextPtr                 
)
{
    switch(updateState)
    {
        case LE_UPDATE_STATE_NEW:
            // New update. Print this information.
            fprintf(stdout, "New update started\n");
            break;
        case LE_UPDATE_STATE_UNPACKING:
            fprintf(stdout, "Unpacking: %d \n", percentDone);
            break;
        case LE_UPDATE_STATE_APPLYING:
            fprintf(stdout, "Applying: %d \n", percentDone);
            break;
        case LE_UPDATE_STATE_SUCCESS:
            //Successful update(install/remove) task.
            fprintf(stdout, "\nSUCCESS\n");
            le_update_Delete(Handle);
            exit(EXIT_SUCCESS);
        case LE_UPDATE_STATE_FAILED:
            // Failure in update, exit with failure code.
            fprintf(stderr, "\nFAILED, ErrorCode: %d\n", le_update_GetErrorCode(Handle));
            le_update_Delete(Handle);
            exit(EXIT_FAILURE);
    }
}

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.