This services represents the RSC-Interface for the AppManager service component More...

#include <IAppManagerService.hpp>

Inheritance diagram for Arp::Services::AppManager::Services::IAppManagerService:

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

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

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

virtual AppManagerServiceError	ListInstalledApps (std::vector< AppInfo > &list)=0
	Lists all installed PLCnext Technology Apps by their identifier. More...

virtual AppManagerServiceError	InstallApp (const RscString< 512 > &filename, const RscString< 256 > &appIdentifier="")=0
	Installs a PLCnext Technology App from an app container file located on the controller (path specified by filename ). May also be used to update an already installed app. More...

virtual AppManagerServiceError	UnInstallApp (const RscString< 256 > &appIdentifier)=0
	Uninstalls an app specified by its identifier. More...

virtual AppManagerServiceError	StartApp (const RscString< 256 > &appIdentifier)=0
	Starts the PLCnext application specified by appIdentifier . The app may start asynchronously; during startup the per‑app status contains Arp.Services.AppManager.Services.AppStatus.Starting. The app is considered fully started when the status is Arp.Services.AppManager.Services.AppStatus.Started. More...

virtual AppManagerServiceError	StopApp (const RscString< 256 > &appIdentifier)=0
	Stops the PLCnext application specified by appIdentifier . The app may stop asynchronously; during shutdown the per‑app status contains Arp.Services.AppManager.Services.AppStatus.Stopping. The app is considered fully stopped when the status is Arp.Services.AppManager.Services.AppStatus.Stopped. More...

virtual AppManagerServiceError	GetAppStatus (const RscString< 256 > &appIdentifier, AppStatus &status)=0
	Reads the status of the app specified by appIdentifier . More...

virtual AppManagerServiceError	GetAppsStatus (const std::vector< RscString< 256 > > &appIdentifiers, std::vector< AppStatus > &status)=0
	Reads the statuses of apps specified by appIdentifiers . If an identifier no longer exists, an error code is returned and the corresponding status in the result array is Arp.Services.AppManager.Services.AppStatus.None. More...

virtual AppManagerServiceError	GetAppInfo (const RscString< 256 > &appIdentifier, AppInfo &appInfo)=0
	Reads the app information for the app specified by appIdentifier . More...

virtual AppManagerServiceError	GetExtendedAppInfo (const RscString< 256 > &appIdentifier, const RscString< 256 > &extendedInfoKey, RscVariant< 256 > &infoItem)=0
	Retrieves extended information for the specified application based on the provided key. More...

virtual AppManagerStatus	GetAppManagerStatus ()=0
	Reads the status of the App Manager. More...

virtual AppManagerServiceError	EnableInstallationMode (const RscString< 256 > &callerName)=0
	Enables the installation mode of the App Manager using the specified user name. Only with active installation mode is it possible to call the following methods: Arp.Services.AppManager.Services.IAppManagerService.InstallApp, Arp.Services.AppManager.Services.IAppManagerService.UnInstallApp, Arp.Services.AppManager.Services.IAppManagerService.StartApp, Arp.Services.AppManager.Services.IAppManagerService.StopApp. If these methods are called with installation mode disabled, they return `InstallationModeInactive`. More...

virtual AppManagerServiceError	DisableInstallationMode (boolean autoRestartDisabled=false)=0
	Disables the installation mode of the App Manager. If a reboot is required by previous install/start/stop operations, it is performed right after this returns unless explicitly disabled. Call this method only when the App Manager status is Arp.Services.AppManager.Services.AppManagerStatus.Ready. More...

virtual AppManagerServiceError	GetExtendedAppManagerInfo (const RscString< 256 > &extendedInfoKey, RscVariant< 256 > &infoItem)=0
	Retrieves extended App Manager information based on the provided key. 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

This services represents the RSC-Interface for the AppManager service component

This service provides methods for managing PLCnext Technology Apps installed on the target.

Operational model and asynchronous behavior

