(Page 1 of 33 in this chapter) Version

Chapter 9

Alphabetical Event Reference

9.1 Introduction
9.2 About the Event Data Structure
9.3 Alphabetical Event Reference

9.1 Introduction

The NCC service employs an asynchronous programming model in order to capitalize on the concurrent processing between AG board processors and the host CPU. In response to commands executed by the application, the NCC service generates events which indicate the occurrence of certain conditions or state changes. This appendix is a summary of the events generated by the NCC service.

9.2 About the Event Data Structure

Events arrive in the form of the standard CTA event data structure:

typedef struct CTA_EVENT
{
    DWORD    id;                /* Event code (and source service id)      */
    CTAHD    ctahd;             /* CT 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 CTA context, as well as including 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 Natural MicroSystems library of functions. For example, all NCC events are prefixed with NCCEVN_ (e.g., NCCEVN_SOMETHING_ HAPPENED). All CT Access events are prefixed with CTAEVN_.

ctahd

 Contains the CTA context handle (line 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 AG board events is 10 milliseconds.

userid

 Contains the user-supplied id. This field is unaltered by CT Access and facilitates asynchronous programming. Its purpose is to correlate a CTA 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 may 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.

9.3 Alphabetical Event Reference

This chapter provides a comprehensive, alphabetically-ordered reference to the NCC service events. A typical event description includes:

Description

 A brief description of the meaning of the event.

State Transition

 If the event signifies a call or line state transition, the transition is described here. If the event is informational, "None" appears here.

Associated Function

 If the event is solicited (i.e., it occurs as a result of a function call), the associated function or functions are listed here. If the event is unsolicited, "Unsolicited" appears here.

Contains

 Lists information returned with the event, such as line or call handles or values.

Reason Codes

 If the event returns a value field, possible values are listed here.

Details

 Lists any further information about the event, such as capabilitymask or bit settings which regulate whether the event occurs.


(Page 1 of 33 in this chapter) Version

tech_support@nmss.com
Copyright © 1999, Natural MicroSystems, Inc. All rights reserved.