(Page 1 of 1 in this chapter) Version

Chapter 2

The Natural Call Control API

2.1 Introduction

2.2 NCC Service Call Control Model

: 2.2.1 Lines and Calls
: 2.2.2 Call Control States

2.3 NCC Service Functions

2.4 NCC Service Events

2.5 Protocol Capabilities

2.6 NCC Service State Machines

: 2.6.1 Line States
: 2.6.2 Call States
: 2.6.3 Functions and States
: 2.6.4 Events and States

2.1 Introduction

This chapter: Discusses the NCC service call control model. Summarizes the NCC service functions. Functions are grouped according to the tasks they perform. Summarizes NCC service events. Transitional events (events that signify a state change) and informational events are listed separately. Describes how to determine the capabilities of a protocol. Illustrates and discusses the NCC service line and call state machines. Note: ADI users: the NCC API and call control model differs substantially from ADI. See Appendix E for information about migrating from ADI to NCC.

2.2 NCC Service Call Control Model

This section introduces the NCC service call control model, and defines some key concepts.

2.2.1 Lines and Calls

The NCC service call control model differentiates between lines and calls: A line is a logical representation of a channel on a trunk. A call is a connection between two parties (or a connection in the making, or a former connection) on a line. Multiple calls can exist simultaneously on a line. However, only one call at a time can be Active (i.e., not disconnected or held).
Programmatically, a line is referenced using a line handle. The line handle is equivalent to the CTA context handle.
A call is referenced using a call handle. When a call handle is referenced in a function call, the line handle is referenced implicitly.
When a line event occurs, the event indication includes the line handle. When a call event occurs, the event indication includes both the line handle and call handle. (For more information about receiving NCC service events, see Section 3.2.4.)

2.2.2 Call Control States

In the NCC service call control model, the state is the condition or status of a line or call. The model defines a set of specific states that a line or call can be in as long as it exists. For each state, a certain set of occurrences (e.g., a specific function call by the application, or actions by the remote party) is defined, which may cause the line or call to change to another state. Whenever a state change occurs, the application receives an appropriate event.
The NCC service call control model differentiates between line states and call states. A line can be in any of five possible states. A call on the line can be in any of 11 states.
To determine the current state of a call or line, the application can invoke status retrieval functions. For more information, see Chapter 6.
The following table lists the line states, and descriptions for each. Figure 4 illustrates the line states, and shows events indicating transitions between them. Line State Description Uninitialized Initial state of line. Signifies that a protocol has not yet been started. Idle Signifies that no Active calls currently exist on the line. If there are any calls on the line, they are either held or in Disconnected call state. The line is now prepared to accept an incoming call or place an outbound call. Active Signifies that there is at least one Active call on this line. Blocking Signifies that all inbound and outbound calls are blocked. Out of Service Signifies that the network has placed the line out of service.
If all calls on a line are held or in Disconnected call state (i.e., all calls are inactive), the line state changes to Idle. If a call becomes Active on the line (i.e., a held call is retrieved or a new call comes in or is placed), the line state returns to Active.
The following is a list of call states, and descriptions for each. Figure 5 illustrates the call states, and shows events indicating transitions between them. Call State Description Inbound Call States: Seizure First indication of a call that is being set up (seized). The event contains a call handle to identify the call for subsequent call-based functions. Receiving Digits (optional) Signifies that a set of one or more incoming digits can be expected in order to fully qualify the incoming call. Incoming Signifies that a call has been delivered from the network to the NCC service. Accepting (optional) Signifies that a call has been accepted by the application but has not yet been answered or rejected. When a call is in this state, the application can play media functions (such as playing a voice file) before connecting or rejecting the call. Answering Signifies that the NCC service is in the process of answering the call and establishing a connection. Rejecting Signifies that the NCC service is in the process of rejecting the inbound call. Outbound Call States: Outbound Initiated Signifies that a call has been initiated. Placing Signifies that the line has been seized and that the network has allowed the call to be placed by the NCC service. In other words, glare has been resolved. At this point, NCC initiates dialing. Proceeding (optional) Signifies that the switch has accepted the call setup request and is in the process of attempting to ring the receiving end. Call progress analysis is begun. Connected/Disconnected Call States: Connected Signifies that a connection now exists between the calling parties. The application can now use DSP resources if necessary. Disconnected Signifies that the connection no longer exists. A disconnected call is no longer Active.

Line State	Description
Uninitialized	Initial state of line. Signifies that a protocol has not yet been started.
Idle	Signifies that no Active calls currently exist on the line. If there are any calls on the line, they are either held or in Disconnected call state. The line is now prepared to accept an incoming call or place an outbound call.
Active	Signifies that there is at least one Active call on this line.
Blocking	Signifies that all inbound and outbound calls are blocked.
Out of Service	Signifies that the network has placed the line out of service.

Call State	Description
Inbound Call States:
Seizure	First indication of a call that is being set up (seized). The event contains a call handle to identify the call for subsequent call-based functions.
Receiving Digits (optional)	Signifies that a set of one or more incoming digits can be expected in order to fully qualify the incoming call.
Incoming	Signifies that a call has been delivered from the network to the NCC service.
Accepting (optional)	Signifies that a call has been accepted by the application but has not yet been answered or rejected. When a call is in this state, the application can play media functions (such as playing a voice file) before connecting or rejecting the call.
Answering	Signifies that the NCC service is in the process of answering the call and establishing a connection.
Rejecting	Signifies that the NCC service is in the process of rejecting the inbound call.
Outbound Call States:
Outbound Initiated	Signifies that a call has been initiated.
Placing	Signifies that the line has been seized and that the network has allowed the call to be placed by the NCC service. In other words, glare has been resolved. At this point, NCC initiates dialing.
Proceeding (optional)	Signifies that the switch has accepted the call setup request and is in the process of attempting to ring the receiving end. Call progress analysis is begun.
Connected/Disconnected Call States:
Connected	Signifies that a connection now exists between the calling parties. The application can now use DSP resources if necessary.
Disconnected	Signifies that the connection no longer exists. A disconnected call is no longer Active.

