Overview of events

This section presents the three types of NaturalFax events:

NaturalFax uses the same event reporting mechanism as Natural Access. The structure informs the application about which event occurred on which context, and includes information specific to the event.

All events in the Natural Access environment are represented by a C data structure, as shown in the following generic CTA_EVENT:

typedef struct
    {
    DWORD id;          /* Event id (LIBEVN_xxx in 'libdef.h')         */
    CTAHD ctahd;       /* Context handle                              */
    DWORD timestamp;   /* Timestamp                                   */
    DWORD userid;      /* Use-supplied id                             */
    DWORD size;        /* Size of buffer if buffer is not NULL        */
                       /* Otherwise, may contain event-specific data  */
    void *buffer;      /* Buffer pointer                              */
    DWORD value;       /* Event status or event-specific data         */
    UINTPTR objHd;     /* Service object handle                       */
    } CTA_EVENT;

This structure, returned by ctaWaitEvent, informs the application which event occurred on which context, and provides additional information specific to the event.

The event structure contains the following fields:

Field	Description
id	Contains an event code defined in the library header file. All NaturalFax event codes are defined in the nfxdef.h header file. All NaturalFax events are prefixed with NFXEVN_. All ADI service events are prefixed with ADIEVN_ and are defined in adidef.h.
ctahd	Contains the context handle (returned from ctaCreateContext).
timestamp	Contains the time when the event was created.
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/context when events occur.
size	NaturalFax does not use this field.
buffer	NaturalFax does not use this field.
value	This is an event-specific value. This field can hold a reason code or an error code.
objHd	Service object handle (for example, swihd, vcehd, callhd).

Three of the NaturalFax events, NFXEVN_PAGE_END, NFXEVN_DOC_END, and NFXEVN_SESSION_DONE, may contain reason or error codes in the value field, as specified in the following tables.

Refer to the ADI Service Developer's Reference Manual for a detailed explanation of events, errors, and reason codes in the ADI service. Refer to the Natural Access Developer's Reference Manual for a detailed explanation of events, errors, and reason codes in Natural Access.