# NCC API call control model

This topic introduces the NCC API call control model and defines key concepts.

## Lines and calls

The NCC API 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 (for example, not disconnected or held).

Programmatically, a line is referenced using a line handle. The line handle is equivalent to the 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.

## NCC API events

When performing call control functions, the NCC API processes events: both those that arrive from the network, and those that are generated in response to NCC API commands. The NCC API 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.

Network event type | Description
--- | ---
Transitional | Generated when the call or line state changes. These are generated because the NCC API needs the application to choose an action or acknowledge that an application command is proceeding.
Informational | These 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.

## Call control states

In the NCC API 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 (for example, 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 is notified by an event.

The NCC API 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 Retrieving call information.

### Line states

The following table lists the line states, and descriptions for each. For more information, refer to NCC API state machines.

Line state | Description
--- | ---
Uninitialized | Initial state of line. Signifies that a protocol has not been started.
Idle | 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 prepared to accept an incoming call or place an outbound call.
Active | There is at least one active call on this line.
Blocking | All inbound and outbound calls are blocked.
Out of service | The network has placed the line out of service.

If all calls on a line are held or are in a disconnected call state (for example, all calls are inactive), the line state changes to idle. If a call becomes active on the line (for example, a held call is retrieved or a new call comes in or is placed), the line state returns to active.

The following tables list the call states and descriptions for each. For more information, refer to NCC API state machines.

### Inbound call states

Call state | Description
--- | ---
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) | A set of one or more incoming digits is expected to qualify the incoming call.
Incoming | A call was delivered from the network to the NCC API.
Accepting (optional) | A call was 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 | The NCC API is in the process of answering the call and establishing a connection.
Rejecting | The NCC API is in the process of rejecting the inbound call.

### Outbound call states

Call state | Description
--- | ---
Outbound initiated | A call was initiated.
Placing | The line was seized and the network allowed the call to be placed by the NCC API. In other words, glare has been resolved. NCC initiates dialing.
Proceeding | The switch accepted the call setup request and is in the process of attempting to ring the receiving end. Call progress analysis begins.

### Connected/disconnected call states

Call state | Description
--- | ---
Connected | A connection exists between the calling parties. The application can use DSP resources if necessary.
Disconnected | A connection no longer exists. A disconnected call is no longer active.