Description

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

Service:: This is a service and can be accessed through toi.applicationService

import "ToiApplicationService.idl";

Public Member Functions
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)
TToiApplicationId	getOwnApplicationId ()
TToiApplicationIdSequence	getApplicationIds ()
boolean	getBoolProperty (in TToiApplicationId applicationId, in string property) raises (TToiInvalidArgumentException)
long	getIntProperty (in TToiApplicationId applicationId, in string property) raises (TToiInvalidArgumentException)
string	getStringProperty (in TToiApplicationId applicationId, in string property) raises (TToiInvalidArgumentException)
TToiPropertyStringSequence	getStringSequenceProperty (in TToiApplicationId applicationId, in string property) raises (TToiInvalidArgumentException)
ToiApplicationServiceApplicationInfo	getInfo (in TToiApplicationId applicationId) raises (TToiInvalidArgumentException)
void	loadUri (in string uri, in string mimeType) raises (TToiUnhandledValueException)
void	addEventListener (in long type, in ToiEventListener listener) raises (TToiInvalidArgumentException)
void	removeEventListener (in long type, in ToiEventListener listener) raises (TToiInvalidArgumentException)
Public Attributes
Events
const long	ON_STATE_CHANGED = 200
TToiApplicationState
const TToiApplicationState	STATE_REGISTERED = 0
const TToiApplicationState	STATE_INSTALLING = 1
const TToiApplicationState	STATE_INSTALLED = 2
const TToiApplicationState	STATE_STARTING = 3
const TToiApplicationState	STATE_INVISIBLE = 4
const TToiApplicationState	STATE_VISIBLE = 5
const TToiApplicationState	STATE_ACTIVE = 6
const TToiApplicationState	STATE_STOPPED = 7
Public Types
typedef long	TToiApplicationState
typedef long	TToiApplicationId
typedef sequence < TToiApplicationId >	TToiApplicationIdSequence
typedef sequence < ToiApplicationServiceApplicationInfo >	TToiApplicationInfoSequence
typedef sequence< string >	TToiPropertyStringSequence

Member Typedef Documentation

typedef long ToiApplicationService::TToiApplicationId

The application identifier type.

typedef sequence< TToiApplicationId > ToiApplicationService::TToiApplicationIdSequence

A sequence of application identifiers.

typedef sequence< ToiApplicationServiceApplicationInfo > ToiApplicationService::TToiApplicationInfoSequence

A sequence of application info structure.

typedef long ToiApplicationService::TToiApplicationState

The ToiApplicationService::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.

typedef sequence< string > ToiApplicationService::TToiPropertyStringSequence

A sequence of property string values.

Member Function Documentation

void ToiApplicationService::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:: ToiApplicationService::TToiApplicationState

void ToiApplicationService::activateWithCommand	(	in TToiApplicationId	applicationId,
		in string	command
	)		raises (TToiInvalidArgumentException)

This method does the same thing as ToiApplicationService::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:: ToiApplicationService::activate(); ToiApplication::executeCommand()

void ToiApplicationService::activateWithUri	(	in TToiApplicationId	applicationId,
		in string	uri,
		in string	mimeType
	)		raises (TToiInvalidArgumentException)

This method does the same thing as ToiApplicationService::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:: ToiApplicationService::activate(); ToiApplication::loadUri()

void ToiEventTarget::addEventListener	(	in long	type,
		in ToiEventListener	listener
	)		raises (TToiInvalidArgumentException) `[inherited]`

This method registers an event listener for a specific event. Multiple listeners can be added for the same event. Events are broadcast to all registered listeners.

Parameters:

type	The event type of the event to subscribe to.
listener	The JavaScript function that will receive events.

Exceptions:

TInvalidArgumentException Raised if the event type is not supported by this object or if the listener is not a valid JavaScript function. This exception is also raised if the application calls addEventListener with the same combination of type and listener twice.

void ToiApplicationService::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, ToiApplicationService::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:: ToiApplicationService::TToiApplicationState

TToiApplicationIdSequence ToiApplicationService::getApplicationIds ( )

Returns the identifiers for all registered applications.

Return values:

applicationsIds The identifiers of all registered applications.

boolean ToiApplicationService::getBoolProperty	(	in TToiApplicationId	applicationId,
		in string	property
	)		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.

ToiApplicationServiceApplicationInfo ToiApplicationService::getInfo ( in TToiApplicationId applicationId ) 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.

long ToiApplicationService::getIntProperty	(	in TToiApplicationId	applicationId,
		in string	property
	)		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.

TToiApplicationId ToiApplicationService::getOwnApplicationId ( )

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.

string ToiApplicationService::getStringProperty	(	in TToiApplicationId	applicationId,
		in string	property
	)		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.

TToiPropertyStringSequence ToiApplicationService::getStringSequenceProperty	(	in TToiApplicationId	applicationId,
		in string	property
	)		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 ToiApplicationService::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 ToiApplicationService::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 (C++) ToiApplication::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:: ToiApplication::loadUri()

void ToiEventTarget::removeEventListener	(	in long	type,
		in ToiEventListener	listener
	)		raises (TToiInvalidArgumentException) `[inherited]`

This method removes an event listener for a specific event.

Parameters:

type	The event type of the event to remove the listener from.
listener	The JavaScript function that was previously added as an event listener.

Exceptions:

TInvalidArgumentException Raised if the event type is not supported by this object or if the listener is not a valid JavaScript function. This exception is also raised if the listener had not previously been added.

Member Data Documentation

const long ToiApplicationService::ON_STATE_CHANGED = 200

This is an Event identifier for ToiApplicationStateChangedEvent.

This constant can also be accessed from toi.consts.ToiApplicationService.ON_STATE_CHANGED.

const TToiApplicationState ToiApplicationService::STATE_ACTIVE = 6

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

This constant can also be accessed from toi.consts.ToiApplicationService.STATE_ACTIVE.

const TToiApplicationState ToiApplicationService::STATE_INSTALLED = 2

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

This constant can also be accessed from toi.consts.ToiApplicationService.STATE_INSTALLED.

const TToiApplicationState ToiApplicationService::STATE_INSTALLING = 1

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.

This constant can also be accessed from toi.consts.ToiApplicationService.STATE_INSTALLING.

const TToiApplicationState ToiApplicationService::STATE_INVISIBLE = 4

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.

This constant can also be accessed from toi.consts.ToiApplicationService.STATE_INVISIBLE.

const TToiApplicationState ToiApplicationService::STATE_REGISTERED = 0

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

This constant can also be accessed from toi.consts.ToiApplicationService.STATE_REGISTERED.

const TToiApplicationState ToiApplicationService::STATE_STARTING = 3

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 (C++) ToiApplicationService::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:: ToiApplicationService::reportStarted()

This constant can also be accessed from toi.consts.ToiApplicationService.STATE_STARTING.

const TToiApplicationState ToiApplicationService::STATE_STOPPED = 7

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.

This constant can also be accessed from toi.consts.ToiApplicationService.STATE_STOPPED.

const TToiApplicationState ToiApplicationService::STATE_VISIBLE = 5

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.

This constant can also be accessed from toi.consts.ToiApplicationService.STATE_VISIBLE.

Description

Public Member Functions

Public Attributes

Public Types

Member Typedef Documentation

Member Function Documentation

Member Data Documentation