2.3 NCC Service Functions

The following sections summarize NCC service functions according to the tasks they perform. With each function is listed:

A brief description.

An indication as to whether the function is synchronous (is complete when the return value is received) or asynchronous (return value indicates success or failure of function call; execution result arrives asynchronously via an event).

Note: Not all functions are supported by all protocols. The developer should consult the protocol documentation, or call nccQueryCapability at runtime to determine if an optional function is supported or not. (See Section 2.5).

Managing Telephony Protocols

After setting up the NCC service, you must initialize a telephony protocol on each line in order to perform telephony activities. To do so, start up a trunk control program (TCP) on the line.
Refer to your telephony protocols manual for more information about telephony protocols and associated trunk control program (TCPs).
The NCC service provides the following functions to manage telephony protocols:

Function

S/A ¹

Description

nccStartProtocol

A

Loads a Trunk Control Program (TCP) on AG boards or a Dynamic Link Library (DLL) for QX boards and enables the use of functions requiring DSP resources.

nccStopProtocol

A

Halts the TCP on the line, terminates functions on the line, and unloads the TCP.

¹ Synchronous or Asynchronous

Function	S/A ¹	Description
nccStartProtocol	A	Loads a Trunk Control Program (TCP) on AG boards or a Dynamic Link Library (DLL) for QX boards and enables the use of functions requiring DSP resources.
nccStopProtocol	A	Halts the TCP on the line, terminates functions on the line, and unloads the TCP.

Handling Incoming Calls

The NCC service provides the following functions to handle incoming calls:

Function

S/A ¹

Description

nccAcceptCall

A

Accepts an incoming call.

nccAnswerCall

A

Answers an incoming call.

nccRejectCall

A

Rejects an incoming call.

¹ Synchronous or Asynchronous

Function	S/A ¹	Description
nccAcceptCall	A	Accepts an incoming call.
nccAnswerCall	A	Answers an incoming call.
nccRejectCall	A	Rejects an incoming call.

Establishing Outgoing Calls

The NCC service provides the following functions to establish outgoing calls:

Function

S/A ¹

Description

nccPlaceCall

A

Places an outbound call.

nccSendDigits

S

Sends digits in overlapped sending mode.

¹ Synchronous or Asynchronous

Function	S/A ¹	Description
nccPlaceCall	A	Places an outbound call.
nccSendDigits	S	Sends digits in overlapped sending mode.

Holding and Transferring Calls

The NCC service provides the following functions to perform call holding, retrieving and transfer:

Function

S/A ¹

Description

nccAutomaticTransfer

A

Completes blind transfer of two calls.

nccHoldCall

A

Put a call on hold.

nccRetrieveCall

A

Retrieves a held call.

nccTransferCall

A

Completes supervised transfer of two calls.

¹ Synchronous or Asynchronous

Function	S/A ¹	Description
nccAutomaticTransfer	A	Completes blind transfer of two calls.
nccHoldCall	A	Put a call on hold.
nccRetrieveCall	A	Retrieves a held call.
nccTransferCall	A	Completes supervised transfer of two calls.

Disconnecting and Releasing Calls

The NCC service provides the following functions to disconnect and release calls:

Function

S/A ¹

Description

nccDisconnectCall

A

Disconnects a connected call.

nccReleaseCall

A

Releases resources associated with a call in the Disconnected state, and destroys the call handle.

¹ Synchronous or Asynchronous

Function	S/A ¹	Description
nccDisconnectCall	A	Disconnects a connected call.
nccReleaseCall	A	Releases resources associated with a call in the Disconnected state, and destroys the call handle.

Getting Status and Capability Information

The NCC service provides the following functions to get line and call status information, and protocol capability information:

Function

S/A ¹

Description

nccGetCallStatus

S

Retrieves call control status information for a call.

nccGetExtendedCallStatus

S

Retrieves protocol-specific call control status information for a call.

nccGetLineStatus

S

Retrieves status information for a line.

nccQueryCapability

S

Queries capabilities of the current protocol.

¹ Synchronous or Asynchronous

Function	S/A ¹	Description
nccGetCallStatus	S	Retrieves call control status information for a call.
nccGetExtendedCallStatus	S	Retrieves protocol-specific call control status information for a call.
nccGetLineStatus	S	Retrieves status information for a line.
nccQueryCapability	S	Queries capabilities of the current protocol.

Sending Call and Line Messages

The following NCC service functions provide escape mechanisms to send protocol-specific messages:

Function

S/A ¹

Description

nccSendCallMessage

P ²

Protocol-specific escape mechanism to send a message to a call.

nccSendLineMessage

P

Protocol-specific escape mechanism to send a message to a line.

¹ Synchronous or Asynchronous
² Protocol-dependent

Function	S/A ¹	Description
nccSendCallMessage	P ²	Protocol-specific escape mechanism to send a message to a call.
nccSendLineMessage	P	Protocol-specific escape mechanism to send a message to a line.

Blocking and Unblocking Calls

The NCC service provides the following functions to block all calls on a line:

Function

S/A ¹

Description

nccBlockCalls

A

Blocks incoming calls.

nccUnBlockCalls

A

Releases blocking of incoming calls.

¹ Synchronous or Asynchronous

Function	S/A ¹	Description
nccBlockCalls	A	Blocks incoming calls.
nccUnBlockCalls	A	Releases blocking of incoming calls.

Setting Billing

The NCC service provides the following function to configure billing:

Function

S/A ¹

Description

nccSetBilling

A

Sets billing relative to an incoming call.

¹ Synchronous or Asynchronous

Function	S/A ¹	Description
nccSetBilling	A	Sets billing relative to an incoming call.

2.4 NCC Service Events

