Key concepts of the library

The swu-core library stores objects that represent pending software updates and accessible target systems. It automates many aspects of interacting with these objects, including memory management, data storage, and state transitions throughout the update lifecycle.

Object handles

The library encapsulates the update data by hiding the implementation of objects. Instead of offering direct access to individual data fields, the library provides a high-level API that uses handles to refer to objects. For example, instead of working with C-strings in an Update object, the caller must use the swu_update_get_name() API function with an swu_update_t handle to access the update name stored in that object.

Reference counting

Many objects in the swu-core library are reference-counted, including:

swu_string_t
swu_uri_t
swu_client_id_t
swu_update_t
swu_target_t

When working with these handle types, you should call swu_object_retain() to increment the reference count. Most API functions that return these handle types must call this function before exiting. When you're finished with a handle, you should call swu_object_release() to decrement the reference count, to indicate that you no longer need the object associated with that handle. When the reference count reaches zero, the library frees the associated object's memory. Calling the release function when you no longer need a handle is important to prevent memory leaks.

Update object

An Update object represents a software update that can be installed by a registered UpdateTarget. All configuration information for the update and all actions to be performed as part of it are specified in API calls to the Update object.

Note: An Update object is meant for only one UpdateTarget (i.e., target system). You'll need to create an Update object for each UpdateTarget.

Each Update object contains a state machine that drives the software update process. The machine's state-transition diagram looks like this:

Figure 1. State-transition diagram for Update objects

The states of the Update object are:

SWU_UPDATE_STATE_NEW: The Update object has been created.
SWU_UPDATE_STATE_VERIFYING: The library is verifying the validity of the new object.
SWU_UPDATE_STATE_VERIFIED: The object's validity has been verified and the user or an application can now accept or decline the update.
SWU_UPDATE_STATE_INSTALLING: The swu_update_accept_install() function was called to start the update and the associated UpdateTarget object was found in the list of registered targets. While the update is in this state, the library calls the prepare_to_install() and install() functions in the registered interface of the UpdateTarget object.
SWU_UPDATE_STATE_INSTALL_COMPLETED: The UpdateTarget successfully installed the update.
SWU_UPDATE_STATE_INSTALL_FAILED: The UpdateTarget encountered an error during the installation or verification phase.
SWU_UPDATE_STATE_INSTALL_VERIFYING: The update was successfully installed and the UpdateTarget is verifying that the installation is correct, in response to the library's call to the verify_update() function. If the UpdateTarget doesn't register this function, this state is skipped and the Update object transitions directly to the SWU_UPDATE_STATE_INSTALL_VERIFIED state.
SWU_UPDATE_STATE_INSTALL_VERIFIED: The UpdateTarget successfully verified the update installation.
SWU_UPDATE_STATE_ERROR: An unexpected error occurred somewhere in the update lifecycle. The client should log an error message by calling the registered swu_logging_callback_t() function.
SWU_UPDATE_STATE_DECLINED: The update has been marked as declined, following a call to swu_update_decline_install(). The update remains in this state and can't be installed.

UpdateTarget object

An UpdateTarget represents a system with updatable software. This object type is generic so the swu-core library can support many different software update models. You can register multiple UpdateTarget objects with the library, each of which has its own implementation. For example, you could register multiple target objects to support updating different micro-controllers on a car's vehicle network.