Prev: Module gsm: GSM information
Module phone: Phone Calls
This module allows to monitor and make voice phone calls. The module can monitor at most one call at the same time. The following diagram depicts the relationship between states and functions:
- If phone.new detects an incoming call, this new call is phone.ringing. It can either be answered via phone.answer or by the user, or rejected via phone.hangup or by the user. Once the call has been answered, it becomes phone.active.
- If phone.new detects an outgoing call dialled by the user, or phone.dial successfully establishes one, the call also becomes phone.active.
- An active call can be terminated explicitly via phone.hangup. Alternatively, phone.state can wait for it becoming phone.idle, i.e. for its termination.
phone.answer
• function answer() → null
Permissions: FreeComm
Answers an incoming (ringing) call by accepting it. This should be called after phone.new returns with an incoming call. See there for an example.
Throws ErrDisconnected if the there is no current call.
phone.dial
• function dial(number, timeout=-1) → Boolean
Permissions: FreeComm+CostComm
Dials the given phone number to establish a voice call. If timeout>=0, waits at least timeout milliseconds before giving up. Returns true if the call could be established and the remote party has answered, or false if the timeout was reached.
Throws ErrInUse if a call is already active.
Throws ExcValueOutOfRange if timeout exceeds 2147483 (35 minutes and 47.483 seconds).
// make a one minute call to +41797654321
if phone.dial("+41797654321", 30000) then
sleep(60000);
phone.hangup()
end
|
phone.hangup
• function hangup() → null
Permissions: FreeComm
| | |
| Compatibility of function phone.hangup |
| Symbian 3rd/5th Edition phones: a call which is phone.ringing cannot be hung up without answering it first. Calling phone.hangup on a ringing call will answer it first and then immediately hang up, potentially causing costs for the caller. |
|
Disconnects the current call ("hangs up" the phone).
Throws ErrDisconnected if there is no current call.
Does not hang up a call which was not made via phone.dial or obtained via phone.new.
phone.ms
• function ms() → Number
Permissions: FreeComm
Gets the duration of the current call in milliseconds.
Throws ErrDisconnected if there is no current call.
See phone.state for an example.
phone.new
• function new(timeout=-1) → Array|null
Permissions: FreeComm
Waits for a new call (incoming or outgoing), and returns an array with the following fields:
| Key | Meaning | Type |
| incoming | true for incoming, false for outgoing | Boolean |
| number | Phone number of remote party | String |
| |
If timeout>=0, waits at least timeout milliseconds before giving up. Returns null if the timeout was reached.
Throws ExcValueOutOfRange if timeout exceeds 2147483 (35 minutes and 47.483 seconds).
// reject all incoming calls from +41797654321
while true do
c=phone.new();
if c["incoming"] then
if c["number"]="+41797654321" then
// we reject this call
phone.hangup()
else
// other calls are accepted
phone.answer()
end
end
end
|
phone.state
• function state(mask=phone.idle | phone.ringing | phone.active, timeout=-1) → Number|null
Permissions: FreeComm
Waits until the current call enters one of the states in mask, and returns the current state. If timeout>=0, waits at least timeout milliseconds before giving up and returning null.
Throws ExcValueOutOfRange if timeout exceeds 2147483 (35 minutes and 47.483 seconds).
Throws ErrDisconnected if there is no current call.
// log number and duration of each outgoing call
while true do
c=phone.new();
if not c["incoming"] then
// wait until the call becomes idle again
phone.state(phone.idle);
print phone.ms(),"ms call to",c["number"]
end
end
|
phone Constants
• const idle = 1
The call is idle, i.e. was hung up.
• const ringing = 2
A call is coming in and must be answered.
• const active = 4
A call is active.
Next: Applications and Processes© 2004-2010 airbit AG, CH-8008 Zürich
Document AB-M-LIB-871
