The service allows to create backups of device data as well as to restore data from backups. More...

#include <IBackupAndRestoreService.hpp>

Inheritance diagram for Arp::Services::BackupAndRestore::Services::IBackupAndRestoreService:

Public Types
using	Ptr = std::shared_ptr< IBackupAndRestoreService >

using	CreateBackupMatchesAnyOfDelegate = delegate< void(IRscWriteEnumerator< ItemSelectionRule > &)>

using	GetBackupBehaviorMatchesAnyOfDelegate = delegate< void(IRscWriteEnumerator< ItemSelectionRule > &)>

using	GetBackupOptionsResultDelegate = delegate< void(IRscReadEnumerator< BackupAndRestoreOption > &)>

using	GetBackupsResultDelegate = delegate< void(IRscReadEnumerator< Backup > &)>

using	GetRestoreBehaviorMatchesAnyOfDelegate = delegate< void(IRscWriteEnumerator< ItemSelectionRule > &)>

using	GetRestoreOptionsResultDelegate = delegate< void(IRscReadEnumerator< BackupAndRestoreOption > &)>

using	RestoreBackupMatchesAnyOfDelegate = delegate< void(IRscWriteEnumerator< ItemSelectionRule > &)>

Public Types inherited from Arp::Base::Rsc::Commons::IRscService
using	Ptr = std::shared_ptr< IRscService >
	The shared_ptr type of IRscService.

Public Member Functions
	IBackupAndRestoreService (void)=default
	Constructs an IBackupAndRestoreService instance.

virtual BackupAndRestoreStatus	GetStatus ()=0
	Returns the current status. More...

virtual StatusCode	Resume ()=0
	Resets the error state. More...

virtual void	GetBackupOptions (const RscString< 16 > &locale, GetBackupOptionsResultDelegate resultDelegate)=0
	Returns the available backup options. More...

virtual void	GetRestoreOptions (const RscString< 16 > &locale, GetRestoreOptionsResultDelegate resultDelegate)=0
	Returns the available restore options. More...

virtual BackupAndRestoreBehavior	GetBackupBehavior (GetBackupBehaviorMatchesAnyOfDelegate matchesAnyOfDelegate)=0
	Returns the behavior for a backup with the selected items. More...

virtual BackupAndRestoreBehavior	GetRestoreBehavior (GetRestoreBehaviorMatchesAnyOfDelegate matchesAnyOfDelegate)=0
	Returns the behavior for a restore with the selected items. More...

virtual StatusCode	CreateBackup (const RscString< 64 > &name, const RscSecureString< 128 > &password, CreateBackupMatchesAnyOfDelegate matchesAnyOfDelegate, RscString< 512 > &filename)=0
	Starts an async task to create an encrypted backup which will contain the selected items. More...

virtual StatusCode	RestoreBackup (const RscString< 512 > &filename, const RscSecureString< 128 > &password, RestoreBackupMatchesAnyOfDelegate matchesAnyOfDelegate)=0
	Starts an async task to restore a backup which will restore the selected items. More...

virtual void	GetBackups (GetBackupsResultDelegate resultDelegate)=0
	Returns information about the available backups on the device. More...

virtual StatusCode	AddBackup (const RscString< 512 > &filename)=0
	Starts an async task to add the backup file and performs validation. More...

virtual TransferStatus	GetAddBackupStatus ()=0
	Returns the status of the last AddBackup call. More...

virtual StatusCode	DeleteBackup (const RscString< 512 > &filename)=0
	Deletes a backup from the device. More...

Public Member Functions inherited from Arp::Base::Rsc::Commons::IRscService
	IRscService (void)=default
	The default constructor.

	IRscService (const IRscService &arg)=delete
	The deleted copy constructor. More...

	IRscService (IRscService &&arg) noexcept=default
	The default move constructor. More...

IRscService &	operator= (const IRscService &arg)=delete
	The deleted assignment operator. More...

IRscService &	operator= (IRscService &&arg) noexcept=default
	The default move-assignment operator. More...

virtual	~IRscService (void)=default
	Destructs this instance and frees all resources.

Static Public Member Functions
static IRscServiceProxyFactory &	GetProxyFactory (void)

