5.1 Introduction

5.2 Call Control Operations Supported By NMS ISDN

5.3 Call Control API Summary 5.3.1 ADI Service Events 109

5.3.2 Call Control Functions and Solicited Events 110

5.3.3 Unsolicited Events 115

5.3.4 Digit Strings in Outbound Calls 116

5.4 State Machines and Sequence Diagrams 5.4.1 Inbound Calls 117

5.4.2 Outbound Calls 122

5.4.3 Call Release 124

5.5 Retrieving Call Information

5.6 Using Extended Arguments 5.6.1 adiPlaceCall Extended Parameters 132

5.6.2 adiAnswerCall Extended Parameters 135

5.6.3 adiAcceptCall Extended Parameters 136

5.6.4 adiRejectCall Extended Parameters 137

5.6.5 adiReleaseCall Extended Parameters 138

5.6.6 Receiving User-to-User Information (UUI) 139

5.6.7 Recieving Charging Information 140

5.1 Introduction

If the ADI service is active, and a protocol has been started on a line using adiStartProtocol, call control proceeds as described in the ADI Service Developer's Manual. This chapter outlines ADI service call control from an NMS ISDN point of view.

Note: ADI service call control functions have been superseded by the NCC service. If your application currently uses the ADI service for call control, consider migrating to the NCC service for better performance, new features, and more control over your application's call control functionality. For more information, see the Natural Call Control Service Developer's Reference Manual.

This chapter:

• Lists the call control operations supported by NMS ISDN.

• Summarizes the Natural Access function calls needed to perform call control.

• Explains how to establish inbound and outbound calls, release calls, and block and unblock calls.

5.2 Call Control Operations Supported By NMS ISDN

NMS ISDN supports the following call control operations:

Operation	Supported?
Receiving inbound calls	Yes
Placing outbound calls	Yes
Releasing calls	Yes
Call blocking	Yes
Call transfer	No

5.3 Call Control API Summary

The following section summarizes the ADI functions needed to perform call control. For most of these function calls, one or more events are expected in response to the command. These events are also described in this section.

Note: For detailed documentation of the functions, parameters and events, see the ADI Service Function Reference Manual.

There are two types of Natural Access events associated with call control operations:

• Solicited events, which signify acknowledgments from the API or the TCP, or occur as a consequence of some function call.

• Unsolicited events, which can occur at any time, regardless of the application's current activities. Usually, unsolicited events indicate that something has happened on the line. These events are summarized in Section 5.3.3, Unsolicited Events.

The eventmask parameter in the ADI_CALLCTL_PARMS structure dictates whether certain informational call control events are generated. For detailed information about this structure, refer to the ADI Service Function Reference Manual.

5.3.1 ADI Service Events

When performing call control functions, the ADI service processes events: both those that arrive from the network, and those that are generated in response to ADI service commands. The ADI service translates the network events into generic call control events. The names are defined in uppercase letters with an ADIEVN_ prefix. The network events fall into two classes: transitional and informational.

• Transitional events are generated when the call or line state changes. They are generated because the ADI service needs the application to choose an action or acknowledge that an application command is proceeding.

• Informational events do not change the line or call state. For example, the protocol error event, ADIEVN_PROTOCOL_ERROR, provides information about abnormalities on the line including false seizure, too many incoming digits, or premature answer while dialing.

  
  5.3.2	 Call Control Functions and Solicited Events
  
  

The following table lists ADI service call control-related functions and associated events. For detailed documentation of the functions, parameters and events, refer to the ADI Service Function Reference Manual.

