SWU library API

The SWU library API is exposed in six header files that define the constants, variable types, data structures, and functions that your update application can use to manage the update process. The API allows you to generate updates based on a manifest file, read information on individual updates, and accept or decline an update. It can also report progress and failures of active updates.

The first API function you must call is swu_client_initialize(), which sets up the library. Next, you can call swu_client_create_updates() and pass in the path of a manifest file, which specifies one or more updates. The library will generate Update and UpdateTarget lists based on the manifest file contents.

Before you can apply updates to a target, you must register it with the library by calling swu_target_register(), passing in a reference to an swu_target_interface_t structure. This structure defines the callback functions that carry out the various update tasks, including installation and verification. To receive progress information while an update is being applied, you can call swu_update_register_notifications() and register an swu_update_notifications_t structure, which defines callbacks for handling progress notifications.

You can call the swu_update_get_* functions (in Update.h) to get useful information such as the manifest file used to create the update, the base (i.e., current) version of the software on the target, and a referent to the target. For the target, you read its information with swu_target_get_info(). You can use the update and target information to decide whether to proceed with the update and then call either swu_update_accept_install() or swu_update_decline_install().

While applying an update, the library calls the swu_target_interface_t functions (to drive the update process) and the swu_update_notifications_t functions (to report update progress). The actions done by your application within any of these callbacks depend on your update policy, but you must report the outcomes of update operations when appropriate by calling the functions in UpdateTargetInterface.h (e.g., swu_target_install_successful(), swu_target_install_failed()).

If an update installation or verification fails, your application can try to reapply the update but only as many times as indicated by the retry limit given in the configuration settings. To access these settings, use the functions in ClientConfiguration.h.

When you're finished using the SWU library, you must call swu_client_uninitialize() to release its memory.