When performing call control functions, the NCC service processes events: both those that arrive from the network, and those that are generated in response to NCC service commands. The NCC service translates the network events into generic call control events. The names are defined in uppercase letters with an NCCEVN_ 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 NCC 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, NCCEVN_PROTOCOL_ERROR, provides information about abnormalities on the line including false seizure, too many incoming digits, or premature answer while dialing.
Events are also classified as solicited or unsolicited. Solicited events are generated as a result of an application executing a command. Unsolicited events are the consequences of activities on the network.
Some NCC service events are solicited events in some circumstances, and unsolicited events in other circumstances. Refer to Section 2.6.4, Events and States, for more details.
The following sections summarize NCC service events according to the operations they are associated with. With each event is listed: A brief description. An indication as to whether the event is informational or transitional. An indication as to whether the event is solicited, unsolicited, or both.
Some events are generated only if you enable them by setting them in the NCC.START.eventmask parameter. For more information about this parameter, see Appendix D.

Managing Telephony Protocols

The NCC service provides the following events related to managing telephony protocols: Event I/T ¹ S/U ² Indicates that... NCCEVN_START_PROTOCOL_DONE T S The application has attempted to start a protocol on a CT Access context (line handle). NCCEVN_STOP_PROTOCOL_DONE T S The protocol has stopped running on the CT Access context. Line is uninitialized. ¹ Informational or Transitional ² Solicited or Unsolicited

Event	I/T ¹	S/U ²	Indicates that...
NCCEVN_START_PROTOCOL_DONE	T	S	The application has attempted to start a protocol on a CT Access context (line handle).
NCCEVN_STOP_PROTOCOL_DONE	T	S	The protocol has stopped running on the CT Access context. Line is uninitialized.

Handling Incoming Calls

The NCC service provides the following events related to handling incoming calls: Event I/T ¹ S/U ² Indicates that... NCCEVN_ACCEPTING_CALL T S The application has accepted the call referenced by the call handle. NCCEVN_ANSWERING_CALL T S The application has answered the call referenced by the call handle. NCCEVN_CALL_CONNECTED T U Both parties are connected. NCCEVN_INCOMING_CALL T U All information related to an incoming call has been collected, and is now presented to the application. NCCEVN_RECEIVED_DIGIT T U Digits are being received in an overlapped fashion for an incoming call. NCCEVN_REJECTING_CALL T S/U A call is being rejected. NCCEVN_SEIZURE_DETECTED T U The line has been seized by the network. ¹ Informational or Transitional ² Solicited or Unsolicited

Event	I/T ¹	S/U ²	Indicates that...
NCCEVN_ACCEPTING_CALL	T	S	The application has accepted the call referenced by the call handle.
NCCEVN_ANSWERING_CALL	T	S	The application has answered the call referenced by the call handle.
NCCEVN_CALL_CONNECTED	T	U	Both parties are connected.
NCCEVN_INCOMING_CALL	T	U	All information related to an incoming call has been collected, and is now presented to the application.
NCCEVN_RECEIVED_DIGIT	T	U	Digits are being received in an overlapped fashion for an incoming call.
NCCEVN_REJECTING_CALL	T	S/U	A call is being rejected.
NCCEVN_SEIZURE_DETECTED	T	U	The line has been seized by the network.

Establishing Outgoing Calls

The NCC service provides the following events related to placing outbound calls: Event I/T ¹ S/U ² Indicates that... NCCEVN_CALL_CONNECTED T U Both parties are connected. NCCEVN_CALL_PROCEEDING T U The switch has accepted the call setup. The receiving side is being rung. NCCEVN_PLACING_CALL T S A call was placed successfully. NCCEVN_REMOTE_ALERTING I S The remote end is ringing. NCCEVN_REMOTE_ANSWERED I S The remote end is answering the call. ¹ Informational or Transitional ² Solicited or Unsolicited

Event	I/T ¹	S/U ²	Indicates that...
NCCEVN_CALL_CONNECTED	T	U	Both parties are connected.
NCCEVN_CALL_PROCEEDING	T	U	The switch has accepted the call setup. The receiving side is being rung.
NCCEVN_PLACING_CALL	T	S	A call was placed successfully.
NCCEVN_REMOTE_ALERTING	I	S	The remote end is ringing.
NCCEVN_REMOTE_ANSWERED	I	S	The remote end is answering the call.

Holding and Retrieving Calls

The NCC service provides the following events related to placing calls on hold, and retrieving calls: Event I/T ¹ S/U ² Indicates that... NCCEVN_CALL_HELD T S/U A call was placed on hold, by the application or by a remote party. NCCEVN_CALL_RETRIEVED T S/U A held call was retrieved, by the application or by a remote party. NCCEVN_HOLD_REJECTED I S A request to put a call on hold was rejected. NCCEVN_RETRIEVE_REJECTED I S A retrieve call request was rejected. ¹ Informational or Transitional ² Solicited or Unsolicited

Event	I/T ¹	S/U ²	Indicates that...
NCCEVN_CALL_HELD	T	S/U	A call was placed on hold, by the application or by a remote party.
NCCEVN_CALL_RETRIEVED	T	S/U	A held call was retrieved, by the application or by a remote party.
NCCEVN_HOLD_REJECTED	I	S	A request to put a call on hold was rejected.
NCCEVN_RETRIEVE_REJECTED	I	S	A retrieve call request was rejected.

Disconnecting and Releasing Calls

The NCC service provides the following events related to disconnecting and releasing calls: Event I/T ¹ S/U ² Indicates that... NCCEVN_CALL_DISCONNECTED T S/U A call was disconnected, by the application or by a remote party. NCCEVN_CALL_RELEASED T S The application has released a call; NCC has released all internal resources for the call. ¹ Informational or Transitional ² Solicited or Unsolicited

Event	I/T ¹	S/U ²	Indicates that...
NCCEVN_CALL_DISCONNECTED	T	S/U	A call was disconnected, by the application or by a remote party.
NCCEVN_CALL_RELEASED	T	S	The application has released a call; NCC has released all internal resources for the call.

Getting Status and Capability Information

