IToiApplicationService Interface Reference


Description

The Application Service is responsible for maintaining the lifecycles of every application registered in the system.

import "IToiApplicationService.idl";

List of all members.

Public Member Functions

void RegisterApplication (in string propertyFilename) raises (TToiInvalidArgumentException)
void ReportStarted (in TToiApplicationId applicationId, in string address) raises (TToiInvalidArgumentException)
void ReportPing (in TToiApplicationId applicationId) raises (TToiInvalidArgumentException)
void Activate (in TToiApplicationId applicationId) raises (TToiInvalidArgumentException)
void ActivateWithUri (in TToiApplicationId applicationId, in string uri, in string mimeType) raises (TToiInvalidArgumentException)
void ActivateWithCommand (in TToiApplicationId applicationId, in string command) raises (TToiInvalidArgumentException)
void Deactivate (in TToiApplicationId applicationId) raises (TToiInvalidArgumentException)
void Kill (in TToiApplicationId applicationId) raises (TToiInvalidArgumentException)
void GetOwnApplicationId (out TToiApplicationId applicationId)
void GetApplicationIds (out TToiApplicationIdSequence applicationIds)
void GetBoolProperty (in TToiApplicationId applicationId, in string property, out boolean value) raises (TToiInvalidArgumentException)
void GetIntProperty (in TToiApplicationId applicationId, in string property, out long value) raises (TToiInvalidArgumentException)
void GetStringProperty (in TToiApplicationId applicationId, in string property, out string value) raises (TToiInvalidArgumentException)
void GetStringSequenceProperty (in TToiApplicationId applicationId, in string property, out TToiPropertyStringSequence values) raises (TToiInvalidArgumentException)
void GetInfo (in TToiApplicationId applicationId, out TToiApplicationInfo info) raises (TToiInvalidArgumentException)
void LoadUri (in string uri, in string mimeType) raises (TToiUnhandledValueException)
void RegisterObserver (in IToiApplicationService::TToiApplicationId applicationId, in string address) raises (TToiInvalidArgumentException)
void ReleaseObserver (in string address) raises (TToiInvalidArgumentException)

Classes

struct  TToiApplicationInfo

Public Types

enum  TToiApplicationState {
  STATE_REGISTERED, STATE_INSTALLING, STATE_INSTALLED, STATE_STARTING,
  STATE_INVISIBLE, STATE_VISIBLE, STATE_ACTIVE, STATE_STOPPED
}
typedef long TToiApplicationId
typedef sequence
< TToiApplicationId
TToiApplicationIdSequence
typedef sequence
< TToiApplicationInfo
TToiApplicationInfoSequence
typedef sequence< string > TToiPropertyStringSequence

Member Typedef Documentation

The application identifier type.

A sequence of application identifiers.

A sequence of application info structure.

A sequence of property string values.


Member Enumeration Documentation

The TToiApplicationState datatype enumerates the different states an application can be in. The application process (or processes) may exist in the system only when in STATE_STARTING, STATE_INVISIBLE, STATE_VISIBLE or STATE_ACTIVE states. This means that it is guaranteed that the application has exited before it enters STATE_STOPPED.

Enumerator:
STATE_REGISTERED 

In STATE_REGISTERED, the application exists only as a simple registration entry containing the basic application properties.

STATE_INSTALLING 

In STATE_INSTALLING, the application's installation package and packages needed by the installation package are being installed. The application enters this state from STATE_REGISTERED. If the installation was successful the application enters STATE_INSTALLED. If the installation failed the application enters STATE_REGISTERED again.

STATE_INSTALLED 

In the STATE_INSTALLED state, the application is installed on the system, ready to be started. The application may enter this state from STATE_INSTALLING or STATE_STOPPED. The application leaves this state either by being started (entering STATE_STARTING) or by being uninstalled (entering STATE_REGISTERED).

STATE_STARTING 

During STATE_STARTING, the application will be started and it will initialize itself to become fully operational. The application leaves this state for one of the running states by registering with the Application Service, using the IToiApplicationService::ReportStarted() method. Which one of the running states STATE_INVISIBLE, STATE_VISIBLE, or STATE_ACTIVE, it enters basically depends on the states of other applications running on the system. If the application fails to register with the Application Service within a configurable time, the application will be stopped.

See also:
IToiApplicationService::ReportStarted()
STATE_INVISIBLE 