ADI Function	Description/Associated Events
adiAcceptCall	Directs the TCP to accept an incoming call without answering it. In response to this function call, the TCP sends a PROGRESS message on the trunk. No further action is taken until the application calls adiAnswerCall or adiRejectCall, or the remote party disconnects. The application can accept a call using any of the following methods: · ADI_ACCEPT_PLAY_RING: Play a ring tone. · ADI_ACCEPT_QUIET: Accept the call, but do not play a tone or other audio. · ADI_ACCEPT_USER_AUDIO: The application generates a recorded message, or a Special Information Tone (SIT). If the remote party disconnects, the TCP interrupts the application tone or play function. Associated Events: · ADIEVN_ACCEPTING_CALL: The TCP is accepting the call, using the specified method. A PROGRESS message is sent to the network. · ADIEVN_CALL_DISCONNECTED: A DISCONNECT message was received from the network, indicating that the remote party has hung up. The event value field contains the reason. · ADIEVN_REJECTING_CALL: The application failed to invoke adiAnswerCall, adiAcceptCall, or adiRejectCall within the period specified in the protocol's ADI.ISD.waitforpctime parameter. The call is automatically rejected. The event value field contains ADI_REJ_HOST_TIMEOUT. In this situation, a tone is played to the network.
adiAnswerCall	Directs the TCP to answer a call after a specified number of rings. Associated Events: · ADIEVN_ANSWERING_CALL: The TCP is answering. First an ALERT message is sent to the network. Then the TCP plays the number of rings specified in the adiAnswerCall call. Then a CONNECT message is sent to the network. Note: By default, a PROGRESS message is not sent to the network by nccAnswerCall. · ADIEVN_CALL_CONNECTED: The CONNECT message was acknowledged by the network, and the connection is established. · ADIEVN_CALL_DISCONNECTED: A DISCONNECT message was received from the network, indicating that the remote party has hung up. The event value field contains the reason. · ADIEVN_REJECTING_CALL: The application failed to invoke either adiAnswerCall, adiAcceptCall, or adiRejectCall within the period specified in the protocol's ADI.ISD.waitforpctime parameter. The call is automatically rejected. The event value field contains ADI_REJ_HOST_TIMEOUT. In this situation, a tone is played to the network.
adiBlockCalls	Requests the TCP to block all incoming calls. The line remains in the blocked state until adiUnBlockCalls is called. The TCP behaves as though the application has responded to each call with an adiRejectCall. NMS ISDN allows two protocol-specific reject modes. The ADI.ISD.blockrejectmode parameter selects the mode: · BLOCK_REJECT_IMMEDIATE: Reject immediate · BLOCK_PLAY_BUSY: Reject playing busy tone Associated Events: · ADIEVN_CALLS_BLOCKED: Returns when request has been granted. · ADIEVN_CALL_DISCONNECTED: A DISCONNECT message was received from the network, indicating that the remote party has hung up. The event value field contains the reason.
adiGetCallStatus	Retrieves incoming digits and other call status information. Associated Events: · ADIEVN_CALL_DISCONNECTED: A DISCONNECT message was received from the network, indicating that the remote party has hung up. The event value field contains the reason.
adiPlaceCall	Directs the TCP to place a call to a specified address, using call placement parameters from the ADI_PLACECALL_PARMS structure. Associated Events: · ADIEVN_PLACING_CALL: This informational event is generated after the TCP has seized the trunk, and an acknowledgement has been received from the network. (This implies that glare has been resolved.) The network is sent a SETUP message. The event also indicates that a B channel has been chosen for the call. This is useful when the TCP is running in Non-Exclusive Mode (see Chapter 6). The stream and timeslot for this channel can be determined by calling adiGetCallStatus. · ADIEVN_CALL_PROCEEDING: This low-level event is enabled only if the ADI_CC_REPTPROCEEDING bit is set in the ADI_CALLCTL_PARMS eventmask passed to adiStartProtocol (see the source code for isdnchan for an example). This event follows ADIEVN_PLACING_CALL. · ADIEVN_REMOTE_ALERTING: This low-level event is enabled only if the ADI_CC_REPTALERTING bit is set in the ADI_CALLCTL_PARMS eventmask passed to adiStartProtocol (see the source code for isdnchan for an example). It means that the network has sent an ALERTING message, indicating that the remote party is being alerted that there is a call, or that a ring tone has been detected. · ADIEVN_REMOTE_ANSWERED: This low-level event is enabled only if the ADI_CC_REPTANSWERED bit is set in the ADI_CALLCTL_PARMS eventmask passed to adiStartProtocol (see isdnchan for an example of this). It means that the network has sent a CONNECT message, indicating that the remote party has answered. · ADIEVN_CALL_CONNECTED: The call fits the connection criteria specified in the connectmask parameter in the ADI_PLACECALL_PARMS structure. Usually, this is when a CONNECT message is received by the network; however, it could be due to other factors, depending on the connection criteria specified. The application can now play and record voice files, generate and detect DTMF tones, etc. The event value field contains the condition that satisfied the connection criteria. · ADIEVN_CALL_DISCONNECTED: The call is disconnected, because: A release event was received from the network, or A busy, reorder, ring-no-answer or Special Information Tone (SIT) was detected, or The call fits the disconnection criteria specified in the disconnectmask parameter in the ADI_PLACECALL_PARMS structure. By default, this is when a DISCONNECT message is received by the network. The event value field contains the condition that fit the disconnection criteria. · ADIEVN_INCOMING_CALL: A call is arriving on the B channel. Call placement is aborted. This message occurs when a SETUP message is received.
adiRejectCall	Directs the TCP to reject an incoming call using one of the following methods: · ADI_REJ_PLAY_BUSY: Play a busy tone, indicating that the line is busy. · ADI_REJ_PLAY_REORDER: Play a reorder tone. Reorder usually means that the number was incorrectly formatted, or is not allocated. · ADI_REJ_USER_AUDIO: The application generates a recorded message, or a Special Information Tone (SIT). If the remote party hangs up, the TCP interrupts the application tone or play function. · ADI_REJ_PLAY_RINGTONE: Play a ring tone. · ADI_REJ_FORCE_IMMEDIATE: Causes the TCP to actively clear a rejected call, by sending an appropriate Q.931 message. No tone is played in this case. Associated Events: · ADIEVN_REJECTING_CALL: The TCP is rejecting the call. The event value field contains the rejection method. After generating ADIEVN_REJECTING_CALL, the TCP sends the busy or reorder message (or plays the audio), and waits for the remote party to hang up. This event also occurs if the application fails to invoke adiAcceptCall, adiAnswerCall, or adiRejectCall within the period specified in the protocol's ADI.ISD.waitforpctime parameter. The event value field contains ADI_REJ_HOST_TIMEOUT. The TCP rejects the call by playing the tone specified by the ADI.ISD.defaulttone parameter. · ADIEVN_CALL_DISCONNECTED: Occurs if a DISCONNECT message is received from the network while the application is rejecting the call. Indicates that the remote party has hung up. ADIEVN_REJECTING_CALL is not generated in this case.
adiReleaseCall	Directs the TCP to perform one of the following actions: initiate connection teardown, abandon call placement, or acknowledge a network disconnect event. Associated Events: · ADIEVN_CALL_RELEASED: The call has been released. A DISCONNECT message was sent to the network, and a RELEASE was received. · ADIEVN_CALL_DISCONNECTED: A disconnect occurred while the release is taking place. This means that a DISCONNECT message has been received from the network. A RELEASE is sent in response, terminating the call.
adiSetExtendedArgs	Sets new arguments for the call control function that immediately follows it. Associated Events: · ADIEVN_EXT_ARGS_SET: The arguments are set.
adiStartProtocol	Starts a TCP. Associated Events: · ADIEVN_STARTPROTOCOL_DONE: The function has finished. The event value field indicates if the TCP started successfully. CTA_REASON_FINISHED means a successful completion. Any other value implies an error.
adiStopProtocol	Stops the TCP. Associated Events: · ADIEVN_STOPPROTOCOL_DONE: Indicates that the TCP has been halted. The value field is set to CTA_REASON_FINISHED.
adiUnBlockCalls	Requests the TCP to stop blocking calls. Associated Events: · ADIEVN_CALLS_UNBLOCKED: The request to unblock the line is granted.