Serialization of management actions: The App Manager processesonly one app management operation at a time. While the manager is in any non-Arp.Services.AppManager.Services.AppManagerStatus.Ready state (e.g. Arp.Services.AppManager.Services.AppManagerStatus.InstallingApp, Arp.Services.AppManager.Services.AppManagerStatus.StartingApp), all other management calls (Arp.Services.AppManager.Services.IAppManagerService.InstallApp, Arp.Services.AppManager.Services.IAppManagerService.UnInstallApp, Arp.Services.AppManager.Services.IAppManagerService.StartApp, Arp.Services.AppManager.Services.IAppManagerService.StopApp) are rejected. Clients must wait untilArp.Services.AppManager.Services.AppManagerStatus.Ready is reported before issuing the next management action.
All app management actions Arp.Services.AppManager.Services.IAppManagerService.InstallApp, Arp.Services.AppManager.Services.IAppManagerService.UnInstallApp, Arp.Services.AppManager.Services.IAppManagerService.StartApp, and Arp.Services.AppManager.Services.IAppManagerService.StopApp are asynchronous. A successful return with error code Arp.Services.AppManager.Services.AppManagerErrorCode.None only indicates that the operation was accepted and initiated; completion must be observed via status polling.
To perform any app management action, installation mode must be enabled via Arp.Services.AppManager.Services.IAppManagerService.EnableInstallationMode. Calling these methods with installation mode disabled returns an error indicating InstallationModeInactive. The App Manager exposes the Arp.Services.AppManager.Services.AppManagerStatus.InstallationModeEnabled flag to indicate the mode state.
The return value of management methods is Arp.Services.AppManager.Services.AppManagerServiceError. If the embedded error code equals AppManagerErrorCode.None, then the App Manager found no fundamental issues (e.g., configuration or mount problems) and the asynchronous operation was started successfully.
On acceptance, the App Manager transitions its state to Arp.Services.AppManager.Services.AppManagerStatus.InstallingApp, Arp.Services.AppManager.Services.AppManagerStatus.UninstallingApp, Arp.Services.AppManager.Services.AppManagerStatus.StartingApp, or Arp.Services.AppManager.Services.AppManagerStatus.StoppingApp. When the operation is fully done, it returns to Arp.Services.AppManager.Services.AppManagerStatus.Ready.
Client applications must poll Arp.Services.AppManager.Services.IAppManagerService.GetAppManagerStatus until Arp.Services.AppManager.Services.AppManagerStatus.Ready is observed (e.g., every 250 ms) before taking any follow‑up action.
After the manager returns to Arp.Services.AppManager.Services.AppManagerStatus.Ready, check whether Arp.Services.AppManager.Services.AppManagerStatus.InstallError is set. If set, call Arp.Services.AppManager.Services.IAppManagerService.GetExtendedAppManagerInfo with the keys LastInstallErrorCode and LastInstallErrorMessage to obtain the precise error code (Arp.Services.AppManager.Services.AppManagerErrorCode) and description. These values are reset on the next install/uninstall action.
Start/Stop errors are app‑specific: read them via Arp.Services.AppManager.Services.IAppManagerService.GetAppStatus. In error cases, the app status exposes Arp.Services.AppManager.Services.AppStatus.StartError and/or Arp.Services.AppManager.Services.AppStatus.StopError. To retrieve error details (code and message) for the last async start/stop operation, call Arp.Services.AppManager.Services.IAppManagerService.GetExtendedAppInfo with CurrentAppErrorCode and CurrentAppErrorMessage. These are cleared on the next start/stop action.
Error flags are reset by performing the corresponding operation again: installation errors on the next install/uninstall, and start/stop errors on the next start/stop of the app.
End of session: call Arp.Services.AppManager.Services.IAppManagerService.DisableInstallationMode when Arp.Services.AppManager.Services.AppManagerStatus.Ready is reported. If a reboot is required (Arp.Services.AppManager.Services.AppManagerStatus.RestartRequired), the manager may schedule it immediately unless the parameter 'autoRestartDisabled' is set. A reboot is required and will be performed if any app , if at least one started or stopped app requires a restart. Remark: parameter 'autoRestartDisabled' is ignored in current implementation.

