# Call control functions and solicited events

The NCC API call control-related functions and their associated events are:

- nccAcceptCall

- nccAnswerCall

- nccAutomaticTransfer

- nccBlockCalls

- nccDisconnectCall

- nccGetCallStatus

- nccGetExtendedCallStatus

- nccGetLineStatus

- nccHoldCall

- nccPlaceCall

- nccRejectCall

- nccReleaseCall

- nccRetrieveCall

- nccSendCallMessage

- nccSendDigits

- nccSendLineMessage

- nccSetBilling

- nccStartProtocol

- nccStopProtocol

- nccTransferCall

- nccUnBlockCalls

For detailed documentation of the functions, parameters, and events, refer to the Dialogic® NaturalAccess™ NaturalCallControl™ API Developer’s Manual.

## nccAcceptCall

nccAcceptCall directs the TCP to accept an incoming call without answering it. The application can perform other operations before answering or rejecting the call. The application can accept a call using any of the following methods:

- NCC_ACCEPT_PLAY_RING: Play a ring tone.

- NCC_ACCEPT_QUIET: Accept call, but do not play tone or other audio.

- NCC_ACCEPT_USER_AUDIO: The application plays a recorded message. If remote party disconnects, the TCP interrupts the message.

Associated events | Description
NCCEVN_ACCEPTING_CALL | The TCP is accepting the call, using the specified method. The call state changes to accepting.
NCCEVN_CALL_DISCONNECTED | A DISCONNECT message was received from the network, indicating that the remote party has hung up. The event value field contains the reason. The call state changes to disconnected.
NCCEVN_REJECTING_CALL | The application failed to invoke nccAnswerCall, nccAcceptCall, or nccRejectCall within the period specified in the protocol's NCC.START.waitforpctime parameter. The call is automatically rejected and enters the rejecting call state. The event value field contains NCC_REJECT_HOST_TIMEOUT. A tone is played to the network. The NCC.X.ADI_ISDN.START.flags parameter controls which TCP messages are sent when nccAcceptCall is invoked. By default, a PROGRESS message is sent to the network.

## nccAnswerCall

Directs the TCP to answer a call after a specified number of rings.

Associated events | Description
NCCEVN_ANSWERING_CALL | The TCP is answering. The call enters the answering call state. An ALERT message is sent to the network. The TCP plays the number of rings specified in the nccAnswerCall call. A CONNECT message is sent to the network. By default, nccAnswerCall does not send a PROGRESS message.
NCCEVN_CALL_CONNECTED | The CONNECT message was acknowledged by the network and the connection is established. The call state changes to connected.
NCCEVN_CALL_DISCONNECTED | A DISCONNECT message was received from the network indicating that the remote party has hung up. The event value field contains the reason. The call state changes to disconnected.
NCCEVN_REJECTING_CALL | The application failed to invoke nccAnswerCall, nccAcceptCall, or nccRejectCall within the period specified in the protocol's NCC.START.waitforpctime parameter. The call is automatically rejected and enters the rejecting call state. The event value field contains NCC_REJECT_HOST_TIMEOUT. A tone is played to the network.

## 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 operates only when the first call handle is in the connected state, or is on hold.

Automatic call transfer is only supported in 4ESS variant. The application determines if a 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 the transfer address is dialed.

Associated events | Description
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 releases this call handle with nccReleaseCall.

Other protocol-specific errors or reasons for disconnecting may be reported.

## nccBlockCalls

Requests the TCP to block all incoming calls using one of these methods:

- NCC_BLOCK_REJECTALL: The TCP behaves as though the application has responded to each call with nccRejectCall. ISDN Software allows two protocol-specific reject modes when NCC_BLOCK_REJECTALL is used. The NCC.X.ADI_ISDN.START_EXT.blockrejectmode parameter determines the mode: 0=reject immediate, 1=reject playing busy tone.