5.3.3 Unsolicited Events

The following is a list of call-control-related unsolicited ADI events:

Event	Description
ADIEVN_REJECTING_CALL	Received unsolicited if the application has failed to accept, answer, or reject an incoming call within the period of time specified by the ADI.ISD.waitforPCtime parameter.
ADIEVN_CALL_DISCONNECTED	A DISCONNECT message was received from the network, indicating that the remote party has hung up. The event value field contains the reason.
ADIEVN_STATUSINFO_UPDATE	New call status information has arrived. The application can receive this information by calling adiGetCallStatus. Possible values are: CALL_STATUS_UUI
ADIEVN_SEIZURE_DETECTED	An incoming call has been detected. This event is generated only if the ADI_CC_REPTALERTING bit is set in the ADI.START.callctl.eventmask parameter.
ADIEVN_IN_SERVICE	Not supported in NMS ISDN protocols.
ADIEVN_INCOMING_CALL	The TCP has handled the setup of an incoming call, and is now waiting for the application to decide if the call must be answered or rejected. The application may now call adiGetCallStatus to retrieve information about the incoming call, or it can answer or reject the call as needed.
ADIEVN_INCOMING_DIGIT	Not supported in NMS ISDN protocols.
ADIEVN_OUT_OF_SERVICE	Not supported in NMS ISDN protocols.
ADIEVN_SEQUENCE_ERROR	A command was received by the TCP while it was in the wrong state. The command is not executed.

5.3.4 Digit Strings in Outbound Calls

The NMS ISDN TCP expects the digit string to be formatted as follows:

a1an * s1sn # d1dn * t1tn

where:

• a1an are the address of the calling party -- the Automatic Number Identification (ANI) digits.

• s1sn are the subaddress digits of the calling party, if used. If no subaddress is used, omit the * and s digits from the string.

• # d1dn are the digits to dial.

  
   # is a separator character. If only a called number is supplied to the adiPlaceCall function, omit this character from the string.
  
  

• t1tn are the subaddress digits to dial, if needed. If no subaddress is needed, omit the * and t digits from the string.

5.4 State Machines and Sequence Diagrams

This section includes state machines and diagrams showing the sequence of commands, events and state changes for various ADI call control operations.

5.4.1 Inbound Calls

Figure 22 is a state diagram for inbound calls. The sequence diagrams on the following pages can be correlated with this diagram to gain a comprehensive understanding of the inbound call states and events.

Figure 22. ADI Service Inbound Call State Diagram

Figure 23 is a sequence diagram for answering an inbound call using ADI call control functions. This diagram depicts the normal exchange of commands and events between the network, the channelizer, the TCP, Natural Access, and the application.

Figure 23. Sequence Diagram for Answering an Inbound Call