Impact on real-time behaviour: Executing app management actions (Arp.Services.AppManager.Services.IAppManagerService.InstallApp, Arp.Services.AppManager.Services.IAppManagerService.UnInstallApp, Arp.Services.AppManager.Services.IAppManagerService.StartApp, Arp.Services.AppManager.Services.IAppManagerService.StopApp) may adversely affect the system's real-time behavior and can cause real-time violations. These operations must not be executed during productive operation.

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

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

Member Function Documentation

◆ DisableInstallationMode()

virtual AppManagerServiceError Arp::Services::AppManager::Services::IAppManagerService::DisableInstallationMode ( boolean autoRestartDisabled = false )

pure virtual

Disables the installation mode of the App Manager. If a reboot is required by previous install/start/stop operations, it is performed right after this returns unless explicitly disabled. Call this method only when the App Manager status is Arp.Services.AppManager.Services.AppManagerStatus.Ready.

Parameters

autoRestartDisabled If true, prevents automatic restart even if required.

Returns

AppManagerErrorCode.None — no reboot is required/performed.
AppManagerErrorCode.RestartScheduled — a reboot will be performed.
AppManagerErrorCode.InstallationModeInactive — installation mode was not active.

◆ EnableInstallationMode()

virtual AppManagerServiceError Arp::Services::AppManager::Services::IAppManagerService::EnableInstallationMode ( const RscString< 256 > & callerName )

pure virtual

Enables the installation mode of the App Manager using the specified user name. Only with active installation mode is it possible to call the following methods: Arp.Services.AppManager.Services.IAppManagerService.InstallApp, Arp.Services.AppManager.Services.IAppManagerService.UnInstallApp, Arp.Services.AppManager.Services.IAppManagerService.StartApp, Arp.Services.AppManager.Services.IAppManagerService.StopApp. If these methods are called with installation mode disabled, they return InstallationModeInactive.

Parameters

callerName The name of the user enabling installation mode.

Returns

AppManagerErrorCode.None — the installation mode was activated (not acquired by another component).
AppManagerErrorCode.InstallationModeActive — the installation mode is already active.

Behavior: Activates installation mode if not already active. The flag Arp.Services.AppManager.Services.AppManagerStatus.InstallationModeEnabled indicates the current mode.

◆ GetAppInfo()

virtual AppManagerServiceError Arp::Services::AppManager::Services::IAppManagerService::GetAppInfo	(	const RscString< 256 > &	appIdentifier,
		AppInfo &	appInfo
	)

pure virtual

Reads the app information for the app specified by appIdentifier .

Parameters

appIdentifier	The app identifier.
appInfo	On return, contains the Arp.Services.AppManager.Services.AppInfo for the app.

Returns: Arp.Services.AppManager.Services.AppManagerServiceError.

◆ GetAppManagerStatus()

virtual AppManagerStatus Arp::Services::AppManager::Services::IAppManagerService::GetAppManagerStatus ( )

pure virtual

Reads the status of the App Manager.

Returns: Arp.Services.AppManager.Services.AppManagerStatus.

Arp.Services.AppManager.Services.AppManagerStatus is a bit field. Use Arp.Services.AppManager.Services.AppManagerStatus.StateMask (0x3F) to extract the primary state and Arp.Services.AppManager.Services.AppManagerStatus.FlagsMask to test flags including Arp.Services.AppManager.Services.AppManagerStatus.InstallationModeEnabled, Arp.Services.AppManager.Services.AppManagerStatus.RestartRequired, and Arp.Services.AppManager.Services.AppManagerStatus.InstallError.

◆ GetAppsStatus()

