< Back to Package Overview

Off-Hook Dialing

Overview

Off-Hook dialing is a feature typical of traditional desk phones. On these devices, a physical handset is provided so that when the handset is lifted from its cradle the user hears dial tone played through the speaker in the handset. Once dialtone is heard, the user knows that the system is ready to accept the digits that represent a phone number to be dialed.

Another key characteristic of Off-Hook dialing is that the receiver of the digits automatically starts the call when enough digits are dialed to complete the number. There is no requirement on the user to press the "Green Key" or "Call" button that is typical on modern mobile devices. In order to know when the last digit has been entered, this requires that the receiver processing the digits know the dial plan for the telephony network and process the digits as they are entered to make the determination when the number is complete and the call can begin.

Support for Off-Hook Dialing in the Desk Phone Services Package

The desk phone services package listens for the events related to a handset device going on or off hook coming from the platform, and reports them to applications via the DeskPhoneEventListener interface. The application provides its implementation of this interface as a parameter when initializing the DeskPhoneService at startup.

The HandsetType enumerated type lists the possible optional handset attachments on Vantage.

When a handset goes off-hook, the offHook(HandsetType) method is invoked on the listener, and similarly when a handset goes on-hook, the onHook(HandsetType) method is called.

It is the application's responsibility to implement handling for these callbacks by:

• Bringing the application to the foreground on the device and displaying a UI for collecting digits
• Playing any media to the proper transducer - key press tones, dial tone, ...
• Digit collection and managing the Off-Hook session with the Communications Package

The callbacks for device on-hook/off-hook are not specific to off-hook dialing, and can be used by the application for other interactions with handsets, such as answering an incoming call by taking a handset off-hook.

Application Requirements for Off-Hook Dialing

The intent of off-hook dialing is to mimic the dialing and dial tone behavior of a standard touch tone telephone. When the handset is lifted (goes off-hook) the application should display a dial pad to the user, instruct the communications package media engine to select the handset as current device, start playback of dial tone, and use the communications package to create and start a new call. As a result of starting a call the communications package will reserve the specified line from the CallCreationInfo object or the first available line for the user's station if no specific line was requested. This will prevent any other device or call from claiming the line while dialing is in progress.

As part of registration, the communications package will download from PPM dial plan data that defines the dial plan patterns used in SM/CM. As the user enters digits into the application's UI, these will be sent to the call object via the addRemoteAddressDigit() method. The communications package will collect these digits and compare them against the downloaded dial plan patterns. When a match is found the communications package will signal this to the application via the onCallDigitCollectionCompleted() callback and automatically initiate a call to the specified number through the existing call object.

If the digits the user has entered have not triggered a match in the dial plan data but the user wishes to place a call to the dialed number regardless, they may do so by pressing the pound (#) key. In this scenario the application should send the pound digit to the communications package via addRemoteAddressDigit() as usual and the communications package will act on this trigger to initiate the call immediately.

Once the user starts to enter digits after going off-hook, playback of dial tone should be stopped. However, as digits are dialed the dial plan data may indicate that dial tone should be played again. A typical example is when the ARS code is dialed, on a standard desk phone this will cause dial tone to resume. As the application sends digits to the communications package, the communications package will identify cases where dial tone should be played again and will communicate this to the application through the onCallDigitCollectionPlayDialTone() callback. Once the user enters another digit, dial tone will again be stopped by the application.

Once the communications package has completed digit collection and initiated the call, the call object behaves identically to a call where the remote address was specified before calling start().

A call in the off-hook digit collection state may be aborted at any time by calling end().

While still in the off-hook digit collection state, a call cannot be preserved or held. If connectivity to the SM is lost, line reservation fails, or an attempt is made to automatically hold such a call, the call will be failed via onCallFailed().