Static Public Member Functions inherited from Arp::Base::Rsc::Commons::IRscService
static IRscServiceProxyFactory &	GetProxyFactory (void)
	Returns a reference to service proxy factory to create a proxy instance of this service. More...

Detailed Description

The service allows to create backups of device data as well as to restore data from backups.

Backup and restore operations support various use cases and do not always require a full system backup or a complete restore. In many scenarios, it is sufficient to back up only specific parts of the system. A typical example is modifying application configurations: Before making changes, the current configuration can be backed up so that it can be selectively restored if needed. For such cases, two approaches are possible: Selective backup: Only the relevant data (e.g., configuration) is backed up. Full backup with selective restore: A complete backup is created, but only specific parts (e.g., configuration data) are restored later. A full backup is not always necessary because:

it can be time-consuming, depending on system size,
it may produce large data volumes,
and often includes more data than actually required.

An important aspect is that certain data is bound to the device/hardware. For example, security-related information such as TPM keys cannot be transferred to another device. When restoring data to a different device, manual post-processing is required, such as:

regenerating keys,
reconfiguring security-related settings.

To enable flexible backup and restore operations, device data is organized into categories. These categories as well as the behavior during backup and restore are defined by TAGs. These TAGs allow precise selection of what should be backed up or restored. TAGs are separated in different types e.g.:

The software "CLASS" (Project, App, Configuration, Container, Firmware).
The "KIND" of data (SoftwarePackage, RuntimeData, Certificates, Secrets, Parameters).
A specific software instance (e.g. for the Engineer Project or PLCnext Store App).
Special TAGs which define critical behavior during backup and restore.

The annotation of files and directories to TAGs are defined in BackupDescriptor files. Example usage:

Modify a configuration on the device.
Call GetBackupBehavior()
If behavior requires NeedsPreparation, the PLC must be stopped (IPlcManagerService).
Call CreateBackup()
Call GetStatus() until state is Idle or Error.
If state is Error, call Resume(); Otherwise, transfer the backup to the client host.
Start PLC if PLC has been stopped.
Call DeleteBackup() to free space.

Modify the same configuration.

Call GetRestoreBehavior()
If behavior requires NeedsPreparation, the PLC must be stopped (IPlcManagerService).
Transfer the backup from the client to the device.
Call AddBackup()
Call GetAddBackupStatus() until InProgress is false and check whether transfer has been successful.
Call RestoreBackup()
Call GetStatus() until state is Idle or Error.
If state is Error, call Resume().
Start PLC if PLC has been stopped.
Call DeleteBackup() to free space.

It is not possible to run multiple backup and restore tasks in parallel.

Realtime Usage: This API call does not have to be deterministic in runtime behaviour, so an asynchronous execution should be considered.

Consider the following common rule when using RSC services that provide arrays or enumerators as return values or out arguments: It is always required to completely read all items from these resulting lists or enumerators.

Member Function Documentation

◆ AddBackup()

virtual StatusCode Arp::Services::BackupAndRestore::Services::IBackupAndRestoreService::AddBackup ( const RscString< 512 > & filename )

pure virtual

Starts an async task to add the backup file and performs validation.

The file is moved into the directory which contains the backups. $ARP_PATH_DATA_DIR$/Services/BackupAndRestore

Parameters

filename The path to the backup file. Appropriate read/write permissions for the file are required.

Returns: Good on success; Any Bad* StatusCode if the transfer task could not be started.

◆ CreateBackup()

virtual StatusCode Arp::Services::BackupAndRestore::Services::IBackupAndRestoreService::CreateBackup	(	const RscString< 64 > &	name,
		const RscSecureString< 128 > &	password,
		CreateBackupMatchesAnyOfDelegate	matchesAnyOfDelegate,
		RscString< 512 > &	filename
	)

pure virtual

Starts an async task to create an encrypted backup which will contain the selected items.

Use GetStatus() to keep track of the operation state. If the backup has been created, the file can be found in $ARP_PATH_DATA_DIR$/Services/BackupAndRestore/[filename]

Parameters

name	A name for the backup. The name will be included into the filename.
password	The password which shall be used to protect the backup.
matchesAnyOf	The scope of items to copy into the backup. If empty, all data is selected.
filename	The filename of the backup which will be created.

Returns: Good on success; Any Bad* StatusCode if the backup operation could not be started.

◆ DeleteBackup()

