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.