virtual AppManagerServiceError Arp::Services::AppManager::Services::IAppManagerService::GetAppsStatus	(	const std::vector< RscString< 256 > > &	appIdentifiers,
		std::vector< AppStatus > &	status
	)

pure virtual

Reads the statuses of apps specified by appIdentifiers . If an identifier no longer exists, an error code is returned and the corresponding status in the result array is Arp.Services.AppManager.Services.AppStatus.None.

Parameters

appIdentifiers	The app identifiers.
status	On return, contains the Arp.Services.AppManager.Services.AppStatus values for the requested apps.

Returns: Arp.Services.AppManager.Services.AppManagerServiceError.

Arp.Services.AppManager.Services.AppStatus is a bit field. Use Arp.Services.AppManager.Services.AppStatus.StateMask and Arp.Services.AppManager.Services.AppStatus.FlagsMask for parsing.

◆ GetAppStatus()

virtual AppManagerServiceError Arp::Services::AppManager::Services::IAppManagerService::GetAppStatus	(	const RscString< 256 > &	appIdentifier,
		AppStatus &	status
	)

pure virtual

Reads the status of the app specified by appIdentifier .

Parameters

appIdentifier	The app identifier.
status	On return, contains the Arp.Services.AppManager.Services.AppStatus of the app.

Returns: Arp.Services.AppManager.Services.AppManagerServiceError.

Arp.Services.AppManager.Services.AppStatus is a bit field. Use Arp.Services.AppManager.Services.AppStatus.StateMask (0x3F) to extract the primary state and Arp.Services.AppManager.Services.AppStatus.FlagsMask for flags such as Arp.Services.AppManager.Services.AppStatus.StartError or Arp.Services.AppManager.Services.AppStatus.StopError.

◆ GetExtendedAppInfo()

virtual AppManagerServiceError Arp::Services::AppManager::Services::IAppManagerService::GetExtendedAppInfo	(	const RscString< 256 > &	appIdentifier,
		const RscString< 256 > &	extendedInfoKey,
		RscVariant< 256 > &	infoItem
	)

pure virtual

Retrieves extended information for the specified application based on the provided key.

Parameters

appIdentifier	The identifier of the application.
extendedInfoKey	The key specifying the type of extended information to retrieve.
infoItem	On return, contains the retrieved data if successful.

Supported keys:

AppRequiresReboot — indicates whether the app requires a reboot for start/stop.
CurrentAppErrorCode — Arp.Services.AppManager.Services.AppManagerErrorCode of the last error in an async start/stop operation (reset on the next start/stop).
CurrentAppErrorMessage — human‑readable message of the last async start/stop error (reset on the next start/stop).

Returns: Arp.Services.AppManager.Services.AppManagerServiceError.

◆ GetExtendedAppManagerInfo()

virtual AppManagerServiceError Arp::Services::AppManager::Services::IAppManagerService::GetExtendedAppManagerInfo	(	const RscString< 256 > &	extendedInfoKey,
		RscVariant< 256 > &	infoItem
	)

pure virtual

Retrieves extended App Manager information based on the provided key.

Parameters

extendedInfoKey	The key specifying the type of extended information to retrieve.
infoItem	On return, contains the retrieved data if successful.

Supported keys:

LastInstallErrorCode — Arp.Services.AppManager.Services.AppManagerErrorCode of the last async install/uninstall error; reset to AppManagerErrorCode.None on next install/uninstall.
LastInstallErrorMessage — message of the last async install/uninstall error; reset to empty string on next install/uninstall.

Returns: Arp.Services.AppManager.Services.AppManagerServiceError.

◆ InstallApp()

virtual AppManagerServiceError Arp::Services::AppManager::Services::IAppManagerService::InstallApp	(	const RscString< 512 > &	filename,
		const RscString< 256 > &	appIdentifier = `""`
	)

pure virtual

Installs a PLCnext Technology App from an app container file located on the controller (path specified by filename ). May also be used to update an already installed app.

Parameters

