When performing call control functions, the NCC API processes two kinds of events: those that arrive from the network, and those that are generated in response to NCC API commands. The NCC API translates the network events into generic call control events. The names are defined in uppercase letters with an NCCEVN_ prefix. The network events fall into two classes: transitional and informational.
Transitional events are generated when the call or line state changes. They are generated because the NCC API needs the application to choose an action or acknowledge that an application command is proceeding.
Informational events do not change the line or call state. For example, the protocol error event, NCCEVN_PROTOCOL_ERROR, provides information about abnormalities on the line including false seizure, too many incoming digits, or premature answer while dialing.
Events are also classified as solicited or unsolicited.
Solicited events are generated as a result of an application executing a command.
Unsolicited events are the consequences of activities on the network.
Some NCC API events are solicited events in some circumstances, and unsolicited events in other circumstances. Some events are generated only if you enable them by setting them in the NCC.START.eventmask parameter. For more information about this parameter, see NCC API global parameters.
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;
This 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 function library. 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 NaturalAccess and facilitates asynchronous programming. Its purpose is to correlate a context with an application object/context when events occur. |
|
size |
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 |
This field 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 |
This is an event-specific value. This field can hold a reason code or an error code. |
|
objHd |
Contains the call handle, if the event concerns a particular call. If the event concerns the line and not a particular call, objHd is NULL. |
When a line or call is in a given state, any unsolicited event that is valid to be received in that state can be received regardless of any pending function calls. For example, assume an application calls nccAnswerCall for a call in the NCC_CALLSTATE_RECEIVING_DIGITS state. Any unsolicited events that can be received in the NCC_CALLSTATE_RECEIVING_DIGITS state are valid, even while nccAnswerCall is pending. You do not proceed into the NCCEVN_CALLSTATE_ANSWERING state until the NCCEVN_CALL_ANSWERED event is received.
Your application does not have to check for certain solicited events if the application has not invoked the corresponding function call. For instance, continuing the previous example, NCCEVN_ACCEPTING_CALL will not arrive because the function nccAcceptCall was not invoked. To determine if an event is solicited, unsolicited, or both, refer to the event details in the alphabetical event listing.
Some events are generated only if they are enabled by setting a parameter. For instance, if overlapped receiving is turned on (NCC.START.overlappedreceiving parameter = 1), the application receives NCCEVN_RECEIVED_DIGIT for calls on that line. For a discussion of how to use parameters to specify the events your application can handle, see the NCC.START.eventmask and NCC.START.overlappedreceiving parameter descriptions in NCC API global parameters.
Refer to NCC events and line states and NCC events and call states to determine which events your application may receive in a given line/call state.