NCC API events

When a SIP application performs call control functions or processes SIP requests and responses, the NCC API generates events. The names of these NCC events are defined in uppercase letters with an NCCEVN_ prefix.

CTA_EVENT structure

Events arrive in the form of the standard NaturalAccess event data structure.

typedef struct CTA_EVENT
{
DWORD    id;              /* Event code (and source service id)      */
CTAHD    ctahd;           /* Natural Access context handle           */
DWORD    timestamp;       /* Timestamp                               */
DWORD    userid;          /* User id (defined by ctaCreateContext)   */
DWORD    size;            /* Size of buffer if buffer != NULL        */
void     *buffer;         /* Buffer pointer                          */
DWORD    value;           /* Event status or event-specific data     */
DWORD    objHd;           /* Service client side object handle       */
} CTA_EVENT;

The CTA_EVENT structure, returned by ctaWaitEvent, informs the application which event occurred on which context and includes additional information specific to the event.

The CTA_EVENT structure contains the following fields:

Field

Description

id

Contains an event code defined in the library header file. The event's prefix relates the event to a specific NaturalAccess library of functions. All NCC events are prefixed with NCCEVN_ . All NaturalAccess events are prefixed with CTAEVN_.

ctahd

Contains the context handle (line handle) returned from ctaCreateContext.

timestamp

Contains the time when the event was created in milliseconds.

userid

Contains the user-supplied id. This field is unaltered by Natural Access and facilitates asynchronous programming. Its purpose is to correlate a context with an application object or context when events occur.

size

Indicates the size (bytes) of the area pointed to by buffer. If the buffer is NULL, this field can be used to hold an event-specific value.

buffer

Points to data returned with the event. The field contains an application process address and the event's size field contains the actual size of the buffer.

value

Contains an event-specific reason code or error code.

objHd

Contains the call handle, if the event concerns a particular call.

The following table specifies standard NCC events that a SIP application can expect to receive:

NCC event

SIP method

Comments

NCCEVN_SEIZURE
NCCEVN_INCOMING_CALL

INVITE

An incoming INVITE generates both of these events.

NCCEVN_CALL_PROCEEDING

100 TRYING

A 100 Trying response was received.

NCCEVN_REMOTE_ALERTING

180 RINGING

A 180 Ringing response was received.

NCCEVN_PROTOCOL_EVENT

All SIP requests and responses

If the SIP stack is configured to pass back all protocol events, all requests and responses are passed to the application through this event. The parameter that controls this behavior is general.sendProtocolEvents.

NCCEVN_CALL_CONNECTED

200 for INVITE or ACK

For outbound calls, a connected event results from an ACK being sent to the line. For inbound calls, receipt of an ACK generates this event.

NCCEVN_CALL_DISCONNECTED

BYE

A BYE request was received.

NCCEVN_CALL_HELD
NCCEVN_CALL_RETRIEVED

A second INVITE request

To place a call on hold, a second INVITE request is sent to the user with the SDP connection address set to 0.0.0.0. The call is retrieved by another INVITE request that contains the original IP address.

NCCEVN_REGISTER_USER

OK in response to a REGISTER request

The NCCEVN_REGISTER_USER can also specify a failure to register the user. The value field contains SUCCESS if the register request succeeded. Otherwise, an error code is returned.

NCCEVN_PRACK_INDICATION

PRACK

Indicates the receipt of PRACK. It is received only if the stack is configured to operate in manual PRACK mode.

NCCEVN_PRACK_CONFIRMATION

200 OK or other final response

Indicates the receipt of a response to PRACK that an application sent manually. The value field contains the response code.

NCCEVN_PLACING_CALL

nccPlaceCall

An INVITE was successfully sent.

NCCEVN_CALL_RELEASED

Errors in outgoing INVITE request or response to nccReleaseCall

Indicates either a response to nccReleaseCall or termination of an outgoing call request due to errors in the INVITE request.

NCCEVN_ACCEPTING_CALL

nccAcceptCall

A 180 Ringing response was successfully sent.

NCCEVN_ANSWERING_CALL

nccAnswerCall

A 200 OK was successfully sent in response to an INVITE.

NCCEVN_REJECTING_CALL

nccRejectCall

Refer to NCC API functions and SIP for NCC API for the nccRejectCall 600 series response codes.

NCCEVN_START_PROTOCOL_DONE

nccStartProtocol

Indicates a response to nccStartProtocol.

NCCEVN_STOP_PROTOCOL_DONE

nccStopProtocol

Indicates a response to nccStopProtocol.

NCCEVN_PROTOCOL_ERROR

Typically sequence errors

The value field describes the specifics of the failure being reported.

NCCEVN_CAPABILITY_INDICATION

OPTIONS

Indicates the receipt of OPTIONS. This event is received only if the stack is configured to receive capability events (nccStartProtocol with the eventmask set with NCC_REPORT_CAPABILITY).

NCCEVN_CAPABILITY_RESPONSE

200 OK or other final response

The value field describes the specifics of the success or failure being reported for the OPTIONS method. This event is received only if the stack is configured to receive capability events (nccStartProtocol with the eventmask set with NCC_REPORT_CAPABILITY).