Client-side Plugins

Eero Räsänen — Wed, 20 Jun 2007 23:21:38 +0000

Client side has support for third party plugins, which are software modules that can for instance

Communicate with hardware or sensor connected to the device
Implement support for optional MIDP APIs
Parse large amounts of data into suitable form for the client and creates events with data parameters in the content
Extract metadata from the images and other media files

The plugins can either be passive or active. Passive plugins do nothing but wait for the client to call it and then immediately create event in the content for the call result. Active plugins are started and left running in the background. They can create events at any time when for instance the data input changes in the sensors.

The content can then parse the data further or trigger functionality in the content according to the plugin parameters. The events plugins create have certain format:

“on_”pluginname”_”processname”_”state”

All plugins are used through plugin API described in the Common Script Language 1. There are three methods that are used to manipulate plugins:

Method	Function
load	Loading and starting the plugin.
unload	Stopping and unloading the plugin.
call	Calling the plugins API.

Lets say we have plugin called calculator and it has method called sum that takes a two integer parameters and sums them together. First we have to load the plugin using load method:

<load plugin="calculator" />

The call creates event on_calculator_loaded_status which has parameter calculator_loaded_status. If plugin loading was successful, the parameter has value yes. If there was an error while loading the plugin, the parameter has value no.

After loading the plugin successfully, the plugin can be called as follows:

<call plugin="calculator" method="sum" a="5" b="3" />

After the call the plugin creates on_calculator_sum_result event and the result is given as parameter for the event.

The result of the sum method is saved in an attribute same name as the event, except without the on_ prefix. In this case the attribute will be called calculator_sum_result. The script can handle the event by hooking it at the template"s global level as follows:

<template>
   <hook name="on_calculator_sum_result">
      <debug text="result is $(global.calculator_sum_result)" />
   </hook>
   <call plugin="calculator" method="sum" a="5" b="3" />
</template>

Each plugin can have its own API for call method, which are described in the following chapters.

Plugin: bluetooth

Bluetooth plugin implements device discovery using MIDP Bluetooth API. At it's current state it does not implement service discovery or data transfers. However, it can be used to detect devices in the close proximity of the MUPE device.

The bluetooth IDs that are obtained from the device discovery can for instance be resolved to detect if the other device nearby is a MUPE device as well (using server).

devicediscovery

Starts a bluetooth device discovery. The device discovery is a non-blocking process, which will send on_bluetooth_devicediscovery_progress events for each device the discovery finds.

Callback(s)

Event	Attribute	Function
on_bluetooth_devicediscovery_progress	bluetooth_devicediscovery_progress	Bluetooth ID and name of found device. Called for each found device furing discovery.
on_bluetooth_devicediscovery_result	bluetooth_devicediscovery_result	Bluetooth IDs and names of all found devices. Called when the discovery is complete.

getaddress

Gets Bluetooth address of the device MUPE is running in.

Callback(s)

Event	Attribute	Function
on_bluetooth_getaddress_result	bluetooth_getaddress_result	Bluetooth ID and name of user's device

stop

Stops the device discovery if it is running currently.

Plugin: gps

GPS plugin implements support for external bluetooth GPS devices. Currently the Nokia GPS devices, Navigore Gps and Clip On GPS modules are supported. The GPS plugin is asynchronous plugin, which operates in the background and sends events to the UI when something interesting happens.

The idea of the plugin is that service can define a set of location triggers (geometrical areas) and the plugin notifies the UI when user enters or exists those areas.

While running in the background the plugin creates following events:

Callback(s)

Event	Attribute	Function
on_location_enter_location	location_enter_location	User enters a location trigger area. The parameter contains the name of the trigger.
on_location_leave_location	location_leave_location	User leaves a location trigger area. The parameter contains the name of the trigger.
on_gps_progress_error	gps_progress_error	Connection to the GPS module has failed, while the plugin is trying to receive data.

start

Starts the GPS plugin if it has been stopped. The plugin needs to be started after loading.

Callback(s)

Event	Attribute	Function
on_gps_init_status	gps_init_status	Status of the starting proccess: searching = plugin is searching for gps module. examining = plugin is examining the device it has found. ok = plugin has found a GPS module and is ready to be used.
on_gps_init_error	gps_init_error	Starting GPS plugin failed. Parameter contains an error code.

stop

Stops the GPS plugin.

addtrigger

