Aktualizr
C++ SOTA Client
Classes | Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
Aktualizr Class Reference

This class provides the main APIs necessary for launching and controlling libaktualizr. More...

#include <aktualizr.h>

Inheritance diagram for Aktualizr:
[legend]
Collaboration diagram for Aktualizr:
[legend]

Classes

struct  InstallationLogEntry
 

Public Types

using InstallationLog = std::vector< InstallationLogEntry >
 
using SigHandler = std::function< void(std::shared_ptr< event::BaseEvent >)>
 

Public Member Functions

 Aktualizr (const Config &config)
 Aktualizr requires a configuration object. More...
 
 Aktualizr (const Aktualizr &)=delete
 
Aktualizroperator= (const Aktualizr &)=delete
 
void Initialize ()
 Initialize aktualizr. More...
 
std::future< void > RunForever (const Json::Value &custom_hwinfo=Json::nullValue)
 Asynchronously run aktualizr indefinitely until Shutdown is called. More...
 
void Shutdown ()
 Shuts down currently running RunForever() method. More...
 
std::future< result::CampaignCheckCampaignCheck ()
 Check for campaigns. More...
 
std::future< void > CampaignControl (const std::string &campaign_id, campaign::Cmd cmd)
 Act on campaign: accept, decline or postpone. More...
 
std::future< void > SendDeviceData (const Json::Value &custom_hwinfo=Json::nullValue)
 Send local device data to the server. More...
 
std::future< result::UpdateCheckCheckUpdates ()
 Fetch Uptane metadata and check for updates. More...
 
std::future< result::DownloadDownload (const std::vector< Uptane::Target > &updates)
 Download targets. More...
 
InstallationLog GetInstallationLog ()
 Get log of installations. More...
 
std::vector< Uptane::TargetGetStoredTargets ()
 Get list of targets currently in storage. More...
 
void DeleteStoredTarget (const Uptane::Target &target)
 Delete a stored target from storage. More...
 
std::ifstream OpenStoredTarget (const Uptane::Target &target)
 Get target downloaded in Download call. More...
 
std::future< result::InstallInstall (const std::vector< Uptane::Target > &updates)
 Install targets. More...
 
bool SetInstallationRawReport (const std::string &custom_raw_report)
 SetInstallationRawReport allows setting a custom raw report field in the device installation result. More...
 
std::future< bool > SendManifest (const Json::Value &custom=Json::nullValue)
 Send installation report to the backend. More...
 
result::Pause Pause ()
 Pause the library operations. More...
 
result::Pause Resume ()
 Resume the library operations. More...
 
void Abort ()
 Aborts the currently running command, if it can be aborted, or waits for it to finish; then removes all other queued calls. More...
 
bool UptaneCycle ()
 Synchronously run an Uptane cycle: check for updates, download any new targets, install them, and send a manifest back to the server. More...
 
void AddSecondary (const std::shared_ptr< SecondaryInterface > &secondary)
 Add new Secondary to aktualizr. More...
 
void SetSecondaryData (const Uptane::EcuSerial &ecu, const std::string &data)
 Store some free-form data to be associated with a particular Secondary, to be retrieved later through GetSecondaries More...
 
std::vector< SecondaryInfoGetSecondaries () const
 Returns a list of the registered Secondaries, along with some associated metadata. More...
 
boost::signals2::connection SetSignalHandler (const SigHandler &handler)
 Provide a function to receive event notifications. More...
 

Protected Member Functions

 Aktualizr (Config config, std::shared_ptr< INvStorage > storage_in, const std::shared_ptr< HttpInterface > &http_in)
 

Protected Attributes

std::shared_ptr< SotaUptaneClientuptane_client_
 

Detailed Description

This class provides the main APIs necessary for launching and controlling libaktualizr.

Definition at line 24 of file aktualizr.h.

Constructor & Destructor Documentation

◆ Aktualizr()

Aktualizr::Aktualizr ( const Config config)
explicit

Aktualizr requires a configuration object.

Examples can be found in the config directory.

Exceptions
SQLException
boost::filesystem::filesystem_error
std::bad_alloc
std::runtime_error(filesystem and json parsing failures; libsodium initialization failure)

Definition at line 15 of file aktualizr.cc.

Member Function Documentation

◆ Abort()

void Aktualizr::Abort ( )

Aborts the currently running command, if it can be aborted, or waits for it to finish; then removes all other queued calls.

This doesn't reset the Paused state, i.e. if the queue was previously paused, it will remain paused, but with an emptied queue. The call is blocking.

Exceptions
std::system_error(failure to lock a mutex)

Definition at line 190 of file aktualizr.cc.

◆ AddSecondary()

void Aktualizr::AddSecondary ( const std::shared_ptr< SecondaryInterface > &  secondary)

Add new Secondary to aktualizr.

Must be called before Initialize.

Parameters
secondaryAn object to perform installation on a Secondary ECU.
Exceptions
std::bad_alloc(memory allocation failure)
std::runtime_error(multiple Secondaries with the same serial)

