Call control functions and solicited events

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

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:

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.

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:

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:

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.