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

#include <aktualizr.h>

Inheritance diagram for Aktualizr:

Collaboration diagram for Aktualizr:

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

Aktualizr &	operator= (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::CampaignCheck >	CampaignCheck ()
	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::UpdateCheck >	CheckUpdates ()
	Fetch Uptane metadata and check for updates. More...

std::future< result::Download >	Download (const std::vector< Uptane::Target > &updates)
	Download targets. More...

InstallationLog	GetInstallationLog ()
	Get log of installations. More...

std::vector< Uptane::Target >	GetStoredTargets ()
	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::Install >	Install (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< SecondaryInfo >	GetSecondaries () 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< SotaUptaneClient >	uptane_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	(memory allocation failure)
std::runtime_error	(filesystem failure; 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

secondary An 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::bad_alloc	(memory allocation failure)
std::runtime_error	(curl failure)

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_id	Campaign ID as provided by CampaignCheck.
cmd	action to apply on the campaign: accept, decline or postpone

Returns: Empty std::future object

Exceptions

std::bad_alloc	(memory allocation failure)
std::system_error	(failure to lock a mutex)

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	(memory allocation failure)
std::runtime_error	(curl and filesystem failures; database inconsistency with pending updates)
std::system_error	(failure to lock a mutex)

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

target Target 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

updates Vector of targets to download as provided by CheckUpdates.

Returns: std::future object with information about download results.

Exceptions

SQLException
std::bad_alloc	(memory allocation failure)
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::Error	and subclasses
SQLException
boost::filesystem::filesystem_error
std::bad_alloc	(memory allocation failure)
std::runtime_error	(curl, P11, filesystem, credentials archive parsing, and certificate parsing failures; missing ECU serials or device ID; database inconsistency with pending updates; invalid OSTree deployment)
std::system_error	(failure to lock a mutex)

Definition at line 33 of file aktualizr.cc.

◆ Install()

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

Install targets.

Parameters

updates Vector of targets to install as provided by CheckUpdates or Download.

Returns: std::future object with information about installation results.

Exceptions

SQLException
std::bad_alloc	(memory allocation failure)
std::runtime_error	(error getting metadata from database or filesystem)
std::system_error	(failure to lock a mutex)

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

target Target 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::bad_alloc	(memory allocation failure)
std::system_error	(failure to lock a mutex)

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::bad_alloc	(memory allocation failure)
std::system_error	(failure to lock a mutex)

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_hwinfo if 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	(memory allocation failure)
std::runtime_error	(curl and filesystem failures; database inconsistency with pending updates; error getting metadata from database or filesystem)
std::system_error	(failure to lock a mutex)

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_hwinfo if 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	(memory allocation failure)
std::runtime_error	(curl and filesystem failures)
std::system_error	(failure to lock a mutex)

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

custom Project-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::bad_alloc	(memory allocation failure)
std::runtime_error	(curl failure; database inconsistency with pending updates)
std::system_error	(failure to lock a mutex)

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_report is 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

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

handler a 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::bad_alloc	(memory allocation failure)
std::runtime_error	(curl and filesystem failures; database inconsistency with pending updates; error getting metadata from database or filesystem)
std::system_error	(failure to lock a mutex)

Definition at line 38 of file aktualizr.cc.

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

include/libaktualizr/aktualizr.h
src/libaktualizr/primary/aktualizr.cc

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Aktualizr()

Member Function Documentation

◆ Abort()

◆ AddSecondary()

◆ CampaignCheck()

◆ CampaignControl()

◆ CheckUpdates()

◆ DeleteStoredTarget()

◆ Download()

◆ GetInstallationLog()

◆ GetSecondaries()

◆ GetStoredTargets()

◆ Initialize()

◆ Install()

◆ OpenStoredTarget()

◆ Pause()

◆ Resume()

◆ RunForever()

◆ SendDeviceData()

◆ SendManifest()

◆ SetInstallationRawReport()

◆ SetSecondaryData()

◆ SetSignalHandler()

◆ Shutdown()

◆ UptaneCycle()