View source for Phonebot developer's reference/Object reference/Using Phonebot services

Services are non-visual components that monitor different environment states and trigger an event when the state changes. The available services are:

* http - Make web requests
* phone - Monitor phone events
* sensor - Monitor hardware sensors
* timer - Alert at specific intervals

When a service is updated, events are fired in the following order:

# The service's <code>OnUpdate</code> event fires
# The [[Phonebot_developer%27s_reference/Object_reference#Application|application]]'s <code>OnService</code> event fires
# The current [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s <code>OnService</code> event fires

Each Service stores its update data in a queue. The methods <code>get_event()</code> and <code>pop_event()</code> access the next event in the queue; <code>event_size</code> returns how many events exist; <code>clear_events()</code> clears the queue.

The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" [[Phonebot properties|Phonebot property]]. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each <code>OnUpdate</code> and <code>OnService</code> event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.

A [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s show_file_dialog() method can be considered a module-level service.

== Service lifecycle ==

A service's properties, methods, and the application state affect that service's lifetime as the following diagram illustrates:

[[Image:phonebot.service-lifecycle.png]]

A service will start running:

* When its start() method is called
* If its autostart property is set to true, immediately after the application starts

A service will stop running:

* When its stop() method is called
* If its system property is set to false, when the application loses focus
* If its system property is set to true, when the application exits

== Object reference ==


Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>auto_start</code>
|Read-only boolean. Set to true to start the service as soon as the application starts.
|-
|<code>event_size</code>
|Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in <code>on_service</code> events to determine which service was updated.
|-
|<code>name</code>
|Read-only.
|-
|<code>system</code>
|Read-only boolean. Set to true to have the service run even when the application has lost focus.
|-
|<code>text</code>
|Read-only.
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size = clear_events()</code>
|Delete all events and return how many were deleted.
|-
|<code>event = get_event()</code>
|Retrieve the next event in the queue.
|-
|<code>value = get_property(name)</code>
|Retrieve the value of a custom property (see below).
|-
|<code>event = pop_event()</code>
|Retrieve and delete the next event in the queue.
|-
|<code>set_property(name, value)</code>
|Set the value of a custom property (see below).
|-
|<code>start()</code>
|Start the service.
|-
|<code>stop()</code>
|Stop the service.
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_service</code>
|
|-
|}

In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:

{|class="wikitable sortable"
|-
!Service
!Properties
!Description
|-
|<code>http</code>
|<code>url</code>
|Makes a GET request to a URL. Returns a single event in the queue containing the response.
|-
|<code>phone</code>
|<code>events</code> - array of event names
|Monitors one or more phone events. Returns an event containing a comma-delimited list of values beginning with the event name (e.g. <code>data_activity,4</code>). The range of each value is dependent on the event.
|-
|<code>sensor</code>
|<code>minimum_update</code> - time between updates in milliseconds
<code>sensors</code> - array of sensor names
|Monitors one or more hardware sensors. Returns an event containing a comma-delimited list of values beginning with the sensor name (e.g. <code>orientation,60.0,-28.0,3.0</code>). The range of each value is dependent on the sensor.
|-
|<code>timer</code>
|<code>duration</code> - time between updates, formatted as <code>h:m:s</code>, <code>m:s</code>, or <code>s</code>
|Fire the update events at regular intervals. The event will first fire immediately after the service is started. Returns an event containing the <code>datetime</code> value when the update happened.
|-
|}

Events can be accessed and parsed in the following manner:

HTTP:

 event = http_service.pop_event()
 // query with XPath
 items = event:xml.query("//root/item")
 // read json data
 root = event:json.get_element("root")
 items = event:json.get_element("item")

Sensor:

 event = sensor_service.pop_event()
 event = event:string.split(",")
 name = event:array.get_element(0)
 // get values from index 1 and greater

Timer:

 event = timer_service.pop_event()
 event = event:datetime.format("HH:mm:ss")

=== Phone events ===

The phone service can be configured to return any combination of phone events. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>call_forwarding</code>
|<code>cfi</code>
|boolean
|-
|<code>call_state</code>
|<code>state,incoming_number</code>
|state: 0 - idle, 1 - ringing, 2 - off hook
|-
|<code>cell_location</code>
|<code>"cdma",base_station_id,base_station_latitude,base_station_longitude,system_id,network_id</code>
<code>"gsm",lac,cid</code>
|
|-
|<code>data_activity</code>
|<code>direction</code>
|0 - none, 1 - in, 2 - out, 3 - in/out, 4 - dormant
|-
|<code>data_connection_state</code>
|<code>state,network_type</code>
|state: 0 - disconnected, 1 - connecting, 2 - connected, 3 - suspended
|-
|<code>message_waiting</code>
|<code>mwi</code>
|boolean
|-
|<code>service_state</code>
|<code>is_manual_selection,operator_alpha_long,operator_alpha_short,operator_numeric,roaming,state</code>
|state: 0 - in service, 1 - out of service, 2 - emergency only, 3 - power off
|-
|<code>signal_strengths</code>
|<code>cdma_ecio,evdo_dbm,evdo_ecio,evdo_snr,gsm_bit_error_rate,gsm_signal_strength,is_gsm</code>
|
|-
|<code>sms_received</code>
|<code>timestamp,originating_address,message_body</code>
|
|}

--[http://developer.android.com/reference/android/telephony/PhoneStateListener.html PhoneStateListener]

=== Sensor events ===

The sensor service can be configured to return any combination of sensor types. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>accelerometer</code>
|<code>x,y,z</code>
|Acceleration in meters/second^2
|-
|<code>gps</code>
|<code>latitude,longitude,accuracy,altitude,bearing,speed</code>
|
|-
|<code>gravity</code>
|<code>x,y,z</code>
|Gravity in meters/second^2
|-
|<code>gyroscope</code>
|<code>x,y,z</code>
|Angular speed in radian/second
|-
|<code>light</code>
|<code>l</code>
|Ambient light in [http://en.wikipedia.org/wiki/Lux lux units]
|-
|<code>linear_acceleration</code>
|<code></code>
|Acceleration in meters/second^2
|-
|<code>magnetic_field</code>
|<code>x,y,z</code>
|Magnetic field in [http://en.wikipedia.org/wiki/Tesla_(unit) micro-Teslas]
|-
|<code>orientation</code>
|<code>azimuth,pitch,roll</code>
|Measured in degrees. 0=North, 90=East, 180=South, 270=West; -180..180; -90..90
|-
|<code>pressure</code>
|<code>p</code>
|Atmospheric pressure in [http://en.wikipedia.org/wiki/Bar_(unit) millibars]
|-
|<code>proximity</code>
|<code>p</code>
|Proximity in centimeters
|-
|<code>rotation_vector</code>
|<code></code>
|
|-
|<code>temperature</code>
|<code></code>
|
|-
|}

--[http://developer.android.com/reference/android/hardware/SensorEvent.html#values SensorEvent values]

[[Category:Phonebot]]