(Page 4 of 12 in this chapter)

3.3 Responding to Inbound Calls

AG Access establishes telephone network-initiated connections for protocols supporting inbound or bidirectional trunks. Once the port's telephony protocol is started with adiStartProtocol, it is eligible to receive incoming calls. After the incoming call event is offered to the application, the application is required to either accept the call by calling adiAnswerCall or reject the call by calling adiRejectCall. If the application does not respond to the event, the call is rejected.
Establishing an inbound call involves the following steps: The telephone network offers the call. AG Access generates an incoming call event. The application chooses to accept or reject the call. AG Access performs telephone network procedures to execute the application's decision. AG Access generates a call connected event if the call is successfully established or a call disconnected event if the remote party disconnects.
Figure 3 contains two protocol sequence diagrams: one for answering an inbound call, and one for rejecting an inbound call. The diagrams depict the normal exchange of commands and events between AG Access and the application. Informational events are shown with a dashed line. Figure 3. Inbound Call Sequence
Figure 4 is a state diagram for inbound calls. The sequence diagrams in Figure 3 can be correlated with the state diagram in Figure 4 to gain a comprehensive understanding of the inbound call states and events, which are described in the next section. Figure 4. Inbound Call State

3.3.1 Inbound Call Parameters

Most of the parameters that govern inbound call establishment are specific to the telephony protocol running on the given port. Refer to the documentation for the telephony protocol that your application is using for more detailed information. The telephony protocols that are included with AG Access are documented in the AG Access Function Reference Manual.

3.3.2 Inbound Call Events

The following table summarizes the AG Access events which are generated when responding to inbound calls:

AG Access Event

Description

ADIEVN_SEIZURE_DETECTED

Informational event generated when a line is seized by the telephone network.
Examples of a line-seized event include:

Line Type
Wink-start
Loop-start

Condition
Off-hook detected.
The leading edge of the first ring.

ADIEVN_INCOMING_CALL

Event that signifies the transition of the call from the Idle state to the Incoming Call state. It is generated after the telephone network delivers the call to AG Access. The following examples illustrate conditions that generate an incoming call event:

Line Type
Wink-start

Loop-start

Condition
All required destination address digits have been received by AG Access. adiGetCallStatus may be invoked to get the called party and the calling party digits.
A specified number of rings have been received, along with optional caller ID information (Refer to the loop-start parameters in the AG Access Function Reference Manual).

The application should respond to the incoming call event by invoking either adiAnswerCall or adiRejectCall.
Wink-start protocols require the application to respond within a specified period of time. If the application fails to respond within the given period, AG Access automatically rejects the call and generates an ADIEVN_REJECTING_CALL event.

ADIEVN_ANSWERING_CALL

After the application invokes adiAnswerCall, this event is generated to acknowledge that AG Access has begun executing the answer call function. Once this event is received, the call state transitions to Answering Call.

ADIEVN_CALL_CONNECTED

After the application invokes adiAnswerCall, and receives the ADIEVN_ANSWERING_CALL acknowledgment, AG Access executes the telephone network procedures for accepting the call and establishing the connection. Once the connection is established, the call connected event is generated and the call state transitions to Connected.

ADIEVN_REJECTING_CALL

If the application invokes adiRejectCall, the rejecting event is generated once AG Access begins executing the specified reject method. Rejection of incoming calls is protocol-dependent.
Loop-start lines can only reject calls by not answering them. The board will report that the call is disconnected when the incoming ring has stopped. Wink-start lines may use one of four methods of call rejection:
- Playing reorder tones
- Playing busy tones
- Indefinitely playing ring tones
- Playing application-provided audio (e.g., SIT)
The method of rejection is returned in the value field of the event. The rejecting event is also generated if the application fails to respond to the incoming call event as described above. In this case, the value field will contain "host timeout."

ADIEVN_CALL_DISCONNECTED

This event is generated when the calling party disconnects. It can occur in any call state. The disconnect event contains the reason for disconnection in the value field.

ADIEVEN_CALL_RELEASED

After the application invokes adiReleaseCall, AG Access generates the call released event when its internal state is reset to Idle.

AG Access Event	Description
`ADIEVN_SEIZURE_DETECTED`	Informational event generated when a line is seized by the telephone network. Examples of a line-seized event include:
	Line Type Wink-start Loop-start	Condition Off-hook detected. The leading edge of the first ring.
