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	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.

5.3 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.

5.3.1 Line States

The following table lists the line states. Associated with each state are one or more transitional events which indicate transitions into particular line states (the states are indicated 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 2 shows the line states, and events indicating transitions between them: Figure 2. 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.

5.3.2 Call States

The following table lists the call states, and describes how each is entered. Associated with each state are transitional events which indicate transitions into particular states (these are indicated in the table). Some states are optional. A call only enters an optional state, and the event indicating the transition is only generated if the proper bit enabling or disabling the event is set in the NCC.START.eventmask parameter.
For more information about this parameter, refer to the Natural Call Control Service Developer's Reference Manual.
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 an NCCEVN_PLACING_CALL event in response to invocation of nccPlaceCall.

Proceeding

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_REPORT_DIGITS bit is set in the NCC.START.eventmask parameter (for more information, refer to the Natural Call Control Service Developer's Reference Manual.)
For some protocols, a response to a call to nccAnswerCall, nccRejectCall or nccAcceptCall in this state is delayed. All the digits must be received before the call can actually be accepted, answered or rejected. The affected protcols are: FGD0, WNK0, WNK1, EUC0, AP20 and SS50.

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.
The following diagram shows the call states, and the events that indicate transitions between them: Figure 3. 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 an NCCEVN_PLACING_CALL event in response to invocation of nccPlaceCall.
Proceeding	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_REPORT_DIGITS bit is set in the NCC.START.eventmask parameter (for more information, refer to the Natural Call Control Service Developer's Reference Manual.) For some protocols, a response to a call to nccAnswerCall, nccRejectCall or nccAcceptCall in this state is delayed. All the digits must be received before the call can actually be accepted, answered or rejected. The affected protcols are: FGD0, WNK0, WNK1, EUC0, AP20 and SS50.
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.

5.4 Call Control Functions and Associated Events

This chapter summarizes NCC service call control functions and events supported by AG CAS TCPs. For more information about call control, refer to the Natural Call Control Service Developer's Reference Manual.
There are two types of CT Access events associated with call control operations: Solicited events that signify acknowledgments from the TCP of particular function calls. These events are summarized in Section 5.4.1. Unsolicited events that can occur at any time, regardless of the application's current activities. These events are summarized in Section 5.4.2.
The NCC.START.eventmask parameter dictates whether certain informational call control events are generated. For detailed information about this structure refer to the Natural Call Control Service Developer's Reference Manual.

5.4.1 Call Control Functions and Solicited Events

The following table lists NCC service call control functions and associated events. Functions are listed in alphabetical order. For more detailed documentation of the functions, parameters, and events refer to the Natural Call Control Service Developer's Reference Manual.

Function

Description/Associated Events

nccAcceptCall

Accepts an incoming call without answering or rejecting it. This allows the application to perform media functions (such as playing a voice file) before connecting (or rejecting) an inbound call.
Note: Not all protocols support this function and the Accepting state. The application can determine if the protocol supports this state by examining the NCC_CAP_ACCEPT_CALL bit in the capabilitymask returned by nccQueryCapability.
If the remote party disconnects while the application accepts the call, then the application receives NCCEVN_CALL_DISCONNECTED. In this case, no NCCEVN_ACCEPTING_CALL event is delivered to the application.
The application can accept a call using any of the following modes:
· NCC_ACCEPT_PLAY_SILENT: Don't play anything (digital trunks only).
· NCC_ACCEPT_PLAY_RING: Play a ring tone (works on all trunks).
· NCC_ACCEPT_USER_AUDIO: The application may generate a recorded message. If the remote party disconnects, the TCP interrupts the message (digital trunks only).
Note: NCC_ACCEPT_PLAY_RING and NCC_ACCEPT_USER_AUDIO are not supported by all protocols. The application can determine if the protocol supports this capability by examining the NCC_CAP_MEDIA_IN_SETUP bit in the capabilitymask returned by nccQueryCapability. NCC_ACCEPT_PLAY_SILENT is the default accept mode supported by all protocols.
Associated Events:
· NCCEVN_ACCEPTING_CALL: The function has completed successfully and the call has entered the Accepting call state.
· NCCEVN_CALL_DISCONNECTED: The remote party has disconnected. The call enters the Disconnected call state.

nccAnswerCall

Answers an incoming call. If nccAnswerCall completes successfully, the call enters the Answering call state. The application receives NCCEVN_ANSWERING_CALL. When the call is connected, the application receives NCCEVN_CALL_CONNECTED, and the call enters the Connected call state. If the remote party disconnects while the call is in the Answering call state, the application receives NCCEVN_CALL_DISCONNECTED.
Associated Events:
· NCCEVN_ANSWERING_CALL: The function has completed successfully and the call has entered the Answering call state.
· NCCEVN_CALL_CONNECTED: The call is connected. The call enters the Connected call state.
· NCCEVN_CALL_DISCONNECTED: The remote party has disconnected. The call enters the Disconnected call state.

nccAutomaticTransfer

Transfers a call on a PBX, Centrex, or Centrex-like, line. nccAutomaticTransfer executes a "blind" transfer by performing placement of a "second" call and completing call transfer. nccAutomaticTransfer will operate only when the first call handle is in the Connected state, or is on hold.
Note: Not all protocols support automatic call transfer. The application can determine if the protocol supports this state by examining the NCC_CAP_AUTOMATIC_TRANSFER bit in the capabilitymask returned by nccQueryCapability.
The application determines when the call is to be transferred by specifying:
· NCC_TRANSFER_PROCEEDING: After transfer address is dialed.
· NCC_TRANSFER_ALERTING: When a ring is detected.
· NCC_TRANSFER_CONNECTED: When called party answers.
Associated Events:
· NCCEVN_CALL_HELD: Indicates that the second call (to the transfer address) is in Placing call state.
· NCCEVN_CALL_RETRIEVED: Indicates that the transfer failed. The event value field contains a NCC_DIS_xxx reason code indicating why the transfer failed.
· NCCEVN_CALL_DISCONNECTED: first call is in Disconnected call state. Receipt of this event with reason code NCC_DIS_TRANSFER indicates successful completion of the automatic transfer. The application should now release this call handle with nccReleaseCall.
Note: Other protocol-specific errors or reasons for disconnecting may be reported.

nccBlockCalls

Blocks calls on a specified line handle. nccBlockCalls may be invoked from any line state, however, incoming calls will not be blocked until there are no calls on the line (i.e., the line has returned to Idle line state).
When using nccBlockCalls, specify the method to be used to block calls. Two methods are valid:
· NCC_BLOCK_REJECTALL: Do not answer subsequent calls.
· NCC_OUT_OF_SERVICE: Place the line out of service.
When the line state has changed to Blocking, the application receives NCCEVN_CALLS_BLOCKED. The value returned with this event contains the chosen blocking method. The line will remain in the blocking state until the function nccUnblockCalls is called.
The application may receive NCCEVN_INCOMING_CALL after invoking nccBlockCalls and before receiving NCCEVN_CALLS_BLOCKED. The application must handle the incoming call (accept it, answer it, etc.). The application will not receive the NCCEVN_CALLS_BLOCKED event until it releases all calls.
If the blocking request fails for some reason, the application receives NCCEVN_BLOCK_FAILED. The line remains in the current state.
The nccUnBlockCalls function can be used to cancel a blocking request initiated using nccBlockCalls. A blocking request can be canceled any time before NCCEVN_CALLS_BLOCKED is received.
Associated Event:
· NCCEVN_CALLS_BLOCKED: The block calls request completed successfully. The line state has changed to Blocking.
· NCCEVN_BLOCK_FAILED: The request to block calls failed. The event value field contains the reason.

nccDisconnectCall

Disconnects a call that is connected to the network. nccDisconnectCall may also be used to abandon outbound call placement.
The NCC_CAP_DISCONNECT_IN_ANY_STATE bit in the capabilitymask returned by nccQueryCapability determines in which states nccDisconnectCall may be invoked. If the bit is set, nccDisconnectCall may be invoked in any call state except Disconnected. If the bit is cleared, nccDisconnectCall may only be invoked in the Connected call state.
A disconnected call is no longer Active. If no Active calls exist on a line, the line state changes to Idle.
Associated Event:
· NCCEVN_CALL_DISCONNECTED: The disconnect operation has completed successfully and the call has entered the Disconnected call state.

nccGetCallStatus

Retrieves the call control status and stores it in an NCC_CALL_STATUS structure. Caller ID data is written to the NCC_CALL_STATUS structure. Applications that requires caller ID data can check the calling party's ID by invoking nccGetCallStatus once NCCEVN_INCOMING_CALL is received, or by waiting for NCCEVN_CALL_STATUS_UPDATE, with a value code of NCC_CALL_STATUS_CALLINGADDR.
For more information about the NCC_CALL_STATUS structure, refer to Section 5.5.1.
Associated Events: None.

nccGetExtendedCallStatus

Retrieves protocol-specific status information for a call and stores it in an NCC_CAS_EXT_CALL_STATUS structure. For more information about the NCC_CAS_EXT_CALL_STATUS structure, see Section 5.5.2.
Associated Events: None.

nccGetLineStatus

Retrieves a snapshot of the port status and stores it in an NCC_LINE_STATUS structure. For more information, see the Natural Call Control Service Developer's Reference Manual.
Associated Events: None.

nccHoldCall

Puts a connected call on hold. There is no call state transition, but a call on hold is no longer Active. Since there are no Active calls currently on the line, the line state changes to Idle. The call is on hold only after the application receives an NCCEVN_CALL_HELD event. The held field in the NCC_CALL_STATUS structure is set to a non-zero value.
Use nccRetrieveCall to take the call off hold.
Some protocols do not support the capability to put a call on hold. The application can determine if the protocol supports call hold/retrieve by examining the NCC_CAP_HOLD_CALL bit in the capabilitymask returned by nccQueryCapability.
Some protocols allow a call to be put on hold only from the Connected state. The application can determine whether or not a call can be put on hold from any state by examining the NCC_CAP_HOLD_IN_ANY_STATE bit in the capabilitymask returned by nccQueryCapability.
Associated Events:
· NCCEVN_CALL_HELD: The call hold attempt completed successfully and the call is now on hold. The line state is now Idle.
· NCCEVN_HOLD_REJECTED: The request to put a call on hold was rejected. The value field contains information as to why the request was rejected.

nccPlaceCall

Places an outbound call to a specified digit string according to call placement parameters specified in NCC_PLACECALL_PARMS.. NCCEVN_PLACING_CALL indicates that the call placement operation has completed successfully and the call has entered the Placing call state.
If the application receives NCCEVN_CALL_RELEASED (with an NCC_RELEASED_FALSE_SEIZURE reason code) instead of NCCEVN_PLACING_CALL, the line was seized for an incoming call before glare was resolved, and the TCP has released the outgoing call. The application should immediately abandon outbound call placement and handle the incoming call.
The address digits can be sent all at once with the function inviocation, or (with some protocols) digits can be sent in an overlapped fashion. For more information, refer to the Natural Call Control Service Developer's Reference Manual.
Associated Events:
· NCCEVN_PLACING_CALL: The TCP has seized an outbound trunk and resolved glare, and the call has entered the Placing call state.
· NCCEVN_CALL_RELEASED: An incoming call was detected while call placement was taking place. The TCP has released the outbound call. The event value field contains NCC_RELEASED_GLARE.
· NCCEVN_CALL_PROCEEDING: The switch has accepted the call setup. The receiving side is being rung. The call enters the Proceeding call state.
· NCCEVN_REMOTE_ALERTING: The remote end is in an alerting state (e.g., is ringing). This event is generated only if the NCC_REPORT_ALERTING bit is set in the NCC.START.eventmask parameter.
· NCCEVN_REMOTE_ANSWERED: Generated at the first positive indication that the remote party has answered; e.g.,
out-of-band signaling, voice, or modem tone. The event value field contains the indication type. This event is generated only if the NCC_REPORT_ANSWERED bit is set in the NCC.START.eventmask parameter.
· NCCEVN_CALL_CONNECTED: Both parties are now connected. The call enters the Connected call state.

nccQueryCapability

This function queries the capabilities of the protocol on a given line handle. The application can invoke this function to determine if the current protocol supports a given feature. nccQueryCapability returns an NCC_PROT_CAP structure containing capability information for the protocol. (For more information about specific protocol capabilities, see Chapters 6 - 18).
Associated Events: none.

nccRejectCall

Rejects an incoming call.
nccRejectCall causes the protocol to reject the incoming call using the method specified by method. Valid methods are:
· NCC_REJECT_PLAY_RINGTONE: Play ring tone (only option on analog trunks).
· NCC_REJECT_PLAY_BUSY: Plays a busy tone (digital trunks only).
· NCC_REJECT_PLAY_REORDER: Plays a reorder tone (digital trunks only).
· NCC_REJECT_USER_AUDIO: The application generates a recorded message, or a Special Information Tone. If the remote party hangs up, the TCP interrupts the application tone or voice file (digital trunks only).
When a call is being rejected, the application receives NCCEVN_REJECTING_CALL.
To use the default rejection behavior for the current protocol, set method to 0.
Note: If the remote party disconnects while the application is rejecting the call, the application receives NCCEVN_CALL_DISCONNECTED only. In this case, NCCEVN_REJECTING_CALL is not delivered.
Associated Events:
· NCCEVN_REJECTING_CALL: The reject call operation has completed successfully and the call has entered the Rejecting call state.
· NCCEVN_CALL_DISCONNECTED: The remote party disconnected.

nccReleaseCall

Releases resources associated with a call in the Disconnected state, and destroys a call handle. nccReleaseCall can only be called when a call is in the Disconnected state. When a call is released, it is completely destroyed. The application can no longer retrieve call status information.
Associated Event:
· NCCEVN_CALL_RELEASED: Generated after the protocol has performed the network procedures for releasing the call. All internal resources allocated to the call are released. After the application receives this event, no more DSP-related events are generated for this call handle.

nccRetrieveCall

Retrieves a call previously placed on hold with nccHoldCall. The call becomes Active again.The line state changes to Active.
Associated Events:
· NCCEVN_CALL_RETRIEVED: The call retrieve attempt completed successfully and the call is now no longer on hold.
· NCCEVN_RETRIEVE_REJECTED: The request to retrieve the call was rejected.

nccSendCallMessage

Pass through mechanism to send a protocol-specific call message directly to the TCP. For more information, see the Natural Call Control Service Developer's Reference Manual. Not used for CAS protocols.
Associated Events: None.

nccSendDigits

Continues the process of sending digits to place an outbound call (for protocols that support overlapped sending of digits). For more information, see the Natural Call Control Service Developer's Reference Manual.
Associated Events: None.

nccSendLineMessage

Pass through mechanism to send a protocol-specific line message. For more information, see the Natural Call Control Service Developer's Reference Manual. Not used for CAS protocols.
Associated Events: None.

nccStartProtocol

Prepares an uninitialized line to be used by a protocol to accept and/or place calls. When invoked, nccStartProtocol returns NCCEVN_START_PROTOCOL_DONE. This event acknowledges the protocol startup attempt. The event value field indicates whether the attempt was successful or not.
Associated Events:
· NCCEVN_START_PROTOCOL_DONE: Acknowledges the attempt by the application to start a protocol on a CT Access context (line handle). The event value field indicates if the protocol was started or not. The following reason codes may be returned:
· CTA_REASON_FINISHED indicates that the protocol has successfully been started on a CT Access context (line handle). The line state changes from Uninitialized to Idle.
· NCCREASON_OUT_OF_RESOURCES indicates that the protocol has not been started, because the mediamask parameter is not set correctly. The line remains in Uninitialized line state. (See your hardware documentation for details.)

nccStopProtocol

Uninitializes an NCC line. If this command succeeds, the line state becomes Uninitialized. Any calls that are on the line are released. An NCCEVN_CALL_RELEASED event is generated for each released call. Then a NCCEVN_STOP_PROTOCOL_DONE event is returned.
Associated Events:
· NCCEVN_START_PROTOCOL_DONE: The line state has successfully changed from Idle to Uninitialized. It can no longer be used to accept and/or place calls.
· NCCEVN_CALL_RELEASED: A call that was on the line was released before the protocol was stopped.

nccTransferCall
(analog trunks only)

Completes supervised transfer of two calls. Only one of the two call handles can be in the Connected state and not be on hold. Both calls must be on the same line (context) handle.
When the transfer is completed, the application should invoke nccReleaseCall for both call handles to release their resources.
Note: Not all protocols support supervised call transfer. The application can determine if the protocol supports this state by examining the NCC_CAP_SUPERVISED_TRANSFER bit in the capabilitymask returned by nccQueryCapability.
When the transfer is completed, call nccReleaseCall to go back to the Idle state.
Associated Events:
· NCCEVN_CALL_DISCONNECTED: Should be received twice, once for each call. Indicates that the call is disconnected (from the point of view of the application). If the call transfer is successful, the NCC_DIS_TRANSFER reason code is returned with this event. Other protocol-specific reason codes may be reported for failure to complete transfer. The CTA_EVENT structure containing this event also contains the first call handle (callhd1) of the nccTransferCall invocation.

nccUnBlockCalls

Used to release blocking of calls on the specified line (context) handle. When the line state has changed from Blocking to Idle, the application receives NCCEVN_CALLS_UNBLOCKED. It can then receive or place new calls.
nccUnblockCalls may be used to cancel a previous nccBlockCalls invocation before the protocol is able to start blocking calls on the specified line. In this case, the application receives no events.
If the call unblocking request fails for some reason, the application receives NCCEVN_UNBLOCK_FAILED. The line remains in the Blocking line state.
Associated Events:
· NCCEVN_CALLS_UNBLOCKED: The unblock calls request completed successfully. The line state has changed to Idle.
· NCCEVN_UNBLOCK_FAILED: The request to unblock calls failed. The event value field contains the reason.

Function	Description/Associated Events
nccAcceptCall	Accepts an incoming call without answering or rejecting it. This allows the application to perform media functions (such as playing a voice file) before connecting (or rejecting) an inbound call. Note: Not all protocols support this function and the Accepting state. The application can determine if the protocol supports this state by examining the NCC_CAP_ACCEPT_CALL bit in the capabilitymask returned by nccQueryCapability. If the remote party disconnects while the application accepts the call, then the application receives NCCEVN_CALL_DISCONNECTED. In this case, no NCCEVN_ACCEPTING_CALL event is delivered to the application. The application can accept a call using any of the following modes: · NCC_ACCEPT_PLAY_SILENT: Don't play anything (digital trunks only). · NCC_ACCEPT_PLAY_RING: Play a ring tone (works on all trunks). · NCC_ACCEPT_USER_AUDIO: The application may generate a recorded message. If the remote party disconnects, the TCP interrupts the message (digital trunks only). Note: NCC_ACCEPT_PLAY_RING and NCC_ACCEPT_USER_AUDIO are not supported by all protocols. The application can determine if the protocol supports this capability by examining the NCC_CAP_MEDIA_IN_SETUP bit in the capabilitymask returned by nccQueryCapability. NCC_ACCEPT_PLAY_SILENT is the default accept mode supported by all protocols. Associated Events: · NCCEVN_ACCEPTING_CALL: The function has completed successfully and the call has entered the Accepting call state. · NCCEVN_CALL_DISCONNECTED: The remote party has disconnected. The call enters the Disconnected call state.
nccAnswerCall	Answers an incoming call. If nccAnswerCall completes successfully, the call enters the Answering call state. The application receives NCCEVN_ANSWERING_CALL. When the call is connected, the application receives NCCEVN_CALL_CONNECTED, and the call enters the Connected call state. If the remote party disconnects while the call is in the Answering call state, the application receives NCCEVN_CALL_DISCONNECTED. Associated Events: · NCCEVN_ANSWERING_CALL: The function has completed successfully and the call has entered the Answering call state. · NCCEVN_CALL_CONNECTED: The call is connected. The call enters the Connected call state. · NCCEVN_CALL_DISCONNECTED: The remote party has disconnected. The call enters the Disconnected call state.
nccAutomaticTransfer	Transfers a call on a PBX, Centrex, or Centrex-like, line. nccAutomaticTransfer executes a "blind" transfer by performing placement of a "second" call and completing call transfer. nccAutomaticTransfer will operate only when the first call handle is in the Connected state, or is on hold. Note: Not all protocols support automatic call transfer. The application can determine if the protocol supports this state by examining the NCC_CAP_AUTOMATIC_TRANSFER bit in the capabilitymask returned by nccQueryCapability. The application determines when the call is to be transferred by specifying: · NCC_TRANSFER_PROCEEDING: After *transfer address* is dialed. · NCC_TRANSFER_ALERTING: When a ring is detected. · NCC_TRANSFER_CONNECTED: When called party answers. Associated Events: · NCCEVN_CALL_HELD: Indicates that the second call (to *the transfer address) is in Placing call state. · NCCEVN_CALL_RETRIEVED: Indicates that the transfer failed. The event value field contains a NCC_DIS_xxx reason code indicating why the transfer failed. · NCCEVN_CALL_DISCONNECTED: first call is in Disconnected call state. Receipt of this event with reason code NCC_DIS_TRANSFER indicates successful completion of the automatic transfer. The application should now release this call handle with nccReleaseCall*. Note: Other protocol-specific errors or reasons for disconnecting may be reported.
nccBlockCalls	Blocks calls on a specified line handle. nccBlockCalls may be invoked from any line state, however, incoming calls will not be blocked until there are no calls on the line (i.e., the line has returned to Idle line state). When using nccBlockCalls, specify the method to be used to block calls. Two methods are valid: · NCC_BLOCK_REJECTALL: Do not answer subsequent calls. · NCC_OUT_OF_SERVICE: Place the line out of service. When the line state has changed to Blocking, the application receives NCCEVN_CALLS_BLOCKED. The value returned with this event contains the chosen blocking method. The line will remain in the blocking state until the function nccUnblockCalls is called. The application may receive NCCEVN_INCOMING_CALL after invoking nccBlockCalls and before receiving NCCEVN_CALLS_BLOCKED. The application must handle the incoming call (accept it, answer it, etc.). The application will not receive the NCCEVN_CALLS_BLOCKED event until it releases all calls. If the blocking request fails for some reason, the application receives NCCEVN_BLOCK_FAILED. The line remains in the current state. The nccUnBlockCalls function can be used to cancel a blocking request initiated using nccBlockCalls. A blocking request can be canceled any time before NCCEVN_CALLS_BLOCKED is received. Associated Event: · NCCEVN_CALLS_BLOCKED: The block calls request completed successfully. The line state has changed to Blocking. · NCCEVN_BLOCK_FAILED: The request to block calls failed. The event value field contains the reason.
nccDisconnectCall	Disconnects a call that is connected to the network. nccDisconnectCall may also be used to abandon outbound call placement. The NCC_CAP_DISCONNECT_IN_ANY_STATE bit in the capabilitymask returned by nccQueryCapability determines in which states nccDisconnectCall may be invoked. If the bit is set, nccDisconnectCall may be invoked in any call state except Disconnected. If the bit is cleared, nccDisconnectCall may only be invoked in the Connected call state. A disconnected call is no longer Active. If no Active calls exist on a line, the line state changes to Idle. Associated Event: · NCCEVN_CALL_DISCONNECTED: The disconnect operation has completed successfully and the call has entered the Disconnected call state.
nccGetCallStatus	Retrieves the call control status and stores it in an NCC_CALL_STATUS structure. Caller ID data is written to the NCC_CALL_STATUS structure. Applications that requires caller ID data can check the calling party's ID by invoking nccGetCallStatus once NCCEVN_INCOMING_CALL is received, or by waiting for NCCEVN_CALL_STATUS_UPDATE, with a value code of NCC_CALL_STATUS_CALLINGADDR. For more information about the NCC_CALL_STATUS structure, refer to Section 5.5.1. Associated Events: None.
nccGetExtendedCallStatus	Retrieves protocol-specific status information for a call and stores it in an NCC_CAS_EXT_CALL_STATUS structure. For more information about the NCC_CAS_EXT_CALL_STATUS structure, see Section 5.5.2. Associated Events: None.
nccGetLineStatus	Retrieves a snapshot of the port status and stores it in an NCC_LINE_STATUS structure. For more information, see the Natural Call Control Service Developer's Reference Manual. Associated Events: None.
nccHoldCall	Puts a connected call on hold. There is no call state transition, but a call on hold is no longer Active. Since there are no Active calls currently on the line, the line state changes to Idle. The call is on hold only after the application receives an NCCEVN_CALL_HELD event. The held field in the NCC_CALL_STATUS structure is set to a non-zero value. Use nccRetrieveCall to take the call off hold. Some protocols do not support the capability to put a call on hold. The application can determine if the protocol supports call hold/retrieve by examining the NCC_CAP_HOLD_CALL bit in the capabilitymask returned by nccQueryCapability. Some protocols allow a call to be put on hold only from the Connected state. The application can determine whether or not a call can be put on hold from any state by examining the NCC_CAP_HOLD_IN_ANY_STATE bit in the capabilitymask returned by nccQueryCapability. Associated Events: · NCCEVN_CALL_HELD: The call hold attempt completed successfully and the call is now on hold. The line state is now Idle. · NCCEVN_HOLD_REJECTED: The request to put a call on hold was rejected. The value field contains information as to why the request was rejected.
nccPlaceCall	Places an outbound call to a specified digit string according to call placement parameters specified in NCC_PLACECALL_PARMS.. NCCEVN_PLACING_CALL indicates that the call placement operation has completed successfully and the call has entered the Placing call state. If the application receives NCCEVN_CALL_RELEASED (with an NCC_RELEASED_FALSE_SEIZURE reason code) instead of NCCEVN_PLACING_CALL, the line was seized for an incoming call before glare was resolved, and the TCP has released the outgoing call. The application should immediately abandon outbound call placement and handle the incoming call. The address digits can be sent all at once with the function inviocation, or (with some protocols) digits can be sent in an overlapped fashion. For more information, refer to the Natural Call Control Service Developer's Reference Manual. Associated Events: · NCCEVN_PLACING_CALL: The TCP has seized an outbound trunk and resolved glare, and the call has entered the Placing call state. · NCCEVN_CALL_RELEASED: An incoming call was detected while call placement was taking place. The TCP has released the outbound call. The event value field contains NCC_RELEASED_GLARE. · NCCEVN_CALL_PROCEEDING: The switch has accepted the call setup. The receiving side is being rung. The call enters the Proceeding call state. · NCCEVN_REMOTE_ALERTING: The remote end is in an alerting state (e.g., is ringing). This event is generated only if the NCC_REPORT_ALERTING bit is set in the NCC.START.eventmask parameter. · NCCEVN_REMOTE_ANSWERED: Generated at the first positive indication that the remote party has answered; e.g., out-of-band signaling, voice, or modem tone. The event value field contains the indication type. This event is generated only if the NCC_REPORT_ANSWERED bit is set in the NCC.START.eventmask parameter. · NCCEVN_CALL_CONNECTED: Both parties are now connected. The call enters the Connected call state.
nccQueryCapability	This function queries the capabilities of the protocol on a given line handle. The application can invoke this function to determine if the current protocol supports a given feature. nccQueryCapability returns an NCC_PROT_CAP structure containing capability information for the protocol. (For more information about specific protocol capabilities, see Chapters 6 - 18). Associated Events: none.
nccRejectCall	Rejects an incoming call. nccRejectCall causes the protocol to reject the incoming call using the method specified by method. Valid methods are: · NCC_REJECT_PLAY_RINGTONE: Play ring tone (only option on analog trunks). · NCC_REJECT_PLAY_BUSY: Plays a busy tone (digital trunks only). · NCC_REJECT_PLAY_REORDER: Plays a reorder tone (digital trunks only). · NCC_REJECT_USER_AUDIO: The application generates a recorded message, or a Special Information Tone. If the remote party hangs up, the TCP interrupts the application tone or voice file (digital trunks only). When a call is being rejected, the application receives NCCEVN_REJECTING_CALL. To use the default rejection behavior for the current protocol, set method to 0. Note: If the remote party disconnects while the application is rejecting the call, the application receives NCCEVN_CALL_DISCONNECTED only. In this case, NCCEVN_REJECTING_CALL is not delivered. Associated Events: · NCCEVN_REJECTING_CALL: The reject call operation has completed successfully and the call has entered the Rejecting call state. · NCCEVN_CALL_DISCONNECTED: The remote party disconnected.
nccReleaseCall	Releases resources associated with a call in the Disconnected state, and destroys a call handle. nccReleaseCall can only be called when a call is in the Disconnected state. When a call is released, it is completely destroyed. The application can no longer retrieve call status information. Associated Event: · NCCEVN_CALL_RELEASED: Generated after the protocol has performed the network procedures for releasing the call. All internal resources allocated to the call are released. After the application receives this event, no more DSP-related events are generated for this call handle.
nccRetrieveCall	Retrieves a call previously placed on hold with nccHoldCall. The call becomes Active again.The line state changes to Active. Associated Events: · NCCEVN_CALL_RETRIEVED: The call retrieve attempt completed successfully and the call is now no longer on hold. · NCCEVN_RETRIEVE_REJECTED: The request to retrieve the call was rejected.
nccSendCallMessage	Pass through mechanism to send a protocol-specific call message directly to the TCP. For more information, see the Natural Call Control Service Developer's Reference Manual. Not used for CAS protocols. Associated Events: None.
nccSendDigits	Continues the process of sending digits to place an outbound call (for protocols that support overlapped sending of digits). For more information, see the Natural Call Control Service Developer's Reference Manual. Associated Events: None.
nccSendLineMessage	Pass through mechanism to send a protocol-specific line message. For more information, see the Natural Call Control Service Developer's Reference Manual. Not used for CAS protocols. Associated Events: None.
nccStartProtocol	Prepares an uninitialized line to be used by a protocol to accept and/or place calls. When invoked, nccStartProtocol returns NCCEVN_START_PROTOCOL_DONE. This event acknowledges the protocol startup attempt. The event value field indicates whether the attempt was successful or not. Associated Events: · NCCEVN_START_PROTOCOL_DONE: Acknowledges the attempt by the application to start a protocol on a CT Access context (line handle). The event value field indicates if the protocol was started or not. The following reason codes may be returned: · CTA_REASON_FINISHED indicates that the protocol has successfully been started on a CT Access context (line handle). The line state changes from Uninitialized to Idle. · NCCREASON_OUT_OF_RESOURCES indicates that the protocol has not been started, because the mediamask parameter is not set correctly. The line remains in Uninitialized line state. (See your hardware documentation for details.)
nccStopProtocol	Uninitializes an NCC line. If this command succeeds, the line state becomes Uninitialized. Any calls that are on the line are released. An NCCEVN_CALL_RELEASED event is generated for each released call. Then a NCCEVN_STOP_PROTOCOL_DONE event is returned. Associated Events: · NCCEVN_START_PROTOCOL_DONE: The line state has successfully changed from Idle to Uninitialized. It can no longer be used to accept and/or place calls. · NCCEVN_CALL_RELEASED: A call that was on the line was released before the protocol was stopped.
nccTransferCall (analog trunks only)	Completes supervised transfer of two calls. Only one of the two call handles can be in the Connected state and not be on hold. Both calls must be on the same line (context) handle. When the transfer is completed, the application should invoke nccReleaseCall for both call handles to release their resources. Note: Not all protocols support supervised call transfer. The application can determine if the protocol supports this state by examining the NCC_CAP_SUPERVISED_TRANSFER bit in the capabilitymask returned by nccQueryCapability. When the transfer is completed, call nccReleaseCall to go back to the Idle state. Associated Events: · NCCEVN_CALL_DISCONNECTED: Should be received twice, once for each call. Indicates that the call is disconnected (from the point of view of the application). If the call transfer is successful, the NCC_DIS_TRANSFER reason code is returned with this event. Other protocol-specific reason codes may be reported for failure to complete transfer. The CTA_EVENT structure containing this event also contains the first call handle (*callhd1) of the nccTransferCall* invocation.
nccUnBlockCalls	Used to release blocking of calls on the specified line (context) handle. When the line state has changed from Blocking to Idle, the application receives NCCEVN_CALLS_UNBLOCKED. It can then receive or place new calls. nccUnblockCalls may be used to cancel a previous nccBlockCalls invocation before the protocol is able to start blocking calls on the specified line. In this case, the application receives no events. If the call unblocking request fails for some reason, the application receives NCCEVN_UNBLOCK_FAILED. The line remains in the Blocking line state. Associated Events: · NCCEVN_CALLS_UNBLOCKED: The unblock calls request completed successfully. The line state has changed to Idle. · NCCEVN_UNBLOCK_FAILED: The request to unblock calls failed. The event value field contains the reason.

5.4.2 Unsolicited Events

The following table lists call control-related unsolicited events:

Event

Description

NCCEVN_BILLING_INDICATION

Indicates that a billing indication was detected for an outbound call. This can be a billing pulse or some more complex indication. The event value field may contain the billing units charged, depending upon the protocol implementation.
This event is generated only if the NCC_REPORT_BILLING bit is set in the NCC.START.eventmask parameter.

NCCEVN_CALL_CONNECTED

Indicates that a call has reached the Connected call state. The event value field contains the reason for connection.

NCCEVN_CALL_DISCONNECTED

This event indicates one of the following:
· The application has invoked nccDisconnectCall.
· The remote party has hung up. This event can occur in almost any call state.
· The call is inbound, and the application has rejected the call.
· The call is outbound, the remote party has answered, and the call has failed to meet the criteria specified by the NCC_PLACECALL_PARMS connectmask passed with nccPlaceCall, or has met the criteria specified by the disconnectmask.
The event value field contains the reason that the call was disconnected.
A disconnected call is no longer considered Active. If there are no active calls on a line (i.e., any calls on the line are either held or disconnected) the line state returns to Idle.
Disconnected calls should be released using nccReleaseCall.

NCCEVN_CALL_HELD

Indicates that a call has been placed on hold, either by the application or by a remote party. When a call is placed on hold, no call state change occurs. However, a call on hold is not considered Active. If there are no active calls on a line (i.e., any calls on the line are either held or disconnected) the line state returns to Idle.
Call holding is not supported by all protocols. The NCC_CAP_HOLD_CALL indicator in the capabilitymask returned by nccQueryCapability indicates if the current protocol supports this event or not.
Ordinarily, a call can only be placed on hold in the Connected call state. However, if the NCC_CAP_HOLD_IN_ANY_STATE indicator is set in the capabilitymask for the protocol, the application can place a call on hold regardless of the call state.
The application can call nccGetCallStatus to determine whether a call is on hold or not. If a call is on hold, the held attribute in the NCC_CALL_STATUS structure returned for that call contains a non-zero value.

NCCEVN_CALL_PROCEEDING

This event indicates 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. The call state changes to Proceeding.

NCCEVN_CALL_RETRIEVED

Indicates that a call on hold has been retrieved, either by the application or by a remote party. The call is now Active. Since there is an Active call on the line, the line state changes to Active.
Call hold/retrieve is not supported by all protocols. NCC_CAP_HOLD_CALL in the capabilitymask returned by nccQueryCapability indicates if the current protocol supports this capability or not.
The application can call nccGetCallStatus to determine whether a call is on hold or not. If a call is on hold, the held attribute in the NCC_CALL_STATUS structure returned for that call contains a non-zero value.
If an automatic transfer fails, NCCEVN_CALL_RETRIEVED is returned, with a value field containing one of the NCC_DIS_xxx reason codes indicating why the transfer failed.

NCCEVN_CALL_STATUS_UPDATE

If call status information changes, the application receives this event. The event value field indicates the type of information that was changed. The application can then invoke nccGetCallStatus to get the updated information.
This event can occur in any call state, as long as the line state is Active. It is generated only if the NCC_REPORT_STATUSINFO bit is set in the NCC.START.eventmask parameter.

NCCEVN_CAPABILITY_UPDATE

The application receives this event when the capabilities of a protocol change. The event value field indicates the capability that changed. The application can call nccQueryCapability to determine the current set of protocol capabilities..

NCCEVN_EXTENDED_CALL_STATUS_UPDATE

The application receives this event when protocol specific call status information changes. The event value field indicates the kind of information that was changed. The application can then call nccGetExtendedCallStatus to retrieve this information.
This event is generated only if the NCC_REPORT_STATUSINFO bit is set in the NCC.START.eventmask parameter.

NCCEVN_INCOMING_CALL

This event indicates that an incoming call has been detected by NCC, and all necessary call information (digits, etc.) has been gathered. The call is now in the Incoming call state. At this point, the application decides whether to accept, answer, or reject the call.

NCCEVN_LINE_IN_SERVICE

This event indicates that an out-of-service line (a line in Out Of Service line state) has been placed in service. It is now in Idle line state.

NCCEVN_LINE_OUT_OF_SERVICE

This event indicates that a line was taken out of service. The event value field indicates the reason for taking the line out of service.

NCCEVN_PROTOCOL_ERROR

An error condition has occurred. The call may be in an unusable state.

NCCEVN_PROTOCOL_EVENT

The protocol implementation generated an unsolicited event.

NCCEVN_RECEIVED_DIGIT

This event indicates that a call address or subaddress digit has been received from the network. The application may receive several of these events, as digits are received in an overlapped fashion for an incoming call. The value field contains the digit.
When the first digit is received, the call state changes from Seizure to Receiving Digits. The call remains in this state until NCCEVN_INCOMING_CALL is received.
This event is generated only if the NCC_REPORT_DIGITS bit is set in the NCC.START.eventmask parameter.

NCCEVN_REJECTING_CALL

Either of the following has occurred:
· The application has invoked nccRejectCall to reject an incoming call.
· The application has failed to accept, answer, or reject an incoming call within the period of time specified by the NCC.START.waitforPCtime parameter.
The call enters the Rejecting call state. The event value field contains the reason why the call was rejected.

NCCEVN_SEIZURE_DETECTED

Indicates that NCC has detected an incoming call. A call handle is created for the call. The call handle may now be used for all subsequent operations for this call. The new call begins in the Seizure call state.

Event	Description
NCCEVN_BILLING_INDICATION	Indicates that a billing indication was detected for an outbound call. This can be a billing pulse or some more complex indication. The event value field may contain the billing units charged, depending upon the protocol implementation. This event is generated only if the NCC_REPORT_BILLING bit is set in the NCC.START.eventmask parameter.
NCCEVN_CALL_CONNECTED	Indicates that a call has reached the Connected call state. The event value field contains the reason for connection.
NCCEVN_CALL_DISCONNECTED	This event indicates one of the following: · The application has invoked nccDisconnectCall. · The remote party has hung up. This event can occur in almost any call state. · The call is inbound, and the application has rejected the call. · The call is outbound, the remote party has answered, and the call has failed to meet the criteria specified by the NCC_PLACECALL_PARMS connectmask passed with nccPlaceCall, or has met the criteria specified by the disconnectmask. The event value field contains the reason that the call was disconnected. A disconnected call is no longer considered Active. If there are no active calls on a line (i.e., any calls on the line are either held or disconnected) the line state returns to Idle. Disconnected calls should be released using nccReleaseCall.
NCCEVN_CALL_HELD	Indicates that a call has been placed on hold, either by the application or by a remote party. When a call is placed on hold, no call state change occurs. However, a call on hold is not considered Active. If there are no active calls on a line (i.e., any calls on the line are either held or disconnected) the line state returns to Idle. Call holding is not supported by all protocols. The NCC_CAP_HOLD_CALL indicator in the capabilitymask returned by nccQueryCapability indicates if the current protocol supports this event or not. Ordinarily, a call can only be placed on hold in the Connected call state. However, if the NCC_CAP_HOLD_IN_ANY_STATE indicator is set in the capabilitymask for the protocol, the application can place a call on hold regardless of the call state. The application can call nccGetCallStatus to determine whether a call is on hold or not. If a call is on hold, the held attribute in the NCC_CALL_STATUS structure returned for that call contains a non-zero value.
NCCEVN_CALL_PROCEEDING	This event indicates 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. The call state changes to Proceeding.
NCCEVN_CALL_RETRIEVED	Indicates that a call on hold has been retrieved, either by the application or by a remote party. The call is now Active. Since there is an Active call on the line, the line state changes to Active. Call hold/retrieve is not supported by all protocols. NCC_CAP_HOLD_CALL in the capabilitymask returned by nccQueryCapability indicates if the current protocol supports this capability or not. The application can call nccGetCallStatus to determine whether a call is on hold or not. If a call is on hold, the held attribute in the NCC_CALL_STATUS structure returned for that call contains a non-zero value. If an automatic transfer fails, NCCEVN_CALL_RETRIEVED is returned, with a value field containing one of the NCC_DIS_xxx reason codes indicating why the transfer failed.
NCCEVN_CALL_STATUS_UPDATE	If call status information changes, the application receives this event. The event value field indicates the type of information that was changed. The application can then invoke nccGetCallStatus to get the updated information. This event can occur in any call state, as long as the line state is Active. It is generated only if the NCC_REPORT_STATUSINFO bit is set in the NCC.START.eventmask parameter.
NCCEVN_CAPABILITY_UPDATE	The application receives this event when the capabilities of a protocol change. The event value field indicates the capability that changed. The application can call nccQueryCapability to determine the current set of protocol capabilities..
NCCEVN_EXTENDED_CALL_STATUS_UPDATE	The application receives this event when protocol specific call status information changes. The event value field indicates the kind of information that was changed. The application can then call nccGetExtendedCallStatus to retrieve this information. This event is generated only if the NCC_REPORT_STATUSINFO bit is set in the NCC.START.eventmask parameter.
NCCEVN_INCOMING_CALL	This event indicates that an incoming call has been detected by NCC, and all necessary call information (digits, etc.) has been gathered. The call is now in the Incoming call state. At this point, the application decides whether to accept, answer, or reject the call.
NCCEVN_LINE_IN_SERVICE	This event indicates that an out-of-service line (a line in Out Of Service line state) has been placed in service. It is now in Idle line state.
NCCEVN_LINE_OUT_OF_SERVICE	This event indicates that a line was taken out of service. The event value field indicates the reason for taking the line out of service.
NCCEVN_PROTOCOL_ERROR	An error condition has occurred. The call may be in an unusable state.
NCCEVN_PROTOCOL_EVENT	The protocol implementation generated an unsolicited event.
NCCEVN_RECEIVED_DIGIT	This event indicates that a call address or subaddress digit has been received from the network. The application may receive several of these events, as digits are received in an overlapped fashion for an incoming call. The value field contains the digit. When the first digit is received, the call state changes from Seizure to Receiving Digits. The call remains in this state until NCCEVN_INCOMING_CALL is received. This event is generated only if the NCC_REPORT_DIGITS bit is set in the NCC.START.eventmask parameter.
NCCEVN_REJECTING_CALL	Either of the following has occurred: · The application has invoked nccRejectCall to reject an incoming call. · The application has failed to accept, answer, or reject an incoming call within the period of time specified by the NCC.START.waitforPCtime parameter. The call enters the Rejecting call state. The event value field contains the reason why the call was rejected.
NCCEVN_SEIZURE_DETECTED	Indicates that NCC has detected an incoming call. A call handle is created for the call. The call handle may now be used for all subsequent operations for this call. The new call begins in the Seizure call state.

5.5 Retrieving Call Information

To get status information on a call, the application can:

Call nccGetCallStatus. This function returns an NCC_CALL_STATUS structure containing basic information about the call, such as the DID and ANI information, whether the call is on hold or not, etc.

Call nccGetExtendedCallStatus. This function returns an NCC_CAS_EXT_CALL_STATUS structure containing other information about the call. For AG CAS, this information may include the user and toll category, billing rate, etc. The types of information received with this function differ from protocol to protocol.
Either of these synchronous functions can be invoked in any call state, as long as the line is in Active line state.

Unsolicited Events

An application may also receive the unsolicited events NCCEVN_CALL_STATUS_UPDATE or NCCEVN_EXTENDED_CALL_STATUS_UPDATE while a particular call is still in progress. These events indicate a change in the status for the specified call. The application can examine the value field of the event for information about the type of status change that has occurred for the specific call. Then the application can invoke nccGetCallStatus or nccGetExtendedCallStatus to retrieve structures (NCC_CALL_STATUS or NCC_CAS_EXT_CALL_STATUS) that provide specific information about the call's status.

5.5.1 The NCC_CALL_STATUS Structure

The function nccGetCallStatus (a protocol independent NCC function) returns an NCC_CALL_STATUS structure. The structure looks like this:

typedef struct { DWORD size ;
DWORD state;
char calledaddr [NCC_MAX_DIGITS+1];
char callingaddr[NCC_MAX_DIGITS+1]; char callingname[NCC_MAX_CALLINGNAME];
DWORD pendingcmd;
DWORD held;
DWORD direction;
CTAHD linehd;
} NCC_CALL_STATUS;
The NCC_CALL_STATUS structure contains the following fields: Field Description size Number of bytes written at the address pointed to by status. state Current call state. Valid states are: NCC_CALLSTATE_SEIZURE NCC_CALLSTATE_RECEIVING_DIGITS NCC_CALLSTATE_INCOMING NCC_CALLSTATE_ACCEPTING NCC_CALLSTATE_ANSWERING NCC_CALLSTATE_REJECTING NCC_CALLSTATE_CONNECTED NCC_CALLSTATE_DISCONNECTED NCC_CALLSTATE_OUTBOUND_INITIATED NCC_CALLSTATE_PLACING NCC_CALLSTATE_PROCEEDING calledaddr For inbound calls, the address of the requested number if provided (e.g., DID). callingaddr For inbound calls, the address of the caller, if provided (e.g., caller ID, ANI). pendingcmd The last call control command issued that has not yet been acknowledged by the AG board. This field is set when a call control command is sent to the board, and cleared on the next event that corresponding to the acknowledgment of the pending command. Possible values are: (0) No command pending. NCC_PENDINGCMD_ACCEPT_CALL NCC_PENDINGCMD_ANSWER_CALL NCC_PENDINGCMD_AUTOMATIC_TRANSFER NCC_PENDINGCMD_DISCONNECT_CALL NCC_PENDINGCMD_HOLD_CALL NCC_PENDINGCMD_PLACE_CALL NCC_PENDINGCMD_REJECT_CALL NCC_PENDINGCMD_RELEASED_CALL NCC_PENDINGCMD_RETRIEVE_CALL NCC_PENDINGCMD_TRANSFER_CALL held Set to non-zero value when a call is held. linehd Line (context) handle on which the call resides. Note: Most of these fields are not guaranteed to be filled during call setup. The values of these fields depend on the information associated with the incoming call, and on the protocol used to set up the call.

Field	Description
size	Number of bytes written at the address pointed to by status.
state	Current call state. Valid states are: NCC_CALLSTATE_SEIZURE NCC_CALLSTATE_RECEIVING_DIGITS NCC_CALLSTATE_INCOMING NCC_CALLSTATE_ACCEPTING NCC_CALLSTATE_ANSWERING NCC_CALLSTATE_REJECTING NCC_CALLSTATE_CONNECTED NCC_CALLSTATE_DISCONNECTED NCC_CALLSTATE_OUTBOUND_INITIATED NCC_CALLSTATE_PLACING NCC_CALLSTATE_PROCEEDING
calledaddr	For inbound calls, the address of the requested number if provided (e.g., DID).
callingaddr	For inbound calls, the address of the caller, if provided (e.g., caller ID, ANI).
pendingcmd	The last call control command issued that has not yet been acknowledged by the AG board. This field is set when a call control command is sent to the board, and cleared on the next event that corresponding to the acknowledgment of the pending command. Possible values are: (0) No command pending. NCC_PENDINGCMD_ACCEPT_CALL NCC_PENDINGCMD_ANSWER_CALL NCC_PENDINGCMD_AUTOMATIC_TRANSFER NCC_PENDINGCMD_DISCONNECT_CALL NCC_PENDINGCMD_HOLD_CALL NCC_PENDINGCMD_PLACE_CALL NCC_PENDINGCMD_REJECT_CALL NCC_PENDINGCMD_RELEASED_CALL NCC_PENDINGCMD_RETRIEVE_CALL NCC_PENDINGCMD_TRANSFER_CALL
held	Set to non-zero value when a call is held.
linehd	Line (context) handle on which the call resides.

5.5.2 The NCC_CAS_EXT_CALL_STATUS Structure

The function nccGetExtendedCallStatus returns the following
NCC_CAS_EXTENDED_CALL_STATUS structure:

typedef struct { DWORD size; char ANIpresentation; /* Contains redirecting address information */
WORD usercategory; /* Contains the user category */
WORD tollcategory; /* Contains the toll category */
char carrierid [33]; /* Contains the carrier ID information */
WORD billingrate; /* Information passed with BILLING_SET event */
} NCC_CAS_EXT_CALL_STATUS;
The NCC_CAS_EXT_CALL_STATUS structure contains the following fields: Field Protocols That use the Field Description ANIpresentation MFC EAM This parameter is set if ANI presentation is restricted (i.e., caller ID information is restricted). redirectingaddr EUC (Sweden) Redirecting number information (if the call has been redirected from another terminal). usercategory MFC, LPS (with caller ID), EAM, R15 The information in this parameter represents either the type of the calling party (e.g., normal subscriber, operator, pay phone, etc.), or the type of call (protocol-specific). tollcategory MFC, EAM Generally the same as usercategory, if supported; it might be different for certain countries using the MFC-R2 protocol. carrierid FGD Carrier ID information. billingrate MFC, EAM Indication if the current call is billed or free (for CAS protocols, the actual cost of an outbound call is calculated by counting billing pulses, if the network offers this service). Note: Only a subset of fields will be filled depending on the protocol used.

Field	Protocols That use the Field	Description
ANIpresentation	MFC EAM	This parameter is set if ANI presentation is restricted (i.e., caller ID information is restricted).
redirectingaddr	EUC (Sweden)	Redirecting number information (if the call has been redirected from another terminal).
usercategory	MFC, LPS (with caller ID), EAM, R15	The information in this parameter represents either the type of the calling party (e.g., normal subscriber, operator, pay phone, etc.), or the type of call (protocol-specific).
tollcategory	MFC, EAM	Generally the same as usercategory, if supported; it might be different for certain countries using the MFC-R2 protocol.
carrierid	FGD	Carrier ID information.
billingrate	MFC, EAM	Indication if the current call is billed or free (for CAS protocols, the actual cost of an outbound call is calculated by counting billing pulses, if the network offers this service).

5.6 Specifying Extended Information with nccPlaceCall

With certain AG CAS protocols, when an application attempts to place a call with nccPlaceCall, extended information can be sent with the call placement request. This information is included in the NCC_ADI_CAS_PLACECALL structure shown below:

typedef struct { DWORD size; unsigned char ANIpresentation[1]; unsigned char pad[1]; WORD satellitecircuit; char redirectingaddr[33]; char carrierid[33]; char pad2[2]; INT16 usercategory; INT16 tollcategory; } NCC_ADI_CAS_PLACECALL_PARMS;
In the function call, this structure is referenced using the void *protcallparms argument.
The NCC_ADI_CAS_PLACECALL_PARMS structure contains the following fields: Field Protocols That use the Field Description ANIpresentation MFC EAM Set this parameter if ANI presentation is restricted (i.e., caller ID information is restricted). satellitecircuit MFC Set this parameter if there is a satellite link in the circuit. redirectingaddr EUC (Sweden) Redirecting number information (if the call has been redirected from another terminal). carrierid FGD Carrier ID information. usercategory MFC, LPS (with caller ID), EAM, R15 The type of the calling party (e.g., normal subscriber, operator, pay phone, etc.), or the type of call (protocol-specific). tollcategory MFC, EAM Generally the same as usercategory, if supported; it might be different for certain countries using the MFC-R2 protocol.

Field	Protocols That use the Field	Description
ANIpresentation	MFC EAM	Set this parameter if ANI presentation is restricted (i.e., caller ID information is restricted).
satellitecircuit	MFC	Set this parameter if there is a satellite link in the circuit.
redirectingaddr	EUC (Sweden)	Redirecting number information (if the call has been redirected from another terminal).
carrierid	FGD	Carrier ID information.
usercategory	MFC, LPS (with caller ID), EAM, R15	The type of the calling party (e.g., normal subscriber, operator, pay phone, etc.), or the type of call (protocol-specific).
tollcategory	MFC, EAM	Generally the same as usercategory, if supported; it might be different for certain countries using the MFC-R2 protocol.

(Page 1 of 1 in this chapter) Version

tech_support@nmss.com