NCC API functions and SIP for NCC API

The NaturalCallControl (NCC) for SIP API implementation follows the NCC API call control model as described in the Dialogic® NaturalAccess™ NaturalCallControl™ API Developer’s Manual. This topic describes the NCC API from a SIP perspective.

The following table describes the NCC API functions that are supported in the SIP for NCC API  and the associated SIP request or response messages. Functions that are specific to SIP for NCC API are also indicated.

NCC function

SIP request or response

nccAcceptCall

180 RINGING.

Sends a provisional 180 Ringing response to an incoming INVITE request. For more information, refer to Accepting a call.

nccAcknowledgeCall

ACK.

Sends ACK in the session establishment sequence INVITE/200 OK/ACK. This function is available only if the SIP stack is configured to operate in a manual acknowledgment mode. This function is SIP specific. The default mode of the stack is to send ACK automatically. For more information, refer to Acknowledging a call and to general.manualACK in Configuration parameters.

nccAnswerCall

200 OK.

Sends a final 200 OK response to an incoming INVITE request. For more information, refer to Answering a call.

nccAutomaticTransfer

REFER.

Instructs the party to whom you are connected to transfer the call, and causes a REFER to be sent to the remote party.

nccDisconnectCall

BYE.

Sends a BYE response to terminate a session.

If this function is called after nccPlaceCall, a CANCEL request is sent to the remote user in an attempt to cancel the establishment of a session. For more information, refer to Disconnecting a call.

nccGetCallStatus

No SIP response or request.

This function retrieves the status of a specified call. For more information, refer to Getting call status information.

nccGetExtendedCallStatus

No SIP response or request.

This function retrieves protocol-specific call status information that includes the To and From URIs and the session description protocol (SDP) information. For more information, refer to Getting extended call status information.

nccHandleTransferRequest

REFER.

Allows the application to either accept (202 response) or reject (501 response) an incoming REFER request. If accepted, NCC automatically implements the transfer.

nccHoldCall

INVITE.

Sends a RE-INVITE using the SDP used when establishing the call. The SDP is modified by marking the stream as sendonly or inactive if previously marked as sendrecv or recvonly respectively. For backward compatibility, the connection address is also set to 0.0.0.0.

nccPlaceCall

INVITE.

Sends an INVITE request to initiate a session. For more information, refer to Placing a call.

nccQueryCapability

No SIP response or request.

This function returns a capability mask that indicates the supported protocol capabilities. Refer to Capability mask for a list of supported capabilities.

nccRegisterUser

REGISTER.

Sends a REGISTER request to register a user with a registrar. This function is SIP specific. For more information, refer to Registering a user.

nccRejectCall

Rejects incoming calls with one of the following responses depending on the NCC rejection method:

NCC method

SIP response

NCC_REJECT_PLAY_BUSY

600 Busy everywhere

NCC_REJECT_PLAY_RINGTONE

603 Decline

NCC_REJECT_PLAY_REORDER

604 Does not exist anywhere

NCC_REJECT_USER_AUDIO

606 Not acceptable

For more information, refer to Rejecting a call.

nccReleaseCall

No SIP response or request.

This function frees a SIP context so that the context can accept another inbound call or can place another outbound call. Even though the SIP server automatically acknowledges a BYE request to disconnect a call with a 200 OK response, nccReleaseCall is required to release the context.

nccRetrieveCall

INVITE.

Sends a RE-INVITE using the SDP used when establishing the call. The call must have been placed on hold prior to using this function.

nccSendCallMessage

Sends messages that cannot be sent using other NCC API calls. When using nccSendCallMessage, decode extended parameters in the same way that you encode them for NCCEVN_PROTOCOL_EVENT.

Note: The SIP server must be aware of the messages the user sends. Otherwise, nccSendCallMessage returns an error. For more information, see Sending SIP messages.

nccSendCapabilityQuery

Requests capability information from the remote by sending a SIP OPTIONS message.

nccSendCapabilityResponse

Responds with capability information to a SIP OPTIONS message.

nccSendPrack

Sends a PRACK message. To use this function, the SIP stack must be configured to support PRACK manually. This function is SIP specific. For more information, refer to Sending a PRACK and to general.manualPRACK in the Configuration parameters table.

nccSendPrackResponse

Sends 200 OK in response to a PRACK. To use this function, the SIP stack must be configured to support PRACK manually. This function is SIP specific. For more information, refer to Acknowledging a PRACK and to general.manualPRACK in the Configuration parameters table.

nccStartProtocol

No SIP response or request.

This function enables a context to run SIP. The trunk control program (TCP) name must be sip0.

nccStopProtocol

Frees the SIP context in the SIP server and stops it from running the SIP protocol. If a session exists on the context, a BYE request is sent to terminate the session.

nccTransferCall

REFER.

If replaces header is enabled, a replaces header is built from the second call handle and placed in the REFER that is sent to the party on the current context. Otherwise, the REFER only contains the contact of the second call handle in the refer-to header.

Automatic responses

Some SIP requests elicit automatic responses. The following table summarizes the automatic responses:

Incoming SIP message

Automatic SIP message

INVITE

100 (TRYING)

200 (OK) following an INVITE request

Note: general.manualACK can override this behavior.

ACK