The NCC service provides the following events related to getting status and capability information: Event I/T ¹ S/U ² Indicates that... NCCEVN_CALL_STATUS_UPDATE I U A call's status has changed. NCCEVN_CAPABILITY_UPDATE I U Protocol capabilities have changed. NCCEVN_EXTENDED_CALL_STATUS_UPDATE I U A call's extended call status information has changed. ¹ Informational or Transitional ² Solicited or Unsolicited

Event	I/T ¹	S/U ²	Indicates that...
NCCEVN_CALL_STATUS_UPDATE	I	U	A call's status has changed.
NCCEVN_CAPABILITY_UPDATE	I	U	Protocol capabilities have changed.
NCCEVN_EXTENDED_CALL_STATUS_UPDATE	I	U	A call's extended call status information has changed.

Blocking and Unblocking Calls

The NCC service provides the following events related to blocking and unblocking all calls on a line: Event I/T ¹ S/U ² Indicates that... NCCEVN_BLOCK_FAILED I S A request to block calls on a line failed. NCCEVN_CALLS_BLOCKED T S The application has blocked all calls on a line. NCCEVN_CALLS_UNBLOCKED T S The line is no longer blocked. NCCEVN_UNBLOCK_FAILED I S A request to unblock a line failed. ¹ Informational or Transitional ² Solicited or Unsolicited

Event	I/T ¹	S/U ²	Indicates that...
NCCEVN_BLOCK_FAILED	I	S	A request to block calls on a line failed.
NCCEVN_CALLS_BLOCKED	T	S	The application has blocked all calls on a line.
NCCEVN_CALLS_UNBLOCKED	T	S	The line is no longer blocked.
NCCEVN_UNBLOCK_FAILED	I	S	A request to unblock a line failed.

Setting Billing

The NCC service provides the following events related to configuring billing: Event I/T ¹ S/U ² Indicates that... NCCEVN_BILLING_INDICATION I U A billing indication has arrived. NCCEVN_BILLING_SET I S A request to set the billing for a call has been completed. ¹ Informational or Transitional ² Solicited or Unsolicited

Event	I/T ¹	S/U ²	Indicates that...
NCCEVN_BILLING_INDICATION	I	U	A billing indication has arrived.
NCCEVN_BILLING_SET	I	S	A request to set the billing for a call has been completed.

Line and Protocol Errors and Events

The NCC service provides the following events related to line and protocol status: Event I/T ¹ S/U ² Indicates that... NCCEVN_LINE_IN_SERVICE T U The network has placed the line in service (was out of service). NCCEVN_LINE_OUT_OF_SERVICE T U The network has placed the line out of service (was in service). NCCEVN_PROTOCOL_ERROR I U An error condition has occurred. The call may be in an unusable state. NCCEVN_PROTOCOL_EVENT I S/U A protocol-specific event has occurred. ¹ Informational or Transitional ² Solicited or Unsolicited

Event	I/T ¹	S/U ²	Indicates that...
NCCEVN_LINE_IN_SERVICE	T	U	The network has placed the line in service (was out of service).
NCCEVN_LINE_OUT_OF_SERVICE	T	U	The network has placed the line out of service (was in service).
NCCEVN_PROTOCOL_ERROR	I	U	An error condition has occurred. The call may be in an unusable state.
NCCEVN_PROTOCOL_EVENT	I	S/U	A protocol-specific event has occurred.

2.5 Protocol Capabilities

Different protocols support different capabilities. Once a protocol has been started, the application can query it to determine the call control features it supports. For an application supporting multiple protocols, this information is important as it determines which function calls are valid, and which events the application can expect to receive.
To retrieve protocol capability information, the application calls the NCC service function nccQueryCapability. This synchronous function returns a capabilitymask, where each bit in the mask indicates whether or not the TCP supports a particular capability.
The following table describes each bit in the capabilitymask returned by nccQueryCapability:

Mnemonic

If bit is set...

NCC_CAP_ACCEPT_CALL

The protocol supports the Accepting call state in the inbound call control state machine. Application may invoke nccAcceptCall function.

NCC_CAP_SET_BILLING

The application may set billing parameters using nccSetBilling.

NCC_CAP_OVERLAPPED_SENDING

The protocol supports overlapped sending of digits, using nccSendDigits.

NCC_CAP_HOLD_CALL

The protocol allows calls to be placed on hold using nccHoldCall. Calls can then be retrieved using nccRetrieveCall.

NCC_CAP_SUPERVISED_TRANSFER

The protocol supports supervised call transfer. Application may invoke nccTransferCall.

NCC_CAP_AUTOMATIC_TRANSFER

The protocol supports blind call transfer. Application may invoke nccAutomaticTransfer.

NCC_CAP_EXTENDED_CALL_STATUS

The protocol supports the ability to get protocol-specific call status information using nccGetExtendedCallStatus.

NCC_CAP_SEND_CALL_MESSAGE

The protocol supports sending of a protocol-specific call message using nccSendCallMessage.

NCC_CAP_SEND_LINE_MESSAGE

The protocol supports sending of a protocol-specific line message using nccSendLineMessage.

NCC_CAP_HOLD_IN_ANY_STATE

The protocol allows a call to be placed on hold in any state. By default, a call can be placed on hold only if it is in the Connected state.

NCC_CAP_DISCONNECT_IN_ANY_STATE

The application can call nccDisconnectCall regardless of the call state. If this bit is not set, nccDisconnectCall may only be invoked in the Connected or Placing call states.

NCC_CAP_MEDIA_IN_SETUP

The protocol contains embedded media capability. Application may:
· Use "play ring" and "user audio" modes when invoking nccAcceptCall.
· Use "play ring", "play busy", "play reorder", and "play user audio" modes when invoking nccRejectCall.

NCC_CAP_CALLER_ID

The protocol supports caller ID. Caller ID information is returned in the callingaddr field in the NCC_CALL_STATUS structure.
If the capabilities of a protocol change, the application receives NCCEVN_CAPABILITY_UPDATE. The application can then invoke nccQueryCapability to determine the changes.

