# Receiving events and ISDN protocol stack messages

All messages and events are returned to the application through the standard Natural Access event handling mechanism. The events returned can be standard Natural Access events, events sent by an ISDN protocol stack instance, or events specific to any Natural Access extensions. They arrive in the form of the standard event data structure:

typedef struct CTA_EVENT
{
DWORD id; /* Event code (and source service ID) */
CTAHD ctahd; /* 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 informs the application which event occurred on which context, and provides additional information specific to the event. The event's prefix relates the event to a specific NMS library of functions. The following table shows some of the available prefixes:

This prefix... | Indicates...
--- | ---
CTAEVN | A Natural Access event.
NCCEVN | An NCC service event.
ADIEVN | An ADI service event.
ISDNEVN | An NMS ISDN event.
OAMEVN | An OAM service event.
HSWEVN | An OAM Hot Swap event.
CLKEVN | An OAM clock management event.

The CTA_EVENT structure fields are used as follows:

Field | Description
--- | ---
id | Contains an event code defined in the library header file. All NMS ISDN events are prefixed with ISDNEVN_ (for example, ISDNEVN_SOMETHING_HAPPENED).
ctahd | Contains the context handle returned from ctaCreateContext.
timestamp | Contains the time when the event was created in milliseconds since midnight, January 1, 1970, modulo 49 days. The resolution for board events is 10 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 and context when events occur.
size | Indicates the size (bytes) of the area pointed to by buffer. If the buffer is NULL, this field can hold an event-specific value.
buffer | Points to data returned with the event. The field contains an application process address. The event's size field contains the actual size of the buffer.
value | Provides a reason code or an error code. This is an event-specific value.
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 ctaWaitEvent.