`ADIEVN_INCOMING_CALL`	Event that signifies the transition of the call from the Idle state to the Incoming Call state. It is generated after the telephone network delivers the call to AG Access. The following examples illustrate conditions that generate an incoming call event:
	Line Type Wink-start Loop-start	Condition All required destination address digits have been received by AG Access. adiGetCallStatus may be invoked to get the called party and the calling party digits. A specified number of rings have been received, along with optional caller ID information (Refer to the loop-start parameters in the AG Access Function Reference Manual).
	The application should respond to the incoming call event by invoking either adiAnswerCall or adiRejectCall. Wink-start protocols require the application to respond within a specified period of time. If the application fails to respond within the given period, AG Access automatically rejects the call and generates an `ADIEVN_REJECTING_CALL` event.
`ADIEVN_ANSWERING_CALL`	After the application invokes adiAnswerCall, this event is generated to acknowledge that AG Access has begun executing the answer call function. Once this event is received, the call state transitions to Answering Call.
`ADIEVN_CALL_CONNECTED`	After the application invokes adiAnswerCall, and receives the `ADIEVN_ANSWERING_CALL` acknowledgment, AG Access executes the telephone network procedures for accepting the call and establishing the connection. Once the connection is established, the call connected event is generated and the call state transitions to Connected.
`ADIEVN_REJECTING_CALL`	If the application invokes adiRejectCall, the rejecting event is generated once AG Access begins executing the specified reject method. Rejection of incoming calls is protocol-dependent. Loop-start lines can only reject calls by not answering them. The board will report that the call is disconnected when the incoming ring has stopped. Wink-start lines may use one of four methods of call rejection: - Playing reorder tones - Playing busy tones - Indefinitely playing ring tones - Playing application-provided audio (e.g., SIT) The method of rejection is returned in the `value` field of the event. The rejecting event is also generated if the application fails to respond to the incoming call event as described above. In this case, the `value` field will contain "host timeout."
`ADIEVN_CALL_DISCONNECTED`	This event is generated when the calling party disconnects. It can occur in any call state. The disconnect event contains the reason for disconnection in the `value` field.
`ADIEVEN_CALL_RELEASED`	After the application invokes adiReleaseCall, AG Access generates the call released event when its internal state is reset to Idle.

3.3.3 Retrieving Incoming Call Information

Available incoming call information is protocol-specific. Wink-start protocols deliver called party information and can be configured to deliver calling party information. Loop-start protocol lines allow a user to subscribe to caller ID service, which delivers calling party information and, optionally, caller name.
Under the wink-start protocol only, some incoming trunks deliver both calling ID (ANI) and called ID in a single burst of digits. There may be a special digit such as '*' separating the two number strings. To analyze caller ID data:

Set the numdigits parameter in the protocol's parameter structure to the total number of digits expected, including the separator character.

After an incoming call arrives, retrieve the digits from the ADI_CALL_STATUS structure with adiGetCallStatus. The entire string will be in the calledaddr field of the status structure.
For loop-start protocol only, modify your ag.cfg file and/or the telephony protocol parameter structure for the telephony protocol(s) your application is using as indicated in the AG Access Function Reference Manual.
The Bellcore specifications define two types of CID message formats for the loop-start protocol which NMS currently supports: Single Message Data Format (SMDF) ADI_CALL_STATUS.callingaddr contains the caller's number. Multiple Message Data Format (MMDF) ADI_CALL_STATUS.callingaddr contains the caller's number, and ADI_CALL_STATUS.callingname contains the caller's name.
All other message formats and parameter types are ignored.
If the caller's ID or name is blocked, the callingname or callingaddr fields respectively, will contain a 'P'. If either is unavailable, the letter 'O' is placed in the field. No information is returned if there are any line errors (such as bad stop bit or a drop in data).
Keep in mind that if caller ID is enabled, even if the ringcount is set to 0 or 1, the ADIEVN_INCOMING_CALL event is not generated until the caller information is received, which occurs sometime between the first and second rings.
To retrieve information about an incoming call, the application needs to respond to an ADIEVN_INCOMING_CALL event by invoking adiGetCallStatus. The application needs to analyze the call status for every incoming call in order to retrieve the caller ID data, since the data is written to the ADI_CALL_STATUS structure.

(Page 4 of 12 in this chapter)

tech_support@nmss.com