virtual StatusCode Arp::Services::BackupAndRestore::Services::IBackupAndRestoreService::DeleteBackup ( const RscString< 512 > & filename )

pure virtual

Deletes a backup from the device.

Parameters

filename The filename of the backup to delete.

Returns: Good on success; Any Bad* StatusCode if the could not be deleted.

◆ GetAddBackupStatus()

virtual TransferStatus Arp::Services::BackupAndRestore::Services::IBackupAndRestoreService::GetAddBackupStatus ( )

pure virtual

Returns the status of the last AddBackup call.

Returns: The transfer status.

◆ GetBackupBehavior()

virtual BackupAndRestoreBehavior Arp::Services::BackupAndRestore::Services::IBackupAndRestoreService::GetBackupBehavior ( GetBackupBehaviorMatchesAnyOfDelegate matchesAnyOfDelegate )

pure virtual

Returns the behavior for a backup with the selected items.

Parameters

matchesAnyOf The scope of items.

Returns: The behavior.

◆ GetBackupOptions()

virtual void Arp::Services::BackupAndRestore::Services::IBackupAndRestoreService::GetBackupOptions	(	const RscString< 16 > &	locale,
		GetBackupOptionsResultDelegate	resultDelegate
	)

pure virtual

Returns the available backup options.

Parameters

locale The locale to be applied to the name of the option. If it is empty, the default locale is used.

Returns: The list of backup options.

◆ GetBackups()

virtual void Arp::Services::BackupAndRestore::Services::IBackupAndRestoreService::GetBackups ( GetBackupsResultDelegate resultDelegate )

pure virtual

Returns information about the available backups on the device.

Returns: The list of available backups.

◆ GetRestoreBehavior()

virtual BackupAndRestoreBehavior Arp::Services::BackupAndRestore::Services::IBackupAndRestoreService::GetRestoreBehavior ( GetRestoreBehaviorMatchesAnyOfDelegate matchesAnyOfDelegate )

pure virtual

Returns the behavior for a restore with the selected items.

Parameters

matchesAnyOf The scope of items.

Returns: The behavior.

◆ GetRestoreOptions()

virtual void Arp::Services::BackupAndRestore::Services::IBackupAndRestoreService::GetRestoreOptions	(	const RscString< 16 > &	locale,
		GetRestoreOptionsResultDelegate	resultDelegate
	)

pure virtual

Returns the available restore options.

Parameters

locale The locale to be applied to the name of the option. If it is empty, the default locale is used.

Returns: The list of restore options.

◆ GetStatus()

virtual BackupAndRestoreStatus Arp::Services::BackupAndRestore::Services::IBackupAndRestoreService::GetStatus ( )

pure virtual

Returns the current status.

Returns: The current status.

◆ RestoreBackup()

virtual StatusCode Arp::Services::BackupAndRestore::Services::IBackupAndRestoreService::RestoreBackup	(	const RscString< 512 > &	filename,
		const RscSecureString< 128 > &	password,
		RestoreBackupMatchesAnyOfDelegate	matchesAnyOfDelegate
	)

pure virtual

Starts an async task to restore a backup which will restore the selected items.

Use GetStatus() to keep track of the operation state. The backup file must exist at $ARP_PATH_DATA_DIR$/Services/BackupAndRestore/[filename]. Use AddBackup(...) to move the backup file from a different location into the expected directory.

Parameters

filename	The filename of the backup to restore.
password	The password which has been used to protect the backup.
matchesAnyOf	The scope of items to restore from the backup. If empty, all data will be restored.

Returns: Good on success; Any Bad* StatusCode if the restore operation could not be started.

◆ Resume()

virtual StatusCode Arp::Services::BackupAndRestore::Services::IBackupAndRestoreService::Resume ( )

pure virtual

Resets the error state.

Returns: Good on success; Any Bad* StatusCode if resume failed.

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

Arp/Services/BackupAndRestore/Services/IBackupAndRestoreService.hpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ AddBackup()

◆ CreateBackup()

◆ DeleteBackup()

◆ GetAddBackupStatus()

◆ GetBackupBehavior()

◆ GetBackupOptions()

◆ GetBackups()

◆ GetRestoreBehavior()

◆ GetRestoreOptions()

◆ GetStatus()

◆ RestoreBackup()

◆ Resume()