Figure 24 illustrates rejection of an inbound call using ADI call control functions:

Figure 24. Sequence Diagram for Rejecting an Inbound Call

Figure 25 illustrates accepting an inbound call and then rejecting it using ADI call control functions:

Figure 25. Sequence Diagram for Accepting and then Rejecting an Inbound Call

Figure 26 illustrates accepting an inbound call and then answering it using ADI call control functions:

Figure 26. Sequence Diagram for Accepting and then Answering an Inbound Call

5.4.2	 Outbound Calls

Figure 27 is a state diagram for placing outbound calls using ADI service call control functions. This diagram can be correlated with the sequence diagram in Figure 28 to gain an understanding of outbound call states and events.

Figure 27. ADI Service Outbound Call State Diagram

Figure 28 is a sequence diagram depicting, at several levels, the command and event interchange for placing an outbound call using ADI call control functions.

Note: Depending upon the switch variant, some of the intermediate messages may not occur, or may occur in a different order than shown here.

Figure 28. Sequence Diagram for an Outbound Call

5.4.3	 Call Release

Figure 29 shows the command/event interchange for a network-initiated release.

Figure 29. Sequence Diagram for Network-Initiated Release

Figure 30 is a sequence diagram depicting the command and event interchange for an application-initiated release.

Figure 30. Sequence Diagram for Application-Initiated Release

5.5 Retrieving Call Information

When the network first sends a SETUP message, the TCP handles the setup of an incoming call, and collects incoming digits (including ANI and subaddress digits), and other setup information. When all initial phases of call setup are complete, and the digits and other setup information are available, an ADIEVN_INCOMING_ CALL event is generated.

The application can call adiGetCallStatus to retrieve the digits and other information. The call status information is stored in the ADI_CALL_STATUS data structure, shown below:

#define ADI_MAX_DIGITS 31
#define ADI_MAX_CNAME 31
typedef struct
{ /* Used by adiGetCallStatus */
DWORD size; /* Size returned by adiGetCallStatus */
DWORD state; /* Call states (ADI_CC_STATE_xxx) */
INT32 reason; /* Reason for going back to IDLE state */
char calledaddr [ADI_MAX_DIGITS+1]; /*DNIS info, called number */
/* (null-terminated string) */
char callingaddr[ADI_MAX_DIGITS+1]; /*ANI info, calling number */
/* (null-terminated string) */
char callingname[ADI_MAX_CNAME+1]; /* Calling party name */
DWORD pendingcommand; /* Current unacknowledged command */
char usercategory; /* User category of the calling party */
char tollcategory; /* Toll category (generally same as */
/* usercategory) */
BYTE stream; /* Address of B channel */
BYTE timeslot; /* Address of B channel */
WORD billingrate; /* Billing rate of call */
char callednumplan; /* Q.931 numbering plan ID of */
/* called number (if supported) */
char callednumtype; /* Q.931 number type of */
/* called number (if supported) */
char callingnumplan; /* Q.931 numbering plan ID of */
/* calling number (if supported) */
char callingnumtype; /* Q.931 number type of */
/* calling number (if supported) */
char callingpres; /* Caller ID presentation indicator */
char callingscreen; /* Q.931 ANI screening indicator */
char progressdescr; /* Progress descriptor */
char releasecause; /* Cause for call release */
char redirectingaddr[ADI_MAX_DIGITS+1]; /* Redirecting no. info */
char redirectingplan; /* Q.931 numbering plan ID of */
/* redirecting number (if supported) */
char redirectingtype; /* Q.931 number type of */
/* redirecting number (if supported) */
char redirectingpres; /* Redirecting number presentation */
/* indicator */
char redirectingscreen; /* Q.931 redirecting number screen */
/* indicator */
char redirectingreason; /* Q.931 reason for redirection */
char originalcalledaddr [ADI_MAX_DIGITS+1]; /* (For future use) */
char UUI[132]; /* User-to-user information */
/* (132 chars max) */
char origcalledplan; /* Q.931 numbering plan ID if supported */
char origcalledtype; /* Q.931 number type if supported */
char origcalledpres; /* Original called number pres. indicator */
char origcalledscreen; /* Q.931 redirecting number screen ind. */
char origcalledreason; /* Q.931 reason for redirection */

} ADI_CALL_STATUS;

The table below describes each of the fields in the ADI_CALL_STATUS structure. Note that not all fields are used by all variants. Possible values for the fields in this structure are defined in isdnval.h.

