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