In STATE_INVISIBLE, the application is running but it is not visible to the user. In this state the application should preserve computing resources by not doing anything that has the sole purpose of producing output to the screen.

STATE_VISIBLE 
Deprecated:
This state will disappear in TOI 2.1 since support for pop-up applications will disappear

In STATE_VISIBLE, the application is running and some parts, but not all, of it is visible to the user.

STATE_ACTIVE 

In STATE_ACTIVE, the application is running and is the frontmost one visible to the user and receiving all user input.

STATE_STOPPED 

In STATE_STOPPED, the application process (or processes) does no longer exist in the system. The application may get to this state either by exiting in an orderly fashion, crashing, misbehaving in such a way that the Application Service decides to stop it. When the platform has released all resources and there are no references left to the application instance the application will leave STATE_STOPPED. Depending on if the application is configured to restart automatically or not, or if the application should be uninstalled, it will enter STATE_STARTING or STATE_INSTALLED.


Member Function Documentation

void IToiApplicationService::Activate ( in TToiApplicationId  applicationId  )  raises (TToiInvalidArgumentException)

This method changes the state of the given application to STATE_ACTIVE. The currently active application will become visible or invisible and if there is an application that is visible it might become invisible.

Parameters:
applicationId The identifier of the application to make active.
Exceptions:
TToiInvalidArgumentException Raised if the specified application identifier is invalid.
See also:
TToiApplicationState
void IToiApplicationService::ActivateWithCommand ( in TToiApplicationId  applicationId,
in string  command 
) raises (TToiInvalidArgumentException)

This method does the same thing as Activate() but it also tells the newly activated application to execute a command.

Parameters:
applicationId The identifier of the application to make active.
command The command the application shall execute.
Exceptions:
TToiInvalidArgumentException Raised if the specified application identifier is invalid.
See also:
IToiApplicationService::Activate()
IToiApplication::ExecuteCommand()
void IToiApplicationService::ActivateWithUri ( in TToiApplicationId  applicationId,
in string  uri,
in string  mimeType 
) raises (TToiInvalidArgumentException)

This method does the same thing as Activate() but it also tells the newly activated application to load a specific URI.

Parameters:
applicationId The identifier of the application to make active.
uri The URI that the application shall load.
mimeType The MIME type of the uri if known, otherwise empty.
Exceptions:
TToiInvalidArgumentException Raised if the specified application identifier is invalid.
See also:
IToiApplicationService::Activate()
IToiApplication::LoadUri()
void IToiApplicationService::Deactivate ( in TToiApplicationId  applicationId  )  raises (TToiInvalidArgumentException)

This method changes the state of the given application to STATE_INVISIBLE IF it can be determined which application should become active. If it cannot be determined which application should become active, Deactivate() does not change state of any application.

Use this method to make popup applications disappear.

Parameters:
applicationId The identifier of the application to deactivate.
Exceptions:
TToiInvalidArgumentException Raised if the specified application identifier is invalid.
See also:
TToiApplicationState
void IToiApplicationService::GetApplicationIds ( out TToiApplicationIdSequence  applicationIds  ) 

Returns the identifiers for all registered applications.

Return values:
applicationsIds The identifiers of all registered applications.
void IToiApplicationService::GetBoolProperty ( in TToiApplicationId  applicationId,
in string  property,
out boolean  value 
) raises (TToiInvalidArgumentException)

Returns the value of a boolean property for an application.

Parameters:
applicationId The identifier of the application to get a property for.
property The name of the property.
Return values:
value The returned property value.
Exceptions:
TToiInvalidArgumentException Raised if a parameter is invalid.
void IToiApplicationService::GetInfo ( in TToiApplicationId  applicationId,
out TToiApplicationInfo  info 
) raises (TToiInvalidArgumentException)

Returns information about the application.

Parameters:
applicationId The identifier of the application to get a property for.
Return values:
info The returned information struct.
Exceptions:
TToiInvalidArgumentException Raised if the specified application identifier is invalid.
void IToiApplicationService::GetIntProperty ( in TToiApplicationId  applicationId,
in string  property,
out long  value 
) raises (TToiInvalidArgumentException)

Returns the value of an integer property for an application.

Parameters:
applicationId The identifier of the application to get a property for.
property The name of the property.
Return values:
value The returned property value.
Exceptions:
TToiInvalidArgumentException Raised if a parameter is invalid.
void IToiApplicationService::GetOwnApplicationId ( out TToiApplicationId  applicationId  ) 