Field	Description
size	Number of bytes written at the address pointed to by the status argument in adiGetCallStatus call.
state	Current call control state. Values applicable to NMS ISDN are: · ADI_CC_STATE_STOPPED · ADI_CC_STATE_IDLE · ADI_CC_STATE_INCOMING_CALL · ADI_CC_STATE_ANSWERING_CALL · ADI_CC_STATE_ACCEPTING_CALL · ADI_CC_STATE_PLACING_CALL · ADI_CC_STATE_DISCONNECTED · ADI_CC_STATE_CONNECTED · ADI_CC_STATE_REJECTING_CALL · ADI_CC_STATE_OUT_OF_SERVICE
reason	Reason for the last disconnect (return to Idle state). reason is 0 if the application initiated the disconnect. Otherwise, reason is the value received in the ADIEVN_CALL_DISCONNECTED event.
calledaddr	For inbound calls, the called party address. For NMS ISDN, the digits are formatted as follows: d1dn * s1sn where: · d1dn are the digits, and · s1sn are the subaddress digits, if available. If no subaddress is available, the * and s digits do not appear in the string.
callingaddr	For inbound calls, the calling party address - the Automatic Number Identification (ANI) digits. For NMS ISDN, the digits are formatted as follows: a1an * t1tn where: · a1an are the ANI digits, and · t1tn are the subaddress digits, if available. If no subaddress is available, the * and s digits do not appear in the string.
callingname	Calling party name. Always 0 for NMS ISDN.
pendingcommand	The last call control command issued that has not yet been acknowledged by the TCP. This field is set when a call control command is sent to the board. The field is cleared on the next event that causes a transition to a new call state. Values applicable to NMS ISDN are: 0 No command pending. 1 ADI_PENDCMD_PLACE_CALL 2 ADI_PENDCMD_ANSWER_CALL 3 ADI_PENDCMD_REJECT_CALL 4 ADI_PENDCMD_RELEASE_CALL 5 ADI_PENDCMD_ACCEPT_CALL
usercategory	For NMS ISDN, this field is always 0.
tollcategory	For NMS ISDN, this field is always 0.
stream	This field and timeslot together indicate the address of the B channel. Use if the TCP is in Non-Exclusive Mode (see Chapter 6).
timeslot	This field and stream together indicate the address of the B channel. Use if the TCP is in Non-Exclusive Mode (see Chapter 6).
billingrate	Billing rate of call. Not implemented for NMS ISDN; always 0.
callednumplan	Q.931 numbering plan of called address.
callednumtype	Q.931 numbering type of called address.
callingnumplan	Q.931 numbering plan of calling address.
callingnumtype	Q.931 numbering type of calling address.
callingpres	Q.931 presentation indicator for calling address.
callingscreen	Q.931 screening indicator for calling address.
progressdescr	Q.931 progress description in progress information element.
releasecause	Q.931 cause for call release.
redirectingaddr	The redirecting address.
redirectingplan	Q.931 numbering plan of redirecting address.
redirectingtype	Q.931 numbering type of redirecting address.
redirectingpres	Q.931 presentation indicator for redirecting address.
redirectingscreen	Q.931 screening indicator for redirecting numbers.
redirectingreason	Q.931 reason for redirection.
originalcalledaddr	Original called number (OCN).
origcalledplan	Q.931 numbering plan ID.
origcalledtype	Q.931 number type.
origcalledpres	Original called number presentation indicator.
origcalledscreen	Q.931 redirecting number screen indicator.
origcalledreason	Q.931 reason for redirection.
UUI	User-to-user information (Up to 132 characters).

Each ISDN variant fills different fields in the ADI_CALL_STATUS structure at different times. The following table shows which fields are filled by which variant. Unless otherwise indicated, each field may be filled at any time.

Field	DMS	NI2	4ESS	5ESS	NTT	AU S	HKT	KOR	TWN	VN6	EUR	QSIG
size	x	x	x	x	x	x	x	x	x	x	x	x
state	x	x	x	x	x	x	x	x	x	x	x	x
reason	x	x	x	x	x	x	x	x	x	x	x	x
calledaddr	x	x	x	x	x	x	x	x	x	x	x	x
callingaddr	x	x	x	x	x	x	x	x	x	x	x	x
callingname	x	x	x	x	x	x	x	x	x	x	x	x
pendingcommand	x	x	x	x	x	x	x	x	x	x	x	x
usercategory	-	-	-	-	-	-	-	-	-	-	-	-
tollcategory	-	-	-	-	-	-	-	-	-	-	-	-
stream	x	x	x	x	x	x	x	x	x	x	x	x
timeslot	x	x	x	x	x	x	x	x	x	x	x	x
billingrate	-	-	-	-	-	-	-	-	-	-	-	-
callednumplan	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1
callednumtype	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1
callingnumplan	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1
callingnumtype	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1
callingpres	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1
callingscreen	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1	x1
progressdescr	-	-	-	-	-	-	-	-	-	-	-	-
releasecause	x3	x3	x3	x3	x3	x3	x3	x3	x3	x3	x3	x3
redirectingaddr	x1	x1	x1	x1	-	-	-	-	-	x1	-	-
redirectingplan	x1	x1	x1	x1	-	-	-	-	-	-	-	-
redirectingtype	x1	x1	x1	x1	-	-	-	-	-	x1	-	-
redirectingpres	x1	x1	x1	x1	-	-	-	-	-	x1	-	-
redirectingscreen	x1	x1	x1	x1	-	-	-	-	-	x1	-	-
redirectingreason	x1	x1	x1	x1	-	-	-	-	-	x1	-	-
originalcalledaddr	x1	-	-	-	-	-	-	-	-	-	-	-
origcalledplan	x1	-	-	-	-	-	-	-	-	-	-	-
origcalledtype	x1	-	-	-	-	-	-	-	-	-	-	-
origcalledpres	x1	-	-	-	-	-	-	-	-	-	-	-
origcalledscreen	x1	-	-	-	-	-	-	-	-	-	-	-
origcalledreason	x1	-	-	-	-	-	-	-	-	-	-	-
UUI	-	x1,2,3	x1,2,3	x1,3	x1,2,3	-	x1,3	x1,2,3	x1,2,3	x1,2,3	x1,2,3	x2,3