Definition at line 103 of file aktualizr.cc.

◆ CampaignCheck()

std::future< result::CampaignCheck > Aktualizr::CampaignCheck ( )

Check for campaigns.

Campaigns are a concept outside of Uptane, and allow for user approval of updates before the contents of the update are known.

Returns
std::future object with data about available campaigns.
Exceptions
std::runtime_error(curl and json parsing failures)

Definition at line 118 of file aktualizr.cc.

◆ CampaignControl()

std::future< void > Aktualizr::CampaignControl ( const std::string &  campaign_id,
campaign::Cmd  cmd 
)

Act on campaign: accept, decline or postpone.

Accepted campaign will be removed from the campaign list but no guarantee is made for declined or postponed items. Applications are responsible for tracking their state but this method will notify the server for device state monitoring purposes.

Parameters
campaign_idCampaign ID as provided by CampaignCheck.
cmdaction to apply on the campaign: accept, decline or postpone
Returns
Empty std::future object
Exceptions
std::bad_alloc(memory allocation failure)

Definition at line 123 of file aktualizr.cc.

◆ CheckUpdates()

std::future< result::UpdateCheck > Aktualizr::CheckUpdates ( )

Fetch Uptane metadata and check for updates.

This collects a client manifest, PUTs it to the director, updates the Uptane metadata (including root and targets), and then checks the metadata for target updates.

Returns
Information about available updates.
Exceptions
SQLException
boost::filesystem::filesystem_error
std::bad_alloc
std::runtime_error(curl, SQL, filesystem, and json parsing failures; database inconsistency with pending updates)

Definition at line 147 of file aktualizr.cc.

◆ DeleteStoredTarget()

void Aktualizr::DeleteStoredTarget ( const Uptane::Target target)

Delete a stored target from storage.

This only affects storage of the actual binary data and does not preclude a re-download if a target matches current metadata.

Parameters
targetTarget object matching the desired target in the storage
Returns
true if successful
Exceptions
SQLException
std::runtime_error(error getting targets from database or filesystem)

Definition at line 221 of file aktualizr.cc.

◆ Download()

std::future< result::Download > Aktualizr::Download ( const std::vector< Uptane::Target > &  updates)

Download targets.

Parameters
updatesVector of targets to download as provided by CheckUpdates.
Returns
std::future object with information about download results.
Exceptions
SQLException
std::system_error(failure to lock a mutex)

Definition at line 152 of file aktualizr.cc.

◆ GetInstallationLog()

Aktualizr::InstallationLog Aktualizr::GetInstallationLog ( )

Get log of installations.

The log is indexed for every ECU and contains every change of versions ordered by time. It may contain duplicates in case of rollbacks.

Returns
installation log
Exceptions
SQLException
std::bad_alloc(memory allocation failure)
std::runtime_error(failure to load ECU serials)

Definition at line 197 of file aktualizr.cc.

◆ GetSecondaries()

std::vector< SecondaryInfo > Aktualizr::GetSecondaries ( ) const

Returns a list of the registered Secondaries, along with some associated metadata.

Returns
vector of SecondaryInfo objects
Exceptions
SQLException
std::bad_alloc(memory allocation failure)

Definition at line 111 of file aktualizr.cc.

◆ GetStoredTargets()

std::vector< Uptane::Target > Aktualizr::GetStoredTargets ( )

Get list of targets currently in storage.

This is intended to be used with DeleteStoredTarget and targets are not guaranteed to be verified and up-to-date with current metadata.

Returns
std::vector of target objects
Exceptions
SQLException
std::bad_alloc(memory allocation failure)
std::runtime_error(error getting targets from database)

Definition at line 219 of file aktualizr.cc.

◆ Initialize()

void Aktualizr::Initialize ( )

Initialize aktualizr.

Any Secondaries should be added before making this call. This will provision with the server if required. This must be called before using any other aktualizr functions except AddSecondary.

Exceptions
Initializer::Errorand subclasses
Uptane::Exceptionand subclasses
SQLException
boost::filesystem::filesystem_error
std::system_error(failure to lock a mutex)
std::bad_alloc(memory allocation failure)
std::runtime_error(curl, P11, SQL, filesystem, credentials archive parsing, certificate parsing, json parsing failures; missing ECU serials or device ID; database inconsistency with pending updates; invalid OSTree deployment)

Definition at line 33 of file aktualizr.cc.

◆ Install()

std::future< result::Install > Aktualizr::Install ( const std::vector< Uptane::Target > &  updates)

Install targets.

Parameters
updatesVector of targets to install as provided by CheckUpdates or Download.
Returns
std::future object with information about installation results.
Exceptions
SQLException
std::runtime_error(error getting metadata from database or filesystem)

Definition at line 158 of file aktualizr.cc.

◆ OpenStoredTarget()

std::ifstream Aktualizr::OpenStoredTarget ( const Uptane::Target target)

