The service of the SoftwareUpdate component which provides the feature to update the software of the device and the connected components. The semantics are based on Version 1.03 of OPC UA Part 100: Devices (OPC 10000-100: OPC Unified Architecture). More...

#include <ISoftwareUpdateService.hpp>

Inheritance diagram for Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService:

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

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

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

virtual std::vector< RscString< 64 > >	GetUpdaterList ()=0
	Returns a list of all updaters that are available on the system. More...

virtual StatusCode	GetUpdaterCapabilities (const RscString< 64 > &updaterName, UpdaterCapabilities &capabilities)=0
	Returns information about the capabilities and behavior of the specified updater. More...

virtual StatusCode	GetUpdateBehavior (const RscString< 64 > &updaterName, const RscString< 512 > &componentId, const RscString< 512 > &manufacturerUri, const RscString< 512 > &softwareRevision, const std::vector< RscString< 512 > > &patchIdentifiers, UpdateBehavior &updateBehavior)=0
	Returns the update behavior of either the Pending or Fallback SoftwareVersionType. More...

virtual StatusCode	GetStatus (const RscString< 64 > &updaterName, const RscString< 512 > &componentId, SoftwareUpdateStatus &status)=0
	Returns the update status of the component. More...

virtual StatusCode	GetSoftwareVersion (const RscString< 64 > &updaterName, const RscString< 512 > &componentId, SoftwareVersionFileType fileType, SoftwareVersionType &version)=0
	Returns information about the software version for a specific file type (fallback, current, pending). More...

virtual StatusCode	SetSoftwarePackage (const RscString< 64 > &updaterName, const RscString< 512 > &componentId, SoftwareVersionFileType fileType, const RscString< 512 > &fileName, boolean async, RscString< 512 > &errorMessage)=0
	Passes a software package to the updater and performs validation. The validation can take a certain amount of time. Asynchronous execution is therefore possible. The status of the asynchronous operation can be queried via GetTranferStatus. More...

virtual StatusCode	GetSoftwarePackage (const RscString< 64 > &updaterName, const RscString< 512 > &componentId, SoftwareVersionFileType fileType, const RscString< 512 > &fileName, boolean async, RscString< 512 > &errorMessage)=0
	The updater creates a software package for the specified version type and saves the file at the specified location. The ownership of the file is transferred to the client. More...

virtual StatusCode	GetTransferStatus (const RscString< 64 > &updaterName, const RscString< 512 > &componentId, TransferStatus &status)=0
	Returns the status of the last or ongoing transfer operation. More...

virtual StatusCode	Prepare (const RscString< 64 > &updaterName, const RscString< 512 > &componentId)=0
	Prepares the PLCnext device for updates. More...

virtual StatusCode	ForcePrepare (const RscString< 64 > &updaterName, const RscString< 512 > &componentId)=0
	Forces the transition from Preparing to the PreparedForUpdate state. This might be necessary if the coupled application does not respond. More...

virtual StatusCode	Abort (const RscString< 64 > &updaterName, const RscString< 512 > &componentId)=0
	Aborts the preparation or resuming process which results in the transition to the Idle state. More...

virtual StatusCode	ResumePrepare (const RscString< 64 > &updaterName, const RscString< 512 > &componentId)=0
	Resumes from the PreparedForUpdate state. More...

virtual StatusCode	SetUpdateKey (const RscString< 64 > &updaterName, const RscString< 512 > &componentId, const RscSecureString< 512 > &updateKey)=0
	Sets a key / password that should be used for the firmware update. More...

virtual StatusCode	SetInstallationDelay (const RscString< 64 > &updaterName, const RscString< 512 > &componentId, int64 installationDelay)=0
	Sets the installation delay for the installation of a software package. More...

virtual StatusCode	GetInstallationDelay (const RscString< 64 > &updaterName, const RscString< 512 > &componentId, int64 &installationDelay)=0
	Returns the installation delay. More...

virtual StatusCode	InstallSoftwarePackage (const RscString< 64 > &updaterName, const RscString< 512 > &componentId, const RscString< 512 > &manufacturerUri, const RscString< 512 > &softwareRevision, const std::vector< RscString< 512 > > &patchIdentifiers, boolean autoResumePrepareForUpdate)=0
	Starts the installation. More...

virtual StatusCode	ResumeInstall (const RscString< 64 > &updaterName, const RscString< 512 > &componentId)=0
	If the installation is in the Error state, the resume method will set the installation state machine back to idle. More...

virtual int64	GetConfirmationTimeout ()=0
	Returns the timeout for the confirmation feature. Represents the maximum time that the client may need to reconnect and call the Confirm Method. More...

virtual StatusCode	SetConfirmationTimeout (int64 timeout)=0
	Sets the timeout for the confirmation feature. The timeout must be set by a client to a value greater than 0 to enable the confirmation feature. More...

virtual StatusCode	Confirm ()=0
	Confirms that the device can keep the update and must not revert to the previous version. More...

virtual StatusCode	Clear (const RscString< 64 > &updaterName, const RscString< 512 > &componentId, SoftwareVersionFileType fileType)=0
	Clears the software version type. / Removes the software package. 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 of the SoftwareUpdate component which provides the feature to update the software of the device and the connected components. The semantics are based on Version 1.03 of OPC UA Part 100: Devices (OPC 10000-100: OPC Unified Architecture).

The service provides access to various updaters that can be used to update different components/software. The components of an updater are identified by an ID that is defined by the updater.

This service is defined in library Arp.Services.SoftwareUpdate.

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

Member Function Documentation

◆ Abort()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::Abort	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId
	)

pure virtual

Aborts the preparation or resuming process which results in the transition to the Idle state.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ Clear()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::Clear	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId,
		SoftwareVersionFileType	fileType
	)

pure virtual

Clears the software version type. / Removes the software package.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.
fileType	The file type of the software version.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ Confirm()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::Confirm ( )

pure virtual

Confirms that the device can keep the update and must not revert to the previous version.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ ForcePrepare()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::ForcePrepare	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId
	)

pure virtual

Forces the transition from Preparing to the PreparedForUpdate state. This might be necessary if the coupled application does not respond.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ GetConfirmationTimeout()

virtual int64 Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::GetConfirmationTimeout ( )

pure virtual

Returns the timeout for the confirmation feature. Represents the maximum time that the client may need to reconnect and call the Confirm Method.

Returns: The confirmation timeout in milliseconds.

◆ GetInstallationDelay()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::GetInstallationDelay	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId,
		int64 &	installationDelay
	)

pure virtual

Returns the installation delay.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.
installationDelay	The delay in milliseconds before the installation shall start.

Returns: The installation delay in milliseconds.

◆ GetSoftwarePackage()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::GetSoftwarePackage	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId,
		SoftwareVersionFileType	fileType,
		const RscString< 512 > &	fileName,
		boolean	async,
		RscString< 512 > &	errorMessage
	)

pure virtual

The updater creates a software package for the specified version type and saves the file at the specified location. The ownership of the file is transferred to the client.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.
fileType	The file type of the software version.
fileName	The location must be writeable by the component and the file must not exist.
async	Whether the operation shall be executed async. If true, the status must be read with GetTransferStatus.
errorMessage	Contains a message in case of an error.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ GetSoftwareVersion()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::GetSoftwareVersion	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId,
		SoftwareVersionFileType	fileType,
		SoftwareVersionType &	version
	)

pure virtual

Returns information about the software version for a specific file type (fallback, current, pending).

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.
fileType	The file type of the software version.
version	The software version of the specified type.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ GetStatus()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::GetStatus	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId,
		SoftwareUpdateStatus &	status
	)

pure virtual

Returns the update status of the component.

Parameters

updaterName	The name of the updater to use.
componentId	The ID of the component.
status	The current update status.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ GetTransferStatus()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::GetTransferStatus	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId,
		TransferStatus &	status
	)

pure virtual

Returns the status of the last or ongoing transfer operation.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.
status	Status information of the transfer operation.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ GetUpdateBehavior()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::GetUpdateBehavior	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId,
		const RscString< 512 > &	manufacturerUri,
		const RscString< 512 > &	softwareRevision,
		const std::vector< RscString< 512 > > &	patchIdentifiers,
		UpdateBehavior &	updateBehavior
	)

pure virtual

Returns the update behavior of either the Pending or Fallback SoftwareVersionType.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.
manufacturerUri	The manufacturer URI of the version that shall be installed.
softwareRevision	The software revision that shall be installed.
patchIdentifiers	The patch identifiers of the version that shall be installed.
updateBehavior	The update behavior.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ GetUpdaterCapabilities()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::GetUpdaterCapabilities	(	const RscString< 64 > &	updaterName,
		UpdaterCapabilities &	capabilities
	)

pure virtual

Returns information about the capabilities and behavior of the specified updater.

Parameters

updaterName	The name of the updater.
capabilities	A bit map based on enumerations with the requested capabilities.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ GetUpdaterList()

virtual std::vector< RscString< 64 > > Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::GetUpdaterList ( )

pure virtual

Returns a list of all updaters that are available on the system.

Returns: The list of updaters.

◆ InstallSoftwarePackage()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::InstallSoftwarePackage	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId,
		const RscString< 512 > &	manufacturerUri,
		const RscString< 512 > &	softwareRevision,
		const std::vector< RscString< 512 > > &	patchIdentifiers,
		boolean	autoResumePrepareForUpdate
	)

pure virtual

Starts the installation.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.
manufacturerUri	The manufacturer URI of the version that shall be installed.
softwareRevision	The software revision that shall be installed.
patchIdentifiers	The patch identifiers of the version that shall be installed.
autoResumePrepareForUpdate	Whether the PrepareForUpdateState shall automatically change to Idle after installation.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ Prepare()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::Prepare	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId
	)

pure virtual

Prepares the PLCnext device for updates.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ ResumeInstall()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::ResumeInstall	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId
	)

pure virtual

If the installation is in the Error state, the resume method will set the installation state machine back to idle.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ ResumePrepare()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::ResumePrepare	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId
	)

pure virtual

Resumes from the PreparedForUpdate state.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ SetConfirmationTimeout()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::SetConfirmationTimeout ( int64 timeout )

pure virtual

Sets the timeout for the confirmation feature. The timeout must be set by a client to a value greater than 0 to enable the confirmation feature.

Parameters

timeout The timeout in milliseconds until the device has to wait before the update is reverted.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ SetInstallationDelay()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::SetInstallationDelay	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId,
		int64	installationDelay
	)

pure virtual

Sets the installation delay for the installation of a software package.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.
installationDelay	The delay in milliseconds before the installation shall start.

Returns: Good on success or a bad StatusCode if an error occurred.

This update behavior must be supported by the updater.

◆ SetSoftwarePackage()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::SetSoftwarePackage	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId,
		SoftwareVersionFileType	fileType,
		const RscString< 512 > &	fileName,
		boolean	async,
		RscString< 512 > &	errorMessage
	)

pure virtual

Passes a software package to the updater and performs validation. The validation can take a certain amount of time. Asynchronous execution is therefore possible. The status of the asynchronous operation can be queried via GetTranferStatus.

The file is moved to a different location on the filesystem by the module.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.
fileType	The file type of the software version.
fileName	The name of the software package file which is located on the system.
async	Whether the operation shall be executed async. If true, the status must be read with GetTransferStatus.
errorMessage	Contains a message in case of an error.

Returns: Good on success or a bad StatusCode if an error occurred.

◆ SetUpdateKey()

virtual StatusCode Arp::Services::SoftwareUpdate::Services::ISoftwareUpdateService::SetUpdateKey	(	const RscString< 64 > &	updaterName,
		const RscString< 512 > &	componentId,
		const RscSecureString< 512 > &	updateKey
	)

pure virtual

Sets a key / password that should be used for the firmware update.

Parameters

updaterName	The name of the updater.
componentId	The ID of the component.
updateKey	The key / password.

Returns: Good on success or a bad StatusCode if an error occurred.

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

Arp/Services/SoftwareUpdate/Services/ISoftwareUpdateService.hpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ Abort()

◆ Clear()

◆ Confirm()

◆ ForcePrepare()

◆ GetConfirmationTimeout()

◆ GetInstallationDelay()

◆ GetSoftwarePackage()

◆ GetSoftwareVersion()

◆ GetStatus()

◆ GetTransferStatus()

◆ GetUpdateBehavior()

◆ GetUpdaterCapabilities()

◆ GetUpdaterList()

◆ InstallSoftwarePackage()

◆ Prepare()

◆ ResumeInstall()

◆ ResumePrepare()

◆ SetConfirmationTimeout()

◆ SetInstallationDelay()

◆ SetSoftwarePackage()

◆ SetUpdateKey()