1 Field may be filled at the beginning of the call.

2 Field may be filled when the call is alerting.

3 Field may be filled when the call is released.

5.6 Using Extended Arguments

An application can send various types of ISDN-specific information during certain call control operations. This information includes address information, user-to-user information (UUI), and other values.

The information is sent in extended argument structures. An application can send extended arguments during the following operations:

• Call establishment (with adiPlaceCall)

• Call answering (with adiAnswerCall)

• Call accepting (with adiAcceptCall)

• Call rejection (with adiRejectCall)

• Call release (with adiReleaseCall)

In each case, the information is sent when the function call is made.

To specify the information to be sent:

1. Fill one of the data structures specified below. To fill the data structure, use the macros specified with the structure. As the name for the pointer to the structure, use p_data.

2. Call adiSetExtendedArgs, presenting the information in one of the data structures specified in the following pages.

The information is sent when the next call to adiAcceptCall, adiAnswerCall, adiPlaceCall, adiRejectCall, or adiReleaseCall is made, depending upon which data structure is filled. The call control function will get the new arguments from the data structure, pass them to the TCP, and clear the pointer to the arguments structure.

Not all fields in these data structures can be used at all times. The fields valid for a given message differ depending upon the network protocol variant used, and the actual ISDN message sent on the trunk in response to the function call. Note that the fields valid for a function depend not on the function itself, but on the ISDN message that the function sends on the trunk (for example, SETUP, CALL PROCEEDING, and so on). For adiAnswerCall, adiAcceptCall, and adiRejectCall, the message sent by each function depends upon the setting of the ADI.ISD.flags parameter. Refer to Appendix A for more information about NMS ISDN TCP parameters.

Note: Only one message of a given type (CALL PROCEEDING, PROGRESS, ALERTING, etc.) may be sent to the network. For example, if your application sets the ADI.ISD.flags parameter such that a PROGRESS message is to be sent with the adiAcceptCall and adiRejectCall functions, and then invokes both functions, only one PROGRESS message will be sent.

For more information about extended call control arguments, see the ADI Service Function Reference Manual.

5.6.1 adiPlaceCall Extended Parameters

The following is the adiPlaceCall extended parameter structure for NMS ISDN:

typedef struct

{

DWORD size; /* Size of this structure */

char uui[132]; /* UUI */

ISDN_CALLEDNUMBER callednumber; /* Called number substructure */

ISDN_CALLINGNUMBER callingnumber; /* Calling number substructure */

ISDN_REDIRECTINGNUMBER redirectingnumber; /* Redir num substructure */

WORD service; /* Service */

WORD nsf_present; /* NSF usage flag */

WORD nsf_service_feature; /* Service or feature is set in the */

/* coding field */

WORD nsf_facility_coding; /* NSF coding */

} ISDNPLACECALL_EXTARGS;

adiPlaceCall always causes a SETUP message to be sent on the trunk. The following table shows the fields in ISDNPLACECALL_EXTARGS which are valid for each network variant:

ISDNPLACECALL_EXTARGS Field	4ESS	E10	NI2	DMS100	ETSI	VN6	HKG	AUSTEL1	NTT	KOREA	TAIWAN	QSIG
uui	x	x	x		x	x			x	x	x
callednumber	x	x	x	x	x	x	x	x	x	x	x	x
callingnumber	x	x	x	x	x	x	x	x	x	x	x	x
redirectingnumber	x	x	x	x
service	x	x	x	x	x	x	x	x	x	x	x	x
nsf_present	x
nsf_service_feature	x
nsf_facility_coding	x

The following is a list of macros to use to access the fields in the ISDNPLACECALL_EXTARGS structure, and in substructures referenced by this structure. Macros beginning with set assign values; those beginning with get retrieve set values.