Mnemonic	If bit is set...
NCC_CAP_ACCEPT_CALL	The protocol supports the Accepting call state in the inbound call control state machine. Application may invoke nccAcceptCall function.
NCC_CAP_SET_BILLING	The application may set billing parameters using nccSetBilling.
NCC_CAP_OVERLAPPED_SENDING	The protocol supports overlapped sending of digits, using nccSendDigits.
NCC_CAP_HOLD_CALL	The protocol allows calls to be placed on hold using nccHoldCall. Calls can then be retrieved using nccRetrieveCall.
NCC_CAP_SUPERVISED_TRANSFER	The protocol supports supervised call transfer. Application may invoke nccTransferCall.
NCC_CAP_AUTOMATIC_TRANSFER	The protocol supports blind call transfer. Application may invoke nccAutomaticTransfer.
NCC_CAP_EXTENDED_CALL_STATUS	The protocol supports the ability to get protocol-specific call status information using nccGetExtendedCallStatus.
NCC_CAP_SEND_CALL_MESSAGE	The protocol supports sending of a protocol-specific call message using nccSendCallMessage.
NCC_CAP_SEND_LINE_MESSAGE	The protocol supports sending of a protocol-specific line message using nccSendLineMessage.
NCC_CAP_HOLD_IN_ANY_STATE	The protocol allows a call to be placed on hold in any state. By default, a call can be placed on hold only if it is in the Connected state.
NCC_CAP_DISCONNECT_IN_ANY_STATE	The application can call nccDisconnectCall regardless of the call state. If this bit is not set, nccDisconnectCall may only be invoked in the Connected or Placing call states.
NCC_CAP_MEDIA_IN_SETUP	The protocol contains embedded media capability. Application may: · Use "play ring" and "user audio" modes when invoking nccAcceptCall. · Use "play ring", "play busy", "play reorder", and "play user audio" modes when invoking nccRejectCall.
NCC_CAP_CALLER_ID	The protocol supports caller ID. Caller ID information is returned in the *callingaddr* field in the NCC_CALL_STATUS structure.

2.6 NCC Service State Machines

The NCC service call control model differentiates between line states and call states. The following sections describe NCC service line state and call state machines.

2.6.1 Line States

The following table lists the line states. Associated with each state are one or more transitional events, which indicate transition into the state. These are noted in the table. An application can use nccGetLineStatus to determine the state of a line:

Line State

Description

Active

Entered via NCCEVN_SEIZURE_DETECTED event, when a call is coming in.
Also can be entered via an NCCEVN_CALL_RETRIEVED event, which means a call has become Active and that therefore the line has reentered Active state.

Blocking

Entered via the NCCEVN_CALLS_BLOCKED event, which is solicited by nccBlockCalls.

Idle

Entered via the NCCEVN_START_PROTOCOL_DONE event, which is solicited by nccStartProtocol.
Entered via the NCCEVN_CALLS_UNBLOCKED event, which is solicited by nccUnblockCalls.
Entered via the NCCEVN_LINE_IN_SERVICE event (an unsolicited event).
Entered from the Active state, via an NCCEVN_CALL_HELD or NCCEVN_CALL_DISCONNECTED event. These events mean that a call has been placed on hold or is disconnected, and is therefore not Active. When no calls are Active on a line, the line enters Idle line state.

Out of Service

Entered via the NCCEVN_LINE_OUT_OF_SERVICE event, which is an unsolicited event.

Uninitialized

Initial state of line. When the NCC service is opened on a CT Access context, the line handle (signified by the CT Access handle) has been created in an uninitialized state.
Entered via the NCCEVN_STOP_PROTOCOL_DONE event, which is solicited by nccStopProtocol.
Figure 4 shows the line states, and events indicating transitions between them: Figure 4. NCC Line State Diagram

Line State	Description
Active	Entered via NCCEVN_SEIZURE_DETECTED event, when a call is coming in. Also can be entered via an NCCEVN_CALL_RETRIEVED event, which means a call has become Active and that therefore the line has reentered Active state.
Blocking	Entered via the NCCEVN_CALLS_BLOCKED event, which is solicited by nccBlockCalls.
Idle	Entered via the NCCEVN_START_PROTOCOL_DONE event, which is solicited by nccStartProtocol. Entered via the NCCEVN_CALLS_UNBLOCKED event, which is solicited by nccUnblockCalls. Entered via the NCCEVN_LINE_IN_SERVICE event (an unsolicited event). Entered from the Active state, via an NCCEVN_CALL_HELD or NCCEVN_CALL_DISCONNECTED event. These events mean that a call has been placed on hold or is disconnected, and is therefore not Active. When no calls are Active on a line, the line enters Idle line state.
Out of Service	Entered via the NCCEVN_LINE_OUT_OF_SERVICE event, which is an unsolicited event.
Uninitialized	Initial state of line. When the NCC service is opened on a CT Access context, the line handle (signified by the CT Access handle) has been created in an uninitialized state. Entered via the NCCEVN_STOP_PROTOCOL_DONE event, which is solicited by nccStopProtocol.

2.6.2 Call States

The following table lists the call states. Associated with each state are one or more transitional events, which indicate transition into the state. These are noted in the table.
Some call states are optional. A call only enters an optional state, and the event indicating the transition is generated only if the proper bit enabling or disabling the event is set in the NCC.START.eventmask parameter. For more information about this parameter, see Appendix D.
The application can use nccGetCallStatus to determine the state of a call.

State

Description

Accepting (optional)

Entered via NCCEVN_ACCEPTING_CALL event in response to invocation of nccAcceptCall.
The NCC_CAP_ACCEPT_CALL indicator in the capabilitymask returned by nccQueryCapability indicates if the protocol supports this state.

Answering

Entered via NCCEVN_ANSWERING_CALL event in response to invocation of nccAnswerCall.

Connected

Entered via an unsolicited NCCEVN_CALL_CONNECTED event after a call has been successfully answered by the remote party, or the NCCEVN_CALL_CONNECTED call control connectmask conditions have occurred on an outbound call (e.g. connect on Proceeding).