filename	Path to the app container file on the controller. Do not delete the file until the App Manager is Arp.Services.AppManager.Services.AppManagerStatus.Ready again.
appIdentifier	Optional app identifier. If specified, it is validated against the identifier in the container. If they do not match, the call fails. A unique identifier of a PLCnext Technology App, assigned by the PLCnext Store during app creation. It consists of the Firm Code and the Product Code. See PLCnext App Metadata documentation .

Returns: Arp.Services.AppManager.Services.AppManagerServiceError indicating acceptance or failure to start the asynchronous installation.

Preconditions:

Installation mode must be enabled.
App Manager status must beArp.Services.AppManager.Services.AppManagerStatus.Ready. See Operational model and asynchronous behavior.

Concurrency: This method can only be called when the App Manager is in stateArp.Services.AppManager.Services.AppManagerStatus.Ready. See Operational model and asynchronous behavior for details.

State transitions: Arp.Services.AppManager.Services.AppManagerStatus.Ready → Arp.Services.AppManager.Services.AppManagerStatus.InstallingApp → Arp.Services.AppManager.Services.AppManagerStatus.Ready.

Polling: Poll Arp.Services.AppManager.Services.IAppManagerService.GetAppManagerStatus (e.g., every 250 ms) until Arp.Services.AppManager.Services.AppManagerStatus.Ready.

Error reporting: If after completion Arp.Services.AppManager.Services.AppManagerStatus.InstallError is set, retrieve LastInstallErrorCode and LastInstallErrorMessage via Arp.Services.AppManager.Services.IAppManagerService.GetExtendedAppManagerInfo. These are reset on the next install/uninstall.

◆ ListInstalledApps()

virtual AppManagerServiceError Arp::Services::AppManager::Services::IAppManagerService::ListInstalledApps ( std::vector< AppInfo > & list )

pure virtual

Lists all installed PLCnext Technology Apps by their identifier.

Parameters

list	After the method call, contains a list of the AppInfo structure Arp.Services.AppManager.Services.AppInfo.

Returns

Arp.Services.AppManager.Services.AppManagerServiceError:

AppManagerServiceError::None — no error occurred.
Otherwise — error code with message.

◆ StartApp()

virtual AppManagerServiceError Arp::Services::AppManager::Services::IAppManagerService::StartApp ( const RscString< 256 > & appIdentifier )

pure virtual

Starts the PLCnext application specified by appIdentifier . The app may start asynchronously; during startup the per‑app status contains Arp.Services.AppManager.Services.AppStatus.Starting. The app is considered fully started when the status is Arp.Services.AppManager.Services.AppStatus.Started.

Parameters

appIdentifier The identifier of the app to be started A unique identifier of a PLCnext Technology App, assigned by the PLCnext Store during app creation. It consists of the Firm Code and the Product Code. See PLCnext App Metadata documentation .

Returns: Arp.Services.AppManager.Services.AppManagerServiceError indicating acceptance or failure to start the asynchronous operation.

Preconditions:

Installation mode must be enabled.
App Manager status must beArp.Services.AppManager.Services.AppManagerStatus.Ready. See Operational model and asynchronous behavior.

Concurrency: This method can only be called when the App Manager is in stateArp.Services.AppManager.Services.AppManagerStatus.Ready. See Operational model and asynchronous behavior for details.

State transitions (manager): Arp.Services.AppManager.Services.AppManagerStatus.StartingApp → Arp.Services.AppManager.Services.AppManagerStatus.Ready.

State transitions (app): Arp.Services.AppManager.Services.AppStatus.Starting → Arp.Services.AppManager.Services.AppStatus.Started.

Polling: Poll Arp.Services.AppManager.Services.IAppManagerService.GetAppManagerStatus to Arp.Services.AppManager.Services.AppManagerStatus.Ready, then confirm per‑app state with Arp.Services.AppManager.Services.IAppManagerService.GetAppStatus.