Parameter	Macros	Description
size	set_isdn_placecall_size get_isdn_placecall_size	Size of ISDNPLACECALL_EXTARGS
uui	isdn_placecall_a_uui	Pointer to a string with user-to-user information (132 chars max)
callednumber	set_isdn_placecall_called_nb_size get_isdn_placecall_called_nb_size	Size of called number
	set_isdn_placecall_called_nb_plan get_isdn_placecall_called_nb_plan	Q.931 numbering plan of called address
	set_isdn_placecall_called_nb_type get_isdn_placecall_called_nb_type	Q.931 numbering type of called address
callingnumber	set_isdn_placecall_calling_nb_size get_isdn_placecall_calling_nb_size	Size of calling number
	set_isdn_placecall_calling_nb_plan get_isdn_placecall_calling_nb_plan	Q.931 numbering plan of calling address
	set_isdn_placecall_calling_nb_type get_isdn_placecall_calling_nb_type	Q.931 numbering type of calling address
	set_isdn_placecall_calling_nb_screen get_isdn_placecall_calling_nb_screen	Q.931 ANI screening indicator
	set_isdn_placecall_calling_nb_presentation get_isdn_placecall_calling_nb_presentation	Q.931 caller ID presentation indicator
redirectingnumber	set_isdn_placecall_redirecting_nb_size get_isdn_placecall_redirecting_nb_size	Size of redirecting address
	isdn_placecall_redirecting_nb_a_digits	Redirecting address
	set_isdn_placecall_redirecting_nb_plan get_isdn_placecall_redirecting_nb_plan	Q.931 numbering plan of redirecting address
	set_isdn_placecall_redirecting_nb_type get_isdn_placecall_redirecting_nb_type	Q.931 numbering type of redirecting address
	set_isdn_placecall_redirecting_nb_screen get_isdn_placecall_redirecting_nb_screen	Q.931 redirecting address screening indicator
	set_isdn_placecall_redirecting_nb_presentation get_isdn_placecall_redirecting_nb_presentation	Q.931 redirecting address presentation indicator
	set_isdn_placecall_redirecting_nb_reason get_isdn_placecall_redirecting_nb_reason	Q.931 reason for redirection
service	set_isdn_placecall_service get_isdn_placecall_serivce	Service
nsf_present	set_isdn_placecall_nsf_present get_isdn_placecall_nsf_present	Network-Specific Facilities usage flag
nsf_service_feature	set_isdn_placecall_nsf_service_feature get_isdn_placecall_nsf_service_feature	Service or feature is set in the coding field
nsf_facility_coding	set_isdn_placecall_nsf_facility_coding get_isdn_placecall_nsf_facility_coding	NSF service or feature ID

5.6.2 adiAnswerCall Extended Parameters

The following is the adiAnswerCall extended parameter structure for NMS ISDN:

typedef struct

{

DWORD size; /* Size of this structure */

char uui [132]; /* UUI */

} ISDNANSWERCALL_EXTARGS;

adiAnswerCall generates an ALERTING message by default. The following table shows the fields in ISDNANSWERCALL_EXTARGS which are valid in this case for each network variant:

ISDNANSWERCALL_EXTARGS Field	4ESS	E10	NI2	DMS100	ETSI	VN6	HKG	AUSTEL1	NTT	KOREA	TAIWAN	QSIG
uui	x	x			x	x			x	x	x

By changing the setting of the ADI.ISD.flags parameter, adiAnswerCall can be made to send a CALL PROCEEDING or PROGRESS message instead of the ALERTING message. No UUI may be sent in this case.

The following is a list of macros to use to access the fields in the ISDNANSWERCALL_EXTARGS structure:

Parameter	Macros	Description
uui	isdn_answercall_a_uui	Pointer to a string with user-to-user information (132 chars max)

5.6.3 adiAcceptCall Extended Parameters

The following is the adiAcceptCall extended parameter structure for NMS ISDN:

typedef struct

{

DWORD size; /* Size of this structure */

char uui [132]; /* UUI */

WORD cause; /* Cause value */

WORD progressdescription; /* Progress description */

} ISDNACCEPTCALL_EXTARGS;

adiAcceptCall generates a PROGRESS message by default. The following table shows the fields in ISDNACCEPTCALL_EXTARGS which are valid in this case for each network variant:

ISDNACCEPTCALL_EXTARGS Field (PROGRESS message)	4ESS	E10	NI2	DMS100	ETSI	VN6	HKG	AUSTEL1	NTT	KOREA	TAIWAN	QSIG
uui	Not sent
cause	x	x	x	x	x
progressdescription	x	x	x	x	x

By changing the setting of the ADI.ISD.flags parameter, adiAcceptCall can be made to send a CALL PROCEEDING or ALERTING message instead of the PROGRESS message. In the case of CALL PROCEEDING, no extended parameters can be sent. In the case of an ALERTING message, the UUI and progressdescription fields are valid for certain variants:

ISDNACCEPTCALL_EXTARGS Field (ALERTING message)	4ESS	E10	NI2	DMS100	ETSI	VN6	HKG	AUSTEL1	NTT	KOREA	TAIWAN	QSIG
uui					x	x			x	x	x
cause	Not sent
progressdescription	Not sent

The following is a list of macros to use to access the fields in the ISDNACCEPTCALL_EXTARGS structure. Macros beginning with set assign values; those beginning with get retrieve set values.

Parameter	Macros	Description
size	set_isdn_acceptcall_size get_isdn_acceptcall_size	Size of ISDNACCEPTCALL_EXTARGS
uui	isdn_acceptcall_a_uui	Pointer to a string with user-to-user information (132 chars max)
cause	set_isdn_acceptcall_cause get_isdn_acceptcall_cause	Cause
progressdescription	set_isdn_acceptcall_progressdescription get_isdn_acceptcall_progressdescription	Progress description

5.6.4 adiRejectCall Extended Parameters

The following is the adiRejectCall extended parameter structure for NMS ISDN:

typedef struct

{

DWORD size; /* Size of this structure */

char uui [132]; /* UUI */

WORD cause; /* Disconnect cause (NCC value) */

WORD pad;

} ISDNREJECTCALL_EXTARGS;

The following table shows the fields in ISDNREJECTCALL_EXTARGS which are valid for each network variant:

ISDNREJECTCALL_EXTARGS Field	4ESS	E10	NI2	DMS100	ETSI	VN6	HKG	AUSTEL1	NTT	KOREA	TAIWAN	QSIG
uui	x	x	x		x	x			x	x	x
cause	x	x	x	x	x	x	x	x	x	x	x	x

adiRejectCall generates a PROGRESS message by default. If this message is sent, only the cause field is used.

By changing the setting of the ADI.ISD.flags parameter, adiRejectCall can be made to send a CALL PROCEEDING or ALERTING message instead of the PROGRESS message. In the case of ALERTING, only the uui field is sent. In the case of CALL PROCEEDING, no extended parameters can be sent.

The following is a list of macros to use to access the fields in the ISDNREJECTCALL_EXTARGS structure. Macros beginning with set assign values; those beginning with get retrieve set values.

Parameter	Macros	Description
size	set_isdn_rejectcall_size get_isdn_rejectcall_size	Size of ISDNREJECTCALL_EXTARGS
uui	isdn_rejectcall_a_uui	Pointer to a string with user-to-user information (132 chars max)
cause	set_isdn_rejectcall_cause get_isdn_rejectcall_cause	Cause

5.6.5 adiReleaseCall Extended Parameters

The following is the adiReleaseCall extended parameter structure for NMS ISDN:

typedef struct

{

DWORD size; /* Size of this structure */

char uui [132]; /* UUI */

WORD cause; /* Disconnect cause (NCC value) */

WORD pad;

} ISDN RELEASECALL_EXTARGS;

adiReleaseCall generates one of two messages, depending upon which side initiates the release:

• If the remote side initiated the clearing, adiReleaseCall sends a RELEASE message. No extended arguments can be sent in this case.

• If the application initiated the call clearing process, adiReleaseCall sends a DISCONNECT message.

The following table shows the fields in ISDNRELEASECALL_EXTARGS which are valid in this case for each network variant:

ISDNRELEASECALL_EXTARGS Field (DISCONNECT message)	4ESS	E10	NI2	DMS100	ETSI	VN6	HKG	AUSTEL1	NTT	KOREA	TAIWAN	QSIG
uui	x		x		x	x			x	x	x
cause	x	x	x	x	x	x	x	x	x	x	x	x

The following is a list of macros to use to access the fields in the ISDNRELEASECALL_EXTARGS structure. Macros beginning with set assign values; those beginning with get retrieve set values.

Parameter	Macros	Description
size	set_isdn_disconnectcall_size get_isdn_disconnectcall_size	Size of ISDNRELEASECALL_EXTARGS
uui	isdn_disconnectcall_a_uui	Pointer to a string with user-to-user information (132 chars max)
cause	set_isdn_disconnectcall_cause get_isdn_disconnectcall_cause	Cause

5.6.6 Receiving User-to-User Information (UUI)

User-to-user information (UUI) may be presented to the application at any time during a call. When user-to-user information is received, an ADIEVN_STATUSINFO_UPDATE event is generated. The value field contains CALL_STATUS_UUI.

The UUI information is available in the ADI_CALL_STATUS structure. (See Section 5.5 for a listing of this structure.) It can be retrieved using adiGetCallStatus.

Only text UUI is supported.

5.6.7 Recieving Charging Information

Charging information is contained within the NCC_ISDN_EXT_CALL_STATUS structure, and can be accessed by invoking nccGetExtendedCallStatus. Charging information may be sent to an application after a call has reached the CONNECTED state.

Note: Charging is supported for the TE side of the VN6/FRANCE variant only.