Disconnected

Entered from any state via an unsolicited NCCEVN_CALL_DISCONNECTED event.
Entered via a solicited NCCEVN_CALL_DISCONNECTED event, following the invocation of nccDisconnectCall. The NCC_CAP_DISCONNECT_IN_ ANY_STATE indicator in the capabilitymask returned by nccQueryCapability indicates in which call states the application can initiate a disconnect.

Incoming

Entered via NCCEVN_INCOMING_CALL event.

Outbound Initiated

Entered by attempting to place a call using nccPlaceCall. No event gets you here.

Placing

Entered via NCCEVN_PLACING_CALL event in response to invocation of nccPlaceCall.

Proceeding (optional)

An NCCEVN_CALL_PROCEEDING event indicates that the call has entered this state.

Receiving Digits (optional)

Entered via an unsolicited NCCEVN_RECEIVED_DIGIT event. Note that this event is generated only if the NCC.START.overlappedreceiving parameter is set (see Appendix D).

Rejecting

Entered via NCCEVN_REJECTING_CALL event in response to invocation of nccRejectCall, or as a result of not responding in time to an NCCEVN_INCOMING_CALL.

Seizure

Entered via an unsolicited NCCEVN_SEIZURE_DETECTED event.
Figure 5 shows the call states, and events indicating transitions between them: Figure 5. NCC Call State Diagram

State	Description
Accepting (optional)	Entered via NCCEVN_ACCEPTING_CALL event in response to invocation of nccAcceptCall. The NCC_CAP_ACCEPT_CALL indicator in the capabilitymask returned by nccQueryCapability indicates if the protocol supports this state.
Answering	Entered via NCCEVN_ANSWERING_CALL event in response to invocation of nccAnswerCall.
Connected	Entered via an unsolicited NCCEVN_CALL_CONNECTED event after a call has been successfully answered by the remote party, or the NCCEVN_CALL_CONNECTED call control connectmask conditions have occurred on an outbound call (e.g. connect on Proceeding).
Disconnected	Entered from any state via an unsolicited NCCEVN_CALL_DISCONNECTED event. Entered via a solicited NCCEVN_CALL_DISCONNECTED event, following the invocation of nccDisconnectCall. The NCC_CAP_DISCONNECT_IN_ ANY_STATE indicator in the capabilitymask returned by nccQueryCapability indicates in which call states the application can initiate a disconnect.
Incoming	Entered via NCCEVN_INCOMING_CALL event.
Outbound Initiated	Entered by attempting to place a call using nccPlaceCall. No event gets you here.
Placing	Entered via NCCEVN_PLACING_CALL event in response to invocation of nccPlaceCall.
Proceeding (optional)	An NCCEVN_CALL_PROCEEDING event indicates that the call has entered this state.
Receiving Digits (optional)	Entered via an unsolicited NCCEVN_RECEIVED_DIGIT event. Note that this event is generated only if the NCC.START.overlappedreceiving parameter is set (see Appendix D).
Rejecting	Entered via NCCEVN_REJECTING_CALL event in response to invocation of nccRejectCall, or as a result of not responding in time to an NCCEVN_INCOMING_CALL.
Seizure	Entered via an unsolicited NCCEVN_SEIZURE_DETECTED event.

2.6.3 Functions and States

The following table depicts which line- and call-related NCC service API calls can be made from each of the states of the line state machine. If the function is not supported by some protocols, the "Capability Mask" column contains the name of the bit in the capabilitymask (returned by nccQueryCapability - see Section 2.5) that indicates if the function is supported or not.

NCC API Function

Line State

Capability Mask

Active

Blocking

Idle

Out of Service

Uninitialized

nccAcceptCall

X

X 1

NCC_CAP_ACCEPT_CALL

nccAnswerCall

X

X 1

nccAutomaticTransfer

X

NCC_CAP_AUTOMATIC_TRANSFER

nccBlockCalls

X

X

X

nccDisconnectCall

X

X 1

nccGetCallStatus

X

X

nccGetExtendedCallStatus

X

X

NCC_CAP_EXTENDED_CALL_STATUS

nccGetLineStatus

X

X

X

X

X

nccHoldCall

X

NCC_CAP_HOLD_CALL

nccPlaceCall

X

X

nccQueryCapability

X

X

X

X

nccRejectCall

X

X 1

nccReleaseCall

X

X

X

X

nccRetrieveCall

X

X

NCC_CAP_HOLD_CALL

nccSendCallMessage

X

X 1

NCC_CAP_SEND_CALL_MESSAGE

nccSendDigits

X

X 1

NCC_CAP_OVERLAPPED_SENDING

nccSendLineMessage

X

X

X

X

NCC_CAP_SEND_LINE_MESSAGE

nccSetBilling

X

X 1

NCC_CAP_SET_BILLING

nccStartProtocol

X

nccStopProtocol

X

X

X

X

nccTransferCall

X

NCC_CAP_SUPERVISED_TRANSFER

nccUnBlockCalls

X

X

X

X

1 This operation can be performed in the Idle line state, on a call that is held, if supported by the service implementation and protocol. The NCC_CAP_HOLD_IN_ANY_STATE indicator in the capabilitymask returned by nccQueryCapability indicates if the protocol allows calls to be held/retrieved from any state.
The following table depicts which call-related NCC service API calls can be made from each of the states of the call state machine. If the function is not supported by some protocols, the "Capability Mask" column contains the name of the bit in the capabilitymask (returned by nccQueryCapability - see Section 2.5) that indicates if the function is supported or not.

NCC API Function

Call State

Capability Mask

Accepting

Answering

Conncected

Disconnected

Incoming

Outbound Initiated

Placing

Proceeding

Receiving Digits

Rejecting

Seizure

nccAcceptCall

X

X

NCC_CAP_ACCEPT_CALL

nccAnswerCall

X

X

X

nccAutomaticTransfer