Get target downloaded in Download call.

Returned target is guaranteed to be verified and up-to-date according to the Uptane metadata downloaded in CheckUpdates call.

Parameters
targetTarget object matching the desired target in the storage.
Returns
Handle to the stored binary. nullptr if none is found.
Exceptions
SQLException
std::runtime_error(error getting targets from database or filesystem)

Definition at line 223 of file aktualizr.cc.

◆ Pause()

result::Pause Aktualizr::Pause ( )

Pause the library operations.

In progress target downloads will be paused and API calls will be deferred.

Returns
Information about pause results.
Exceptions
std::system_error(failure to lock a mutex)
std::bad_alloc

Definition at line 172 of file aktualizr.cc.

◆ Resume()

result::Pause Aktualizr::Resume ( )

Resume the library operations.

Target downloads will resume and API calls issued during the pause will execute in fifo order.

Returns
Information about resume results.
Exceptions
std::system_error(failure to lock a mutex)
std::bad_alloc

Definition at line 181 of file aktualizr.cc.

◆ RunForever()

std::future< void > Aktualizr::RunForever ( const Json::Value &  custom_hwinfo = Json::nullValue)

Asynchronously run aktualizr indefinitely until Shutdown is called.

Parameters
custom_hwinfoif not empty will be sent to the backend instead of lshw output
Returns
Empty std::future object
Exceptions
SQLException
boost::filesystem::filesystem_error
std::system_error(failure to lock a mutex)
std::bad_alloc
std::runtime_error(curl, SQL, filesystem, and json parsing failures; database inconsistency with pending updates; error getting metadata from database or filesystem)

Definition at line 75 of file aktualizr.cc.

◆ SendDeviceData()

std::future< void > Aktualizr::SendDeviceData ( const Json::Value &  custom_hwinfo = Json::nullValue)

Send local device data to the server.

This includes network status, installed packages, hardware etc.

Parameters
custom_hwinfoif not empty will be sent to the backend instead of lshw output
Returns
Empty std::future object
Exceptions
SQLException
boost::filesystem::filesystem_error
std::bad_alloc
std::runtime_error(curl, filesystem, and json parsing failures)

Definition at line 142 of file aktualizr.cc.

◆ SendManifest()

std::future< bool > Aktualizr::SendManifest ( const Json::Value &  custom = Json::nullValue)

Send installation report to the backend.

Note
The device manifest is also sent as a part of CheckUpdates and SendDeviceData calls, as well as after a reboot if it was initiated by Aktualizr as a part of an installation process. All these manifests will not include the custom data provided in this call.
Parameters
customProject-specific data to put in the custom field of Uptane manifest
Returns
std::future object with manifest update result (true on success).
Exceptions
SQLException
std::runtime_error(curl failures; database inconsistency with pending updates)

Definition at line 167 of file aktualizr.cc.

◆ SetInstallationRawReport()

bool Aktualizr::SetInstallationRawReport ( const std::string &  custom_raw_report)

SetInstallationRawReport allows setting a custom raw report field in the device installation result.

Note
An invocation of this method will have effect only after call of Aktualizr::Install and before calling Aktualizr::SendManifest member function.
Parameters
custom_raw_reportis intended to replace a default value in the device installation report.
Returns
true if the custom raw report was successfully applied to the device installation result. If there is no installation report in the storage the function will always return false.
Exceptions
SQLException

Definition at line 163 of file aktualizr.cc.

◆ SetSecondaryData()

void Aktualizr::SetSecondaryData ( const Uptane::EcuSerial ecu,
const std::string &  data 
)

Store some free-form data to be associated with a particular Secondary, to be retrieved later through GetSecondaries

Exceptions
SQLException
std::runtime_error(SQL failure)

Definition at line 107 of file aktualizr.cc.

◆ SetSignalHandler()

boost::signals2::connection Aktualizr::SetSignalHandler ( const SigHandler handler)

Provide a function to receive event notifications.

Parameters
handlera function that can receive event objects.
Returns
a signal connection object, which can be disconnected if desired.

Definition at line 192 of file aktualizr.cc.

◆ Shutdown()

void Aktualizr::Shutdown ( )

Shuts down currently running RunForever() method.

Exceptions
std::system_error(failure to lock a mutex)

Definition at line 95 of file aktualizr.cc.

◆ UptaneCycle()

bool Aktualizr::UptaneCycle ( )

Synchronously run an Uptane cycle: check for updates, download any new targets, install them, and send a manifest back to the server.

Returns
false, if the restart is required to continue, true otherwise
Exceptions
SQLException
boost::filesystem::filesystem_error
std::system_error(failure to lock a mutex)
std::bad_alloc
std::runtime_error(curl, SQL, filesystem, and json parsing failures; database inconsistency with pending updates; error getting metadata from database or filesystem)

Definition at line 38 of file aktualizr.cc.


The documentation for this class was generated from the following files: