Update API

API Reference

---

This API is used to update the software/firmware of the target device using update packs.

Update packs can contain one or more "tasks" to be performed by the Update Daemon.

from the point of view of the client of this API, the update service follows this 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 during update.

API Usage Guidelines

Typically, the API used used as follows:

1. Client calls le_update_Create(), providing a file descriptor that the update service can read the update pack from.
2. Server returns a handle for the update that the client can later use to cancel the update or register for notification of events related to this update.
3. Client calls le_update_AddProgressHandler() to register a callback function to be called (by the Legato event loop) when events related to this update are reported by the update service.
4. Client calls le_update_Start() to start the update. This is an asynchronous function call, meaning that it returns immediately without providing any status feedback.
5. Progress reports are sent to the client periodically via the notification function registered by the client through le_update_AddProgressHandler().
6. If the update fails, le_update_GetErrorCode() can be used to find out more information.
7. When the client is finished with the update, the client MUST call le_update_Delete() to deallocate resources.

To cancel an update before it finishes, call le_update_Delete().

If the client disconnects before deleting the update, the update will automatically be deleted, and if the update is still in progress, it may be cancelled (if it's not too late).

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

    // Create an update handle.
    le_update_HandleRef_t updateHandle = le_update_Create(fd);
    if (updateHandle == NULL)
    {
         fprintf(stderr, "Update already in progress.  Try again later.\n");

         // NOTE: It's okay to not delete the update here because we are exiting, so the handle
         //       will be deleted automatically.

         exit(EXIT_FAILURE);
    }

    // Register callback function.  (note: contextPtr not needed in this example)
    le_update_AddProgressHandler(updateHandle, UpdateProgressHandler, NULL);

    // Start update process. Completion will be notified via callback function.
    le_update_Start(updateHandle);
}


// 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:
            fprintf(stdout, "\nSUCCESS\n");
            exit(EXIT_SUCCESS);

        case LE_UPDATE_STATE_FAILED:
            fprintf(stderr, "\nFAILED: error code %d\n", le_update_GetErrorCode(Handle));
            exit(EXIT_FAILURE);
    }
}

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