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
OnUpdate
event fires - The application's
OnService
event fires - The current module's
OnService
event fires
Each Service stores its update data in a queue. The methods get_event()
and pop_event()
access the next event in the queue; event_size
returns how many events exist; clear_events()
clears the queue.
The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" Phonebot property. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each OnUpdate
and OnService
event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.
A 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:
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
Syntax | Description |
---|---|
auto_start
|
Read-only boolean. Set to true to start the service as soon as the application starts. |
event_size
|
Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in on_service events to determine which service was updated.
|
name
|
Read-only. |
system
|
Read-only boolean. Set to true to have the service run even when the application has lost focus. |
text
|
Read-only. |
Methods
Syntax | Description |
---|---|
size = clear_events()
|
Delete all events and return how many were deleted. |
event = get_event()
|
Retrieve the next event in the queue. |
value = get_property(name)
|
Retrieve the value of a custom property (see below). |
event = pop_event()
|
Retrieve and delete the next event in the queue. |
set_property(name, value)
|
Set the value of a custom property (see below). |
start()
|
Start the service. |
stop()
|
Stop the service. |
Events
Syntax | Description |
---|---|
on_service
|
In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:
Service | Properties | Description |
---|---|---|
http
|
url
|
Makes a GET request to a URL. Returns a single event in the queue containing the response. |
phone
|
events - 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. data_activity,4 ). The range of each value is dependent on the event.
|
sensor
|
minimum_update - time between updates in milliseconds
|
Monitors one or more hardware sensors. Returns an event containing a comma-delimited list of values beginning with the sensor name (e.g. orientation,60.0,-28.0,3.0 ). The range of each value is dependent on the sensor.
|
timer
|
duration - time between updates, formatted as h:m:s , m:s , or s
|
Fire the update events at regular intervals. The event will first fire immediately after the service is started. Returns an event containing the datetime 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:
Name | Structure of event value
(actual values are prefixed with the name, i.e. |
Description |
---|---|---|
call_forwarding
|
cfi
|
boolean |
call_state
|
state,incoming_number
|
state: 0 - idle, 1 - ringing, 2 - off hook |
cell_location
|
"cdma",base_station_id,base_station_latitude,base_station_longitude,system_id,network_id
|
|
data_activity
|
direction
|
0 - none, 1 - in, 2 - out, 3 - in/out, 4 - dormant |
data_connection_state
|
state,network_type
|
state: 0 - disconnected, 1 - connecting, 2 - connected, 3 - suspended |
message_waiting
|
mwi
|
boolean |
service_state
|
is_manual_selection,operator_alpha_long,operator_alpha_short,operator_numeric,roaming,state
|
state: 0 - in service, 1 - out of service, 2 - emergency only, 3 - power off |
signal_strengths
|
cdma_ecio,evdo_dbm,evdo_ecio,evdo_snr,gsm_bit_error_rate,gsm_signal_strength,is_gsm
|
|
sms_received
|
timestamp,originating_address,message_body
|
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:
Name | Structure of event value
(actual values are prefixed with the name, i.e. |
Description |
---|---|---|
accelerometer
|
x,y,z
|
Acceleration in meters/second^2 |
gps
|
latitude,longitude,accuracy,altitude,bearing,speed
|
|
gravity
|
x,y,z
|
Gravity in meters/second^2 |
gyroscope
|
x,y,z
|
Angular speed in radian/second |
light
|
l
|
Ambient light in lux units |
linear_acceleration
|
|
Acceleration in meters/second^2 |
magnetic_field
|
x,y,z
|
Magnetic field in micro-Teslas |
orientation
|
azimuth,pitch,roll
|
Measured in degrees. 0=North, 90=East, 180=South, 270=West; -180..180; -90..90 |
pressure
|
p
|
Atmospheric pressure in millibars |
proximity
|
p
|
Proximity in centimeters |
rotation_vector
|
|
|
temperature
|
|