swu_target_interface

Interface used by the UpdateClient to make requests of an UpdateTarget

Synopsis:

typedef struct {

    swu_result_t (*get_info)
                    ( swu_target_id_t id, 
                      swu_target_sw_information_t *info, 
                      void *get_info_context );

    void *get_info_context;

    swu_result_t (*prepare_to_install)
                    ( swu_target_id_t id, 
                      swu_update_t update, 
                      void *prepare_to_install_context );

    void *prepare_to_install_context;

    swu_result_t (*install)
                    ( swu_target_id_t id, 
                      swu_update_t update, 
                      void *install_context );

    void *install_context;

    swu_result_t (*cancel_install)
                    ( swu_target_id_t id, 
                      swu_update_t update, 
                      void *cancel_install_context );

    void *cancel_install_context;

    swu_result_t (*verify_update)
                    ( swu_target_id_t id, 
                      swu_update_t update, 
                      void *verify_update_context );

    void *verify_update_context;

    swu_result_t (*rollback_update)
                    ( swu_target_id_t id, 
                      swu_update_t update, 
                      void *rollback_update_context );

    void *rollback_update_context;

} swu_target_interface_t;

Data:

swu_result_t (*get_info) ( swu_target_id_t id, swu_target_sw_information_t *info, void *get_info_context ): Pointer to a function that the UpdateClient can call to retrieve ID and software version information from an UpdateTarget.; This function is primarily used when the application calls swu_target_get_info(), which always calls the get_info function. However, the UpdateClient may call this latter function at other times in the software update process.
void *get_info_context: Context pointer to use as a parameter when the get_info function is called.
swu_result_t (*prepare_to_install) ( swu_target_id_t id, swu_update_t update, void *prepare_to_install_context ): Pointer to a function that the UpdateClient can call to inform an UpdateTarget that an update is available and that it should prepare for the update.; The UpdateClient calls this function after the user accepts an update that's ready for installation. The prepare_to_install function allows the UpdateTarget to determine if it's in a state suitable for updates and, if so, to prepare for an update installation.; If the UpdateTarget is ready, it should respond by calling swu_target_ready_to_install() from its own context. If it's not ready, it should call swu_target_not_ready_to_install().
void *prepare_to_install_context: Context pointer to use as a parameter when the prepare_to_install function is called.
swu_result_t (*install) ( swu_target_id_t id, swu_update_t update, void *install_context ): Pointer to a function that the UpdateClient can call to tell an UpdateTarget to start installing an update.; As soon as the UpdateTarget returns from this function, it can begin the installation. As the installation progresses, the UpdateTarget can call swu_target_install_progress() to indicate how far the installation has progressed, but this reporting is optional. The decision to track and report installation progress (and how often to do this) is an implementation detail.
void *install_context: Context pointer to use as a parameter when the install function is called.
swu_result_t (*cancel_install) ( swu_target_id_t id, swu_update_t update, void *cancel_install_context ): (Currently unused); Pointer to a function that the UpdateClient can call to request an UpdateTarget to cancel an ongoing update installation.
void *cancel_install_context: (Currently unused); Context pointer to use as a parameter when the cancel_install function is called.
swu_result_t (*verify_update) ( swu_target_id_t id, swu_update_t update, void *verify_update_context ): Pointer to a function that the UpdateClient can call to tell an UpdateTarget to verify that an update was installed correctly.; The library calls this function after an update finishes installing. The UpdateTarget can then perform any post-installation verification steps defined for it. As with the other function pointers in this structure, verify_update should be set to NULL if the UpdateTarget doesn't support or require verification.; After the verification completes successfully, the UpdateTarget must call swu_target_verification_successful() to indicate the success of this operation to the library. If a problem occurs during the verification, the UpdateTarget should call swu_target_verification_failed() and provide the reason why the verification failed.
void *verify_update_context: Context pointer to use as a parameter when the verify_update function is called.
swu_result_t (*rollback_update) ( swu_target_id_t id, swu_update_t update, void *rollback_update_context ): (Currently unused); Pointer to a function that the UpdateClient can call to request an UpdateTarget to try to rollback a previously installed update.
void *rollback_update_context: (Currently unused); Context pointer to use as a parameter when the rollback_update function is called.

Library:

libswu-core

Use the -l swu-core option with qcc to link against the SWU library. This library is usually included automatically.

Description:

Interface used by the UpdateClient to make requests of an UpdateTarget. Each UpdateTarget must register an swu_target_interface_t structure with the UpdateClient so this latter component knows how to talk to the UpdateTarget when requesting software update actions. Any functions not supported by the UpdateTarget should have their function pointers set to NULL.

Because the functions referenced in this structure are executed in the context of the library, it's expected that the UpdateTarget will quickly return from these functions. The UpdateTarget should use its own context to perform any long-running operations.