Adds a geometrical area as location trigger in the plugin.

Parameters

Param	Type	Default	Meaning
name	string	none	Name of the trigger
lat	float	none	Latitude of the area center point.
lon	float	none	Longitude of the area center point.
width	float	none	west-east "width" of the area in WSG82 seconds
height	float	none	north-south "height" of the area in WSG82 seconds

addcurrent

Adds the current location as a location trigger using given geometry.

Parameters

Param	Type	Default	Meaning
name	string	none	Name of the trigger
width	float	none	west-east "width" of the area in WSG82 seconds
height	float	none	north-south "height" of the area in WSG82 seconds

removetrigger

Removes a location trigger.

Parameters

Param	Type	Default	Meaning
name	string	none	Name of the trigger

removeall

Removes all location triggers.

getlocation

Returns current location.

Callback(s)

Event	Attribute	Function
on_gps_getlocation_result	gps_getlocation_result	The parameter contains the current location in format "lat,lon" or string "n/a" if the location information is not available.

Plugin: location

Location plugin implements XML api for MIDP location API. The Location API is only implemented for CLDC 1.1 and some older phones cannot support the feature. The main difference between the location and gps plugins are that the location API also works with build-in location devices and possibly also locationing methods other than GPS (yet to see this). Also it is possible to calculate distances between the triggers and user, which might come handy in location based services.

The idea of the plugin is that service can define a set of location triggers (geometrical areas) and the plugin notifies the UI when user enters or exists those areas.

Unlike the gps plugin location plugin does not need to be explicitly started. It starts automatically right after loading.

The plugin loading takes a set of parameters:

Parameters

Param	Type	Default	Meaning
haccuracy	int	100	Preferred horisontal accuracy in meters.
vaccuracy	int	100	Preferred vertical (altitude) accuracy in meters.
responsetime	int	0	Preferred response time. Zero means no requirement and positive integer is a response time in seconds.
powerconsumption	int	0	Power consumtion requirement: 0 = no requirement 1 = low 2 = medium 3 = high
costallowed	Bool	true	Set to false if the location service should be free of charge.
needorientation	Bool	false	Set to true if the locationing method must extract user orientation information.
needaltitude	Bool	false	Set to true if the locationing method must extract user altitude.
needaddress	Bool	false	Set to true if the locationing method must know the street address where the user is at.

While running in the background the plugin creates following events:

Callback(s)

Event	Attribute	Function
on_location_coordinate_update	location_coordinate_update	The parameter contains the current location in format "lat,lon".
on_location_enter_location	location_enter_location	User enters a location trigger area. The parameter contains the name of the trigger.
on_location_leave_location	location_leave_location	User leaves a location trigger area. The parameter contains the name of the trigger.
on_location_provider_state	location_provider_state	State of the location service has chanced "Available" = location service is available. "Out of service" = location service is unavailable. "Temporarily unavailable" = location service is temporarily unavailable.

addtrigger

Adds a geometrical area as location trigger in the plugin.

Parameters

Param	Type	Default	Meaning
name	string	none	Name of the trigger
lat	float	none	Latitude of the area center point.
lon	float	none	Longitude of the area center point.
radius	float	none	west-east "width" of the area in WSG82 seconds

addcurrent

Adds the current location as a location trigger using given geometry.

Parameters

Param	Type	Default	Meaning
name	string	none	Name of the trigger
width	float	none	west-east "width" of the area in WSG82 seconds
height	float	none	north-south "height" of the area in WSG82 seconds

removetrigger

Removes a location trigger.

Parameters

Param	Type	Default	Meaning
name	string	none	Name of the trigger

getlocation

Returns current location.

Callback(s)

Event	Attribute	Function
on_location_getlocation_result	location_getlocation_result	The parameter contains the current location in format "lat,lon" or string "n/a" if the location information is not available.

removeall

Removes all location triggers.

distance

Calculates a distance between two location triggers or user and a location trigger.

Parameters

Param	Type	Default	Meaning
origin	String	none	Location origin is either a name of a location trigger or the user if the parameter is left unspecified.
destination	String	none	Name of a location trigger where to the distance is calculated.
border	Bool	false	Set to true if you want to calculate the distance between the area borders instead of are center points. Note: distance can become negative, which means the location triggers are overlapping.

Callback(s)

Event	Attribute	Function
on_location_distance_result	location_distance_result	Parameter contains the calculated distance.