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

#include <aktualizr.h>

Inheritance diagram for Aktualizr:

Classes
struct	InstallationLogEntry
	Get log of installations. More...

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.

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 ()

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`

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 20 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.

Definition at line 13 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.

Definition at line 186 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.

Definition at line 99 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.

Definition at line 114 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

Definition at line 119 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.

Definition at line 143 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

Definition at line 217 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.

Definition at line 148 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

Definition at line 107 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

Definition at line 215 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.

Definition at line 29 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.

Definition at line 154 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.

Definition at line 219 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.

Definition at line 168 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.

Definition at line 177 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

Definition at line 71 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

Definition at line 138 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).

Definition at line 163 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.

Definition at line 159 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 188 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

Definition at line 34 of file aktualizr.cc.

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

src/libaktualizr/primary/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()

◆ GetSecondaries()

◆ GetStoredTargets()

◆ Initialize()

◆ Install()

◆ OpenStoredTarget()

◆ Pause()

◆ Resume()

◆ RunForever()

◆ SendDeviceData()

◆ SendManifest()

◆ SetInstallationRawReport()

◆ SetSignalHandler()

◆ UptaneCycle()