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
• phone.dial
• phone.hangup
• phone.ms
• phone.new
• phone.state
• Constants

phone.answer

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

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

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

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

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

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