X

NCC_CAP_AUTOMATIC_TRANSFER

nccDisconnectCall

X 1

X 1

X

X 1

X

X

X

X 1

X 1

X 1

nccGetCallStatus

X

X

X

X

X

X

X

X

X

X

X

nccGetExtendedCallStatus

X

X

X

X

X

X

X

X

X

X

X

NCC_CAP_EXTENDED_CALL_STATUS

nccHoldCall

X 2

X 2

X

X 2

X 2

X 2

X 2

X 2

X 2

X 2

X 2

NCC_CAP_HOLD_CALL

nccRejectCall

X

X

X

nccReleaseCall

X

nccRetrieveCall

X 2

X 2

X

X 2

X 2

X 2

X 2

X 2

X 2

X 2

NCC_CAP_HOLD_CALL

nccSendCallMessage

X

X

X

X

X

X

X

X

X

X

X

NCC_CAP_SEND_CALL_MESSAGE

nccSendDigits

X

NCC_CAP_OVERLAPPED_SENDING

nccSetBilling

X

X

X

X

X

X

X

NCC_CAP_SET_BILLING

nccTransferCall

X

NCC_CAP_SUPERVISED_TRANSFER

1 This function can be called in this state, if the NCC_CAP_DISCONNECT_IN_ANY_STATE indicator is set in the capabilitymask returned by nccQueryCapability.
2 This function can be called in this state, if supported by the service implementation and protocol. The NCC_CAP_HOLD_IN_ANY_STATE indicator in the capabilitymask returned by nccQueryCapability indicates if the protocol allows calls to be held/retrieved from any state.

NCC API Function	Line State	Capability Mask
	Active	Blocking	Idle	Out of Service	Uninitialized
nccAcceptCall	X		X 1			NCC_CAP_ACCEPT_CALL
nccAnswerCall	X		X 1
nccAutomaticTransfer	X					NCC_CAP_AUTOMATIC_TRANSFER
nccBlockCalls	X		X	X
nccDisconnectCall	X		X 1
nccGetCallStatus	X		X
nccGetExtendedCallStatus	X		X			NCC_CAP_EXTENDED_CALL_STATUS
nccGetLineStatus	X	X	X	X	X
nccHoldCall	X					NCC_CAP_HOLD_CALL
nccPlaceCall	X		X
nccQueryCapability	X	X	X	X
nccRejectCall	X		X 1
nccReleaseCall	X	X	X	X
nccRetrieveCall	X		X			NCC_CAP_HOLD_CALL
nccSendCallMessage	X		X 1			NCC_CAP_SEND_CALL_MESSAGE
nccSendDigits	X		X 1			NCC_CAP_OVERLAPPED_SENDING
nccSendLineMessage	X	X	X	X		NCC_CAP_SEND_LINE_MESSAGE
nccSetBilling	X		X 1			NCC_CAP_SET_BILLING
nccStartProtocol					X
nccStopProtocol	X	X	X	X
nccTransferCall	X					NCC_CAP_SUPERVISED_TRANSFER
nccUnBlockCalls	X	X	X	X

NCC API Function	Call State	Capability Mask
	Accepting	Answering	Conncected	Disconnected	Incoming	Outbound Initiated	Placing	Proceeding	Receiving Digits	Rejecting	Seizure
nccAcceptCall					X				X			NCC_CAP_ACCEPT_CALL
nccAnswerCall	X				X				X
nccAutomaticTransfer			X									NCC_CAP_AUTOMATIC_TRANSFER
nccDisconnectCall	X 1	X 1	X		X 1	X	X	X	X 1	X 1	X 1
nccGetCallStatus	X	X	X	X	X	X	X	X	X	X	X
nccGetExtendedCallStatus	X	X	X	X	X	X	X	X	X	X	X	NCC_CAP_EXTENDED_CALL_STATUS
nccHoldCall	X 2	X 2	X	X 2	X 2	X 2	X 2	X 2	X 2	X 2	X 2	NCC_CAP_HOLD_CALL
nccRejectCall	X				X				X
nccReleaseCall				X
nccRetrieveCall	X 2	X 2	X	X 2	X 2		X 2	X 2	X 2	X 2	X 2	NCC_CAP_HOLD_CALL
nccSendCallMessage	X	X	X	X	X	X	X	X	X	X	X	NCC_CAP_SEND_CALL_MESSAGE
nccSendDigits							X					NCC_CAP_OVERLAPPED_SENDING
nccSetBilling	X	X	X		X				X	X	X	NCC_CAP_SET_BILLING
nccTransferCall			X									NCC_CAP_SUPERVISED_TRANSFER

2.6.4 Events and States

The following table specifies standard NCC events that the application can expect to receive for a line, given that the line is in a particular line state. Note that other protocol-specific NCC events may be reported in most states. See protocol-specific documentation for details.
Some events are generated only if you enable them by setting a parameter. If the event is controlled by this parameter, the "Controlled by..." column in the table below contains the name of the parameter which controls the event. For more information about parameters, see Appendix D.
For the NCC service, when a line/call is in a given state, any unsolicited event that is valid to be received in that state can be received regardless of any pending API call. For example, assume an application calls nccAnswerCall for a call in the NCC_CALLSTATE_RECEIVING_DIGITS state. Any unsolicited events that can be received in the NCC_CALLSTATE_RECEIVING_DIGITS state are valid, even while nccAnswerCall is pending. You do not proceed into the NCCEVN_CALLSTATE_ANSWERING state until the NCCEVN_CALL_ANSWERED event has been received.
Refer to the following tables to determine which events your application may receive in a given line/call state.
Your application does not have to check for certain solicited events if the application has not invoked the corresponding API call. For instance, continuing the previous example, an NCCEVN_ACCEPTING_CALL event will not arrive because the function nccAcceptCall was not invoked. To determine if an event is solicited, unsolicited, or both, refer to the event details in Chapter 9.
Certain unsolicited events need not be expected if it is known that a particular capability is disabled on the NCC line. For instance, if overlapped receiving is turned off (i.e., NCC.START.overlappedreceiving parameter = 0), the application will not receive the NCCEVN_RECEIVED_DIGIT event for calls on that line. For a discussion of how parameters can be used to specify which events your application should be prepared to handle, see the NCC.START.eventmask and NCC.START.overlappedreceiving parameter descriptions in Appendix D.

