Receiving a Call

When an incoming call arrives, the user application receives a PKX_EVENT_GROUP_INCOMING_CALL event. The handle of the group receiving the call is specified in the event handle field. The handle of the channel on which the call was received is specified in the p0 field. The handle of the object created to represent the call is specified in the p1 field.

The user application then calls the PKX_CALL_GetInfo function which returns the call information (PKX_TCallInfo), including the called address and calling identification information. The user application uses this information to

determine who is calling and who they are attempting to call.

The PKX_TCallInfo structure contains the following:

5

• to - the called number or identification • from - the calling number or identification • display - caller identification information

• callingNumberRestricted - if set to PK_TRUE, the calling number information has been restricted by the remote party

• forwardedFrom - indicates the party that forwarded the call to the current destination party • custom - custom ISDN call setting used to specify bearer capability information

When the call is destined for a device other than the user application, the PKX_CALL_Accept function should be called to indicate the user application is attempting to reach the called party. The PKX_CALL_Accept function returns immediately, while lower level processes send the appropriate accept message to the calling party. When the accept message has been sent, the user application receives a PKX_EVENT_CALL_ACCEPTED event.

If the user application does not want to accept the call or doesn't know how to route the call, it can reject the call by calling the PKX_CALL_Reject function.

When the called party answers the call, the user application calls the PKX_CALL_Answer function. The

PKX_CALL_Answer function returns immediately while lower-level processes send the appropriate answer message to the calling party. When the answer message is acknowledged and the call is established, the user application receives a PKX_EVENT_CALL_ANSWERED event. Billing at the service provider normally starts when a call is answered. The PKX_Call_Answer function has an optional settings parameter for special answer characteristics. Currently, the only characteristics defined are those for Collect Call Blocking (pg. 47). Refer to the section below. If no special characteristics are required, this parameter can be set to null.

When the user application is the called party (such as an IVR application), it is not necessary to accept the call before answering it.

The following diagrams show the typical processing flow for handling incoming calls. The diagram below shows the process flow when the call must be routed by the user application to another device. The user application accepts the call and makes a call to the destination. When the destination indicates that alerting has started, a one-way voice path from the called party to the calling party is made to provide the audio path for alerting tones being received from the destination to the original caller. When the destination answers, both channels of the calls are connected.

The following diagram shows the process flow when the user application answers the call. In this case, the call is answered immediately, without going through the call accept process. When the call answered event

(PKX_EVENT_CALL_ANSWERED) is received, processing is performed on the channels of the call.

5

Example

This example is taken from the EventProcessing function in ivr.cpp of the IVR sample application. It demonstrates the processing of the events received during an incoming call. When the PKX_EVENT_GROUP_INCOMING_CALL event is received, the application retrieves the call information and accepts the call. When the

PKX_EVENT_CALL_ACCEPTED event is received, the application answers the call. When the

PKX_EVENT_CALL_ANSWERED event is received, the channel is ready to receive or transmit audio data. The channel can be joined with another channel or, as is the case in this application, play the IVR menu.

5.3.4.2.1 Collect Call Blocking

In countries such as Brazil, the telephone company provides an automated collect call service that follows a national standard. The service operates as follows:

• The caller initiates a call using the collect call prefix

• When the far end answers, an automatic recording is played: "Collect Call, to accept stay on the line after the identification"

• At the same time, the caller hears: "After answer, say your name and the city you are calling from"

• If the far end hangs up the call before a specified time, typically 7 seconds, the called party is not billed for long distance charges

Companies with automated phone systems (e.g. IVR systems) need to block collect calls to avoid long distances charges. GP provides functionality referred to as double-answer which means that the call will be answered normally, hung up for 1.5 seconds and then answered again. If it is a collect call, the call is dropped by the telephone company. If not, the call continues normally. In countries where this service is offered, the called party can hang up for up to 90 seconds

without dropping the call (call retention by called party) and for collect calls, the called party controls when the call is dropped.

If the collect call block is enabled, GP will perform the double-answer before raising the PKX_EVENT_CALL_ANSWERED event to the user application.

settings

The PKX_CALL_Answer function parameter settings allows the user application to enable collect call blocking and to adjust the timeouts for the double answer.

• enable - enables/disables collect call blocking

• beforeOnHookTime - time (in ms) to wait before sending the onhook to the PSTN. [100 to 5000; default is 500] • collectCallTime - time (in ms) to wait before sending the offhook to the PSTN [1000 to 5000; default is 1500] • afterOffHookTime - time (in ms) to wait before raising the ANSWERED event to the application [100 to 5000;

default is 200]

5

NOTE: _{1. This feature is not supported for ISDN trunks.}

2. The settings parameter is introduced in the 2.5 release and it must be enabled by adding the

USE_ANSW_SETTINGS define to your project files or Makefiles. Refer to the information about the PKX_CALL_Answer function in the API Reference for more information.