- NCC_BLOCK_OUT_OF_SERVICE: A service request to block calls is sent to the remote end. If this request is confirmed, all subsequent incoming calls are rejected by the switch. This method is supported by the DMS, 4ESS, and E10 variants.

Blocking takes place as soon as there are no calls on the line (the line state is idle). The line state changes to blocking. The line remains in this state and all calls are blocked on the line until nccUnBlockCalls is called.

Note: The application should not call nccUnBlockCalls until it has received the NCCEVN_CALLS_BLOCKED event.

Associated events | Description
NCCEVN_CALLS_BLOCKED | The request was granted. The line enters blocking line state. The line remains in the blocked state until nccUnBlockCalls is called. NCCEVN_CALLS_BLOCKED can also be received as an unsolicited event. See Unsolicited events for more information.
NCCEVN_BLOCK_FAILED | The network failed to respond to the request. The line remains in its current state. The event value field contains a reason code, indicating the reason for the failure. The line remains unblocked.
NCCEVN_CALLS_UNBLOCKED | The switch rejected the request to put the line out of service. The line remains in its current state.

## nccDisconnectCall

Disconnects a call that is connected to the network. The function can also be used to abandon outbound call placement.

Associated events | Description
NCCEVN_CALL_DISCONNECTED | Generated after the protocol performs the network procedures for disconnecting the call from the network. The call state changes to disconnected.

## nccGetCallStatus

Retrieves the current status of the call (such as caller ID information, if available). For more information, see NCC_CALL_STATUS structure.

There are no associated events with this function.

## nccGetExtendedCallStatus

Retrieves protocol-specific status information for a call. For more information, see NCC_ISDN_EXT_CALL_STATUS structure.

There are no associated events with this function.

## nccGetLineStatus

Gets current status of line, in NCC_LINE_STATUS.

There are no associated events with this function.

## nccHoldCall

Places a call on hold.

## nccPlaceCall

Places a call to a specified address, using call placement parameters specified in NCC_ADI_PLACECALL_PARMS. The call enters the outbound initiated state.

Associated events | Description
NCCEVN_PLACING_CALL | Generated after the TCP seizes the trunk and an acknowledgment is received from the network. This implies that glare was resolved and call collision will not occur. The TCP is dialing the digits. The network is sent a SETUP message. The call is now in the placing call state. The event also indicates that a B channel was chosen for the call. This is useful when the TCP is running in non-exclusive mode (see B channel assignment overview). The stream and timeslot for this channel can be determined by calling nccGetCallStatus.
NCCEVN_CALL_PROCEEDING | The switch accepted the call setup. The call enters the proceeding state. The NCC.X.ADI_ISDN.START_EXT.startCP parameter determines if call progress analysis is enabled (default) or disabled.
NCCEVN_REMOTE_ALERTING | The network sent an ALERTING message indicating that the remote party is alerted of the call or that a ring tone was detected.
NCCEVN_REMOTE_ANSWERED | The network sent a CONNECT message indicating that the remote party answered.
NCCEVN_CALL_CONNECTED | The call satisfies the connectmask requirements set in the NCC_ADI_PLACECALL_PARMS structure. Usually, this is when a CONNECT message is received by the network; however, it could be due to other factors, depending on the connection criteria specified. The event value field indicates the reason. The call is now in the connected call state. The application can play and record voice files, and generate and detect DTMF tones.
NCCEVN_CALL_DISCONNECTED | The call entered the disconnected call state, because: A release event was received from the network. A busy, reorder, ring-no-answer, or Special Information Tone (SIT) was detected. The call fits the disconnection criteria specified in the disconnectmask parameter in the NCC_ADI_PLACECALL_PARMS structure. By default, this is when a DISCONNECT message is received by the network. The event value field contains the condition that fits the disconnection criteria. This is a race condition.
NCCEVN_INCOMING_CALL | A call is arriving on the B channel. Call placement is aborted. This message occurs when a SETUP is received. This is a race condition.
NCCEVN_PROTOCOL_EVENT | An ISDN PROGRESS message was received. The event value field contains 0x9F0E000. The application receives this event if the ISDN_REPORT_PROGRESS bit is set in the NCC.X.ADI_ISDN.START.EXT.ISDNeventmask parameter.