NCC Event

Line State

Controlled by...

Active

Blocking

Idle

Out of Service

Uninitialized

NCCEVN_ACCEPTING_CALL

X

X 1

NCCEVN_ANSWERING_CALL

X

X 1

NCCEVN_BILLING_INDICATION

X

X 1

NCC_REPORT_BILLING bit in NCC.START.eventmask parameter

NCCEVN_BILLING_SET

X

X 1

NCCEVN_BLOCK_FAILED

X

NCCEVN_CALL_CONNECTED

X

X 1

NCCEVN_CALL_DISCONNECTED

X

X 1

NCCEVN_CALL_HELD

X

NCCEVN_CALL_PROCEEDING

X

X 1

NCCEVN_CALL_RELEASED

X

X

X

X

NCCEVN_CALL_RETRIEVED

X

NCCEVN_CALL_STATUS_UPDATE

X

X

NCC_REPORT_STATUSINFO bit in NCC.START.eventmask parameter

NCCEVN_CALLS_BLOCKED

X

NCCEVN_CALLS_UNBLOCKED

X

NCCEVN_CAPABILITY_UPDATE

X

X

NCCEVN_EXTENDED_CALL_STATUS_UPDATE

X

X

NCC_REPORT_STATUSINFO bit in NCC.START.eventmask parameter

NCCEVN_HOLD_REJECTED

X

NCCEVN_INCOMING_CALL

X

X 1

NCCEVN_LINE_IN_SERVICE

X

NCCEVN_LINE_OUT_OF_SERVICE

X

NCCEVN_PLACING_CALL

X

NCCEVN_PROTOCOL_ERROR

X

X

X

X

NCCEVN_PROTOCOL_EVENT

X

X

X

X

NCCEVN_RECEIVED_DIGIT

X

X 1

NCC.START.overlapped receiving parameter

NCCEVN_REJECTING_CALL

X

X 1

NCCEVN_REMOTE_ALERTING

X

X 1

NCC_REPORT_ALERTING bit in NCC.START.eventmask parameter

NCCEVN_REMOTE_ANSWERED

X

X 1

NCC_REPORT_ANSWERED bit in NCC.START.eventmask parameter

NCCEVN_RETRIEVE_REJECTED

X

NCCEVN_SEIZURE_DETECTED

X

X

NCCEVN_START_PROTOCOL_DONE

X

NCCEVN_STOP_PROTOCOL_DONE

X

X

X

X

NCCEVN_UNBLOCK_FAILED

X

1 This event may occur in this state if the NCC_CAP_HOLD_IN_ANY_STATE bit is set in the capabilitymask returned by nccQueryCapability.
The following table specifies standard NCC events that the application can expect to receive for a call, given that the call is in a particular call state. Note, that other protocol-specific NCC events may be reported in most states. See protocol-specific documentation for details.
Some events are generated only if you enable them by setting them in the NCC.START.eventmask parameter. Other events are not supported by some protocols. For more information, see the table above.

NCC Event

NCC Call State

Controlled by...

Accepting

Answering

Connected

Disconnected

Incoming

Outbound Initiated

Placing

Proceeding

Receiving Digits

Rejecting

Seizure

NCCEVN_ACCEPTING_CALL

X

X

NCCEVN_ANSWERING_CALL

X

X

X

NCCEVN_BILLING_INDICATION

X

X

X

X

NCC_REPORT_BILLING bit in NCC.START.eventmask

NCCEVN_BILLING_SET

X

NCCEVN_CALL_CONNECTED

X

X

X

NCCEVN_CALL_DISCONNECTED

X

X

X

X

X

X

X

X

X

X

NCCEVN_CALL_HELD

X 1

X 1

X

X 1

X 1

X 1

X 1

X 1

X 1

X 1

NCCEVN_CALL_PROCEEDING

X

NCCEVN_CALL_RELEASED

X

X

NCCEVN_CALL_RETRIEVED

X 1

X 1

X

X 1

X 1

X 1

X 1

X 1

X 1

X 1

NCCEVN_CALL_STATUS_UPDATE

X

X

X

X

X

X

X

X

X

X

X

NCC_REPORT_STATUSINFO bit in NCC.START.eventmask

NCCEVN_EXTENDED_CALL_STATUS_UPDATE

X

X

X

X

X

X

X

X

X

X

X

NCC_REPORT_STATUSINFO bit in NCC.START.eventmask

NCCEVN_HOLD_REJECTED

X 1

X 1

X

X 1

X 1

X 1

X 1

X 1

X 1

X 1

NCCEVN_INCOMING_CALL

X

X

NCCEVN_PLACING_CALL

X

NCCEVN_PROTOCOL_ERROR

X

X

X

X

X

X

X

X

X

X

X

NCCEVN_PROTOCOL_EVENT

X

X

X

X

X

X

X

X

X

X

X

NCCEVN_RECEIVED_DIGIT

X

X

NCC.START.overlappedreceiving

NCCEVN_REJECTING_CALL

X

X

X

NCCEVN_REMOTE_ALERTING

X

X

NCC_REPORT_ALERTING bit in NCC.START.eventmask

NCCEVN_REMOTE_ANSWERED

X

X

NCC_REPORT_ANSWERED bit in NCC.START.eventmask

NCCEVN_RETRIEVE_REJECTED*

X 1

X 1

X

X 1

X 1

X 1

X 1

X 1

X 1

X 1

1 This event may occur in this state if the NCC_CAP_HOLD_IN_ANY_STATE bit is set in the capabilitymask returned by nccQueryCapability.

(Page 1 of 1 in this chapter) Version

tech_support@nmss.com