Error reporting: If the last start failed, Arp.Services.AppManager.Services.AppStatus.StartError is set. Retrieve details via Arp.Services.AppManager.Services.IAppManagerService.GetExtendedAppInfo using keys CurrentAppErrorCode and CurrentAppErrorMessage. Reset occurs on the next start/stop.

◆ StopApp()

virtual AppManagerServiceError Arp::Services::AppManager::Services::IAppManagerService::StopApp ( const RscString< 256 > & appIdentifier )

pure virtual

Stops the PLCnext application specified by appIdentifier . The app may stop asynchronously; during shutdown the per‑app status contains Arp.Services.AppManager.Services.AppStatus.Stopping. The app is considered fully stopped when the status is Arp.Services.AppManager.Services.AppStatus.Stopped.

Parameters

appIdentifier The identifier of the app to be stopped A unique identifier of a PLCnext Technology App, assigned by the PLCnext Store during app creation. It consists of the Firm Code and the Product Code. See PLCnext App Metadata documentation .

Returns: Arp.Services.AppManager.Services.AppManagerServiceError indicating acceptance or failure to start the asynchronous operation.

Preconditions:

Installation mode must be enabled.
App Manager status must beArp.Services.AppManager.Services.AppManagerStatus.Ready. See Operational model and asynchronous behavior.

State transitions (manager): Arp.Services.AppManager.Services.AppManagerStatus.StoppingApp → Arp.Services.AppManager.Services.AppManagerStatus.Ready.

State transitions (app): Arp.Services.AppManager.Services.AppStatus.Stopping → Arp.Services.AppManager.Services.AppStatus.Stopped.

Polling: Same as Arp.Services.AppManager.Services.IAppManagerService.StartApp; confirm per‑app state with Arp.Services.AppManager.Services.IAppManagerService.GetAppStatus.

Error reporting: If the last stop failed, Arp.Services.AppManager.Services.AppStatus.StopError is set. Retrieve details via Arp.Services.AppManager.Services.IAppManagerService.GetExtendedAppInfo using keys CurrentAppErrorCode and CurrentAppErrorMessage. Reset occurs on the next start/stop.

◆ UnInstallApp()

virtual AppManagerServiceError Arp::Services::AppManager::Services::IAppManagerService::UnInstallApp ( const RscString< 256 > & appIdentifier )

pure virtual

Uninstalls an app specified by its identifier.

Parameters

appIdentifier The identifier of the app to be uninstalled A unique identifier of a PLCnext Technology App, assigned by the PLCnext Store during app creation. It consists of the Firm Code and the Product Code. See PLCnext App Metadata documentation .

Returns: Arp.Services.AppManager.Services.AppManagerServiceError indicating acceptance or failure to start the asynchronous uninstallation.

Preconditions:

Installation mode must be enabled.
App Manager status must beArp.Services.AppManager.Services.AppManagerStatus.Ready. See Operational model and asynchronous behavior.

Concurrency: This method can only be called when the App Manager is in stateArp.Services.AppManager.Services.AppManagerStatus.Ready. See Operational model and asynchronous behavior for details.

State transitions: Arp.Services.AppManager.Services.AppManagerStatus.UninstallingApp → Arp.Services.AppManager.Services.AppManagerStatus.Ready.

Polling & errors: Same pattern as Arp.Services.AppManager.Services.IAppManagerService.InstallApp; consult Arp.Services.AppManager.Services.IAppManagerService.GetExtendedAppManagerInfo if Arp.Services.AppManager.Services.AppManagerStatus.InstallError is set after completion.

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

Arp/Services/AppManager/Services/IAppManagerService.hpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ DisableInstallationMode()

◆ EnableInstallationMode()

◆ GetAppInfo()

◆ GetAppManagerStatus()

◆ GetAppsStatus()

◆ GetAppStatus()

◆ GetExtendedAppInfo()

◆ GetExtendedAppManagerInfo()

◆ InstallApp()

◆ ListInstalledApps()

◆ StartApp()

◆ StopApp()

◆ UnInstallApp()