Returns the calling application's identifier. This function is mainly intended for Javascript since the identifier is also available in the APPLICATION_ID environment variable.

Return values:
applicationId The identifier of the calling application.
void IToiApplicationService::GetStringProperty ( in TToiApplicationId  applicationId,
in string  property,
out string  value 
) raises (TToiInvalidArgumentException)

Returns the value of a string property for an application.

Parameters:
applicationId The identifier of the application to get a property for.
property The name of the property.
Return values:
value The returned property value.
Exceptions:
TToiInvalidArgumentException Raised if a parameter is invalid.
void IToiApplicationService::GetStringSequenceProperty ( in TToiApplicationId  applicationId,
in string  property,
out TToiPropertyStringSequence  values 
) raises (TToiInvalidArgumentException)

Returns the values of a sequence property for an application. Unlike the other property functions it does not throw an exception if the property does not exist, instead it returns an empty sequence.

Parameters:
applicationId The identifier of the application to get a property for.
property The name of the property.
Return values:
values The returned property values.
Exceptions:
TToiInvalidArgumentException Raised if a parameter is invalid.
void IToiApplicationService::Kill ( in TToiApplicationId  applicationId  )  raises (TToiInvalidArgumentException)

Kill an application. This method has no effect if the application is not currently running. If the application is running it will be restarted automatically if the restart property is true. This method is useful in forcing an application to a known initial state.

Parameters:
applicationId The identifier of the application to kill.
Exceptions:
TToiInvalidArgumentException Raised if the specified application identifier is invalid.
void IToiApplicationService::LoadUri ( in string  uri,
in string  mimeType 
) raises (TToiUnhandledValueException)

Call this method to tell the Application Service to load a specific URI. If an application is registered to handle the type of URI, it will be activated and IToiApplication::LoadUri() will be called.

Parameters:
uri The URI to load.
mimeType The MIME type is used to hint the loader about which application to use for loading the URI.
Exceptions:
TToiUnhandledValueException Raised if there is no application that handles the URI or the MIME type.
See also:
IToiApplication::LoadUri()
void IToiApplicationService::RegisterApplication ( in string  propertyFilename  )  raises (TToiInvalidArgumentException)

This method can be called to register new applications.

This is used to dynamically register new applications at runtime.

The applications registered at runtime will automatically be considered to be dynamically downloadable uninstallable applications. In consequence they have to be downloaded and installed before they are started.

Parameters:
propertyFilename The name of the property file of the application.
Exceptions:
TToiInvalidArgumentException Raised when the supplied propertyFilename or property file is invalid.
void IToiApplicationService::RegisterObserver ( in IToiApplicationService::TToiApplicationId  applicationId,
in string  address 
) raises (TToiInvalidArgumentException)

Register an observer of type IToiApplicationObserver. The observer will receive events sent by this IToiApplicationService instance.

Parameters:
applicationId The identifier of the observing application.
address The address where the IToiApplicationService can find an IToiApplicationObserver interface.
Exceptions:
TToiInvalidArgumentException Raised if the specified address is invalid or if the application has already registered itself as an observer with the same address.
See also:
IToiApplicationObserver
void IToiApplicationService::ReleaseObserver ( in string  address  )  raises (TToiInvalidArgumentException)

Release an observer previously registered with RegisterObserver.

Parameters:
address The address where the IToiApplicationService can find the registered IToiApplicationObserver interface.
Exceptions:
TToiInvalidArgumentException Raised if the specified address is invalid.
See also:
IToiApplicationObserver
void IToiApplicationService::ReportPing ( in TToiApplicationId  applicationId  )  raises (TToiInvalidArgumentException)

This method must be called by applications that receive a Ping from the Application Service. If the application does not do so within the time configured in the application properties, it will be terminated and possibly restarted.

Parameters:
applicationId The identifier of the application.
Exceptions:
TToiInvalidArgumentException Raised if the specified application identifier is invalid.
See also:
IToiApplication
void IToiApplicationService::ReportStarted ( in TToiApplicationId  applicationId,
in string  address 
) raises (TToiInvalidArgumentException)

This method must be called by the application when it is initialized and has become fully operational. If the application does not do so within the time configured in the application properties, it will be terminated and possibly restarted.

Parameters:
applicationId The identifier of the application.
address The address where the Application Service can find an IToiApplication interface.
Exceptions:
TToiInvalidArgumentException Raised if the specified application identifier or the address is invalid.
See also:
IToiApplication