## nccRejectCall

Directs the TCP to reject an incoming call using one of the following methods:

- NCC_REJECT_PLAY_BUSY

- NCC_REJECT_PLAY_REORDER

- NCC_REJECT_USER_AUDIO

- NCC_REJECT_PLAY_RINGTONE

Associated events | Description
NCCEVN_REJECTING_CALL | The reject sequence started or the application failed to invoke nccAnswerCall, nccAcceptCall, or nccRejectCall within the period specified in the protocol's NCC.START.waitforpctime parameter. The event value field contains the reject method code, or NCC_REJECT_HOST_TIMEOUT if the host timed out.
NCCEVN_CALL_DISCONNECTED | The remote party hung up. Either a DISCONNECT or a RELEASE message was received from the network. This is a race condition. Optionally, you can invoke nccDisconnectCall to cause the TCP to actively clear a rejected call, by sending a DISCONNECT message to the network. No tone is played.

## nccReleaseCall

Directs the TCP to release a disconnected call (a call in the disconnected call state). To release a call, the application must first bring it to the disconnected state by invoking nccDisconnectCall.

Associated events | Description
NCCEVN_CALL_RELEASED | The call was released. A DISCONNECT message was sent to the network and a RELEASE was received.

## nccRetrieveCall

Retrieves a held call.

## nccSendCallMessage

Sends ISDN-specific messages to the TCP. For more information, see Sending and receiving ISDN-specific messages.

There are no associated events with this function.

## nccSendDigits

Continues the process of sending digits to place an outbound call (for protocols that support overlapped sending of digits). For more information, see Overlapped sending and receiving.

There are no associated events with this function.

## nccSendLineMessage

Not supported by ISDN Software.

## nccSetBilling

Not supported by ISDN Software.

## nccStartProtocol

Starts a TCP.

Associated events | Description
NCCEVN_STARTPROTOCOL_DONE | The function has finished. The event value field indicates if the TCP started successfully: CTA_REASON_FINISHED: Indicates successful completion. NCCREASON_OUT_OF_RESOURCES: The application must restart the TCP with the mediamask value in the NCC.ADI_START.CALLCTL structure set to 0.

## nccStopProtocol

Stops the protocol and uninitializes the line.

Associated events | Description
NCCEVN_STOPPROTOCOL_DONE | The TCP was halted. The value field is set to CTA_REASON_FINISHED. The line state successfully changed to uninitialized. The line can no longer be used to accept calls, place calls, or both.
NCCEVN_CALL_RELEASED | A call was released before the protocol was stopped.

## nccTransferCall

Completes supervised transfer of two calls. When the transfer is completed, the application should invoke nccReleaseCall for both call handles to release their resources.

Note: Supervised call transfer is not supported in all variants. The application can determine if the protocol supports this state by examining the NCC_CAP_SUPERVISED_TRANSFER bit in the capabilitymask returned by nccQueryCapability.

Associated events | Description
NCCEVN_CALL_DISCONNECTED | Should be returned 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.

## nccUnBlockCalls

Requests the TCP to stop blocking calls.

Associated events | Description
NCCEVN_CALLS_UNBLOCKED | The request to unblock the line is granted. The line state changes to idle.
NCCEVN_UNBLOCK_FAILED | The event value field contains the reason code indicating the reason for the failure. The line remains blocked.
NCCEVN_CALLS_BLOCKED | The switch rejected the request to put the line back into service. The line stays in the blocking state.

Note: The application should not call nccBlockCalls again until it has received the NCCEVN_CALLS_UNBLOCKED event.