Event Name	Hex	Description
`NFXEVN_SESSION_DONE`	`0x052001`	The current fax session has completed.

(Page 1 of 1 in this chapter)

Appendix C

Event Summary

Introduction

NaturalFax uses the same event reporting mechanism as CT Access. The structure informs the application about which event occurred on which CTA context, as well as including information specific to the event.

About Events

All events in the CT Access environment are represented by a C data structure, as shown in the generic CTA_EVENT below: typedef struct { DWORD id; /* event id (LIBEVN_xxx in 'libdef.h') */ CTAHD ctahd; /* CTA 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 */ DWORD reserved; /* must be 0 */ } CTA_EVENT;
This structure, returned by ctaWaitEvent, informs the application which event occurred on which CTA context, and provides additional information specific to the event. The LIB prefix in LIBEVN relates the event to a specific Natural MicroSystems library of functions. For example, the CTA prefix indicates CT Access, NFX indicates NaturalFax, and VPR indicates NaturalRecognition.
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 CTA 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 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 CT Access context with an application object/CTA context when events occur. value This is an event-specific value. This field can hold a reason code or an error code. size NaturalFax does not use this field. buffer NaturalFax does not use this field.
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 Function Reference Manual for a detailed explanation of events, errors, and reason codes in the ADI Service and the CT Access Developer's Reference Manual for a detailed explanation of events, errors, and reason codes in CT Access.

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 CTA 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 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 CT Access context with an application object/CTA context when events occur.
`value`	This is an event-specific value. This field can hold a `reason` code or an `error` code.
`size`	NaturalFax does not use this field.
`buffer`	NaturalFax does not use this field.

Completion Events

The NFXEVN_SESSION_DONE event is sent as the last event for all asynchronous NaturalFax functions, regardless of the results or function requested. Always wait for this event before attempting the next function on the current CTA context. Event Name Hex Description NFXEVN_SESSION_DONE 0x052001 The current fax session has completed.
The following error and reason codes, which are presented in alphabetical order, may appear in the value field of the NFXEVN_SESSION_DONE event:

Reason or Error

Hex

Description

CTAERR_FILE_EXISTS

0X24

You attempted to create a file that already exists. Remove or rename the existing file, or specify a different file name.

CTAERR_FILE_NOT_FOUND

0X21

The specified file does not exist. Create the file or specify a different file name.

CTAERR_FILE_OPEN_FAILED

0X25

File open failed due to a system error. Verify that the file exists.

CTAERR_FILE_READ_FAILED

0X27

The file is not opened or is locked, or the expected amount of data could not be read. Make sure that the file is of the expected type. Verify that an incorrect handle was not used to close another file.

CTAERR_FILE_WRITE_FAILED

0X28

The file is not open or is locked, or the expected amount of data could not be written. Verify that an incorrect handle was not used to close another file.

CTAERR_FUNCTION_ACTIVE

0XF

A function is already running on the CTA context. Be sure your application waits for a DONE event from other fax or voice operations before initiating a new fax operation.

CTAERR_FUNCTION_NOT_ACTIVE

0XE

An attempt was made to stop or modify a function that was not running.

CTAERR_FUNCTION_NOT_AVAIL

0XD

A NaturalFax DSP file has not been downloaded to the board. Check your AG configuration file and review agerror.log and ag.rpt for start-up problems.

CTAERR_INVALID_CTAHD

0X5

An invalid CTA context handle was passed as an argument to a function or the context was destroyed by another thread.

CTAERR_OUT_OF_MEMORY

0X6

Unable to allocate memory for queue, driver or CTA context, for play or record buffers, or for temporary storage. When this error occurs on a DONE event, it may mean that there was insufficient memory on the board.

CTAERR_OUT_OF_RESOURCES

0X8

A NaturalFax DSP function could not be started. Check to see that you are using the proper AG configuration for your application. Check to see that you have not exceeded the maximum number of fax operations for your hardware configuration.

CTA_REASON_FINISHED

0X1001

The fax function terminated normally.

CTA_REASON_RELEASED

0X1007

The call has been disconnected by the remote fax machine. Check that events are being handled in a timely fashion. Check your host processor CPU loading. The application will also receive ADIEVEN_CALL_DISCONNECTED before NFXEVN_SESSION_DONE.

CTA_REASON_STOPPED

0X51101

The fax function was stopped by calling nfxStopSession.

NFXERR_BAD_FILE_FORMAT

0X050207

The specified file is not in TIFF-F format.

NFXERR_BAD_PAGE_SIZE

0X05020B

Unsupported page size.

NFXERR_BUFFER_UNDERRUN

0X050211

On fax transmit, buffers of image data have not been provided in time. Check your host computer loading to be sure events and disk I/O are being processed in a timely fashion.

NFXERR_CARRIER_LOST

0X05021D

The received signal has fallen below the level specified by NFX_RECEIVE_PARMS.threshold, and the fax session has been terminated.

NFXERR_CONNECT_FAILED

0X050201

The called fax machine was not detected. Check that the number you are dialing is connected to a fax machine.

NFXERR_CONVERSION_REQUIRED

0X05020C

Cannot transmit file because there is a mismatch between the stored file format and the receiving fax terminal's capabilities and on-the-fly conversion has been disabled (otfmode in the receive or transmit parameters is set to NFX_OTF_NEVER).

NFXERR_FAX_SERVICE

0X050217

A fatal error occurred in the FAX service. Contact NMS Developer Support.

NFXERR_FXM_SERVICE

0X05021A

A fatal error occurred in the FXM service. Contact NMS Developer Support.

NFXERR_INCOMPATIBLE_RECEIVER

0X050216

The application has disabled on-the-fly conversion and the receiver can not handle the specified image format.

NFXERR_INTERNAL_ERROR

0X58000 -
0X5FFFF

An unexpected internal error has occurred. Contact NMS Developer Support.

NFXERR_LICENSE_ALREADY_ALLOC

0x050205

A fax license unit is already allocated to this CTA context

NFXERR_NEGOTIATION_FAILED

0x050202

Failed T.30 fax negotiation at the beginning of a session or between documents. When transmitting, this error indicates that training failed (usually due to bad phone line quality) or that the transmitter and receiver capabilities do not match. When receiving, this error indicates that training failed.

NFXERR_NO_MODEMS

0x050213

The required DSP files are not configured or loaded to the AG board. The FXM service failed to start.

NFXERR_NO_LICENSE

0x050204

No fax license unit is allocated to this CTA context.

NFXERR_NO_MORE_LICENSES

0x050203

There are no available fax license units.

NFXERR_NO_MORE_DOCUMENTS

0x05020F

The fax session ended because there were no more receive files in the receive document queue.

NFXERR_NO_PPM

0x050214

The receiver has not received a correct post-page message.

NFXERR_NO_PPM_RESPONSE

0x050215

The receiver has not returned a correct response to the post-page message.

NFXERR_NO_REMOTE

0x05021C

The called fax terminal did not send a DIS signal.

NFXERR_OPEN_QUEUE_FAILED

0x05020A

Could not open the specified document queue. Check that you have a valid transmit queue.

NFXERR_PROTOCOL_ERROR

0x050217

A T.30 protocol error occurred.

NFXERR_QUEUE_EMPTY

0x050206

The specified document queue is empty.

NFXERR_QUEUE_TOO_LATE

0x050208

Attempted to enqueue a file in an active transmit or receive queue too late in the fax session.

NFXERR_RATE_TOO_LOW

0x050210

The receiving or transmitting fax terminal is attempting to receive or transmit at a rate lower than the minrate

NFXERR_REMOTE_DCN

0x05021B

The remote terminal has sent an unexpected disconnect (DCN) command frame.

NFXERR_RETRAIN_NEGATIVE

0x05021E

The page was received with errors, and NaturalFax has requested that the remote transmitter retransmit the last page.

NFXERR_SESSION_FAILED

0x050209

The fax session failed due to an unexpected event. May indicate a T.30 timeout or failure to receive a post page message. Check your host processor CPU and I/O loading.

Reason or Error	Hex	Description
`CTAERR_FILE_EXISTS`	`0X24`	You attempted to create a file that already exists. Remove or rename the existing file, or specify a different file name.
`CTAERR_FILE_NOT_FOUND`	`0X21`	The specified file does not exist. Create the file or specify a different file name.
`CTAERR_FILE_OPEN_FAILED`	`0X25`	File open failed due to a system error. Verify that the file exists.
`CTAERR_FILE_READ_FAILED`	`0X27`	The file is not opened or is locked, or the expected amount of data could not be read. Make sure that the file is of the expected type. Verify that an incorrect handle was not used to close another file.
`CTAERR_FILE_WRITE_FAILED`	`0X28`	The file is not open or is locked, or the expected amount of data could not be written. Verify that an incorrect handle was not used to close another file.
`CTAERR_FUNCTION_ACTIVE`	`0XF`	A function is already running on the CTA context. Be sure your application waits for a `DONE` event from other fax or voice operations before initiating a new fax operation.
`CTAERR_FUNCTION_NOT_ACTIVE`	`0XE`	An attempt was made to stop or modify a function that was not running.
`CTAERR_FUNCTION_NOT_AVAIL`	`0XD`	A NaturalFax DSP file has not been downloaded to the board. Check your AG configuration file and review `agerror.log` and `ag.rpt` for start-up problems.
`CTAERR_INVALID_CTAHD`	`0X5`	An invalid CTA context handle was passed as an argument to a function or the context was destroyed by another thread.
`CTAERR_OUT_OF_MEMORY`	`0X6`	Unable to allocate memory for queue, driver or CTA context, for play or record buffers, or for temporary storage. When this error occurs on a `DONE` event, it may mean that there was insufficient memory on the board.
`CTAERR_OUT_OF_RESOURCES`	`0X8`	A NaturalFax DSP function could not be started. Check to see that you are using the proper AG configuration for your application. Check to see that you have not exceeded the maximum number of fax operations for your hardware configuration.
`CTA_REASON_FINISHED`	`0X1001`	The fax function terminated normally.
`CTA_REASON_RELEASED`	`0X1007`	The call has been disconnected by the remote fax machine. Check that events are being handled in a timely fashion. Check your host processor CPU loading. The application will also receive `ADIEVEN_CALL_DISCONNECTED` before `NFXEVN_SESSION_DONE`.
`CTA_REASON_STOPPED`	`0X51101`	The fax function was stopped by calling `nfxStopSession`.
`NFXERR_BAD_FILE_FORMAT`	`0X050207`	The specified file is not in TIFF-F format.
`NFXERR_BAD_PAGE_SIZE`	`0X05020B`	Unsupported page size.
`NFXERR_BUFFER_UNDERRUN`	`0X050211`	On fax transmit, buffers of image data have not been provided in time. Check your host computer loading to be sure events and disk I/O are being processed in a timely fashion.
`NFXERR_CARRIER_LOST`	`0X05021D`	The received signal has fallen below the level specified by `NFX_RECEIVE_PARMS.threshold`, and the fax session has been terminated.
`NFXERR_CONNECT_FAILED`	`0X050201`	The called fax machine was not detected. Check that the number you are dialing is connected to a fax machine.
`NFXERR_CONVERSION_REQUIRED`	`0X05020C`	Cannot transmit file because there is a mismatch between the stored file format and the receiving fax terminal's capabilities and on-the-fly conversion has been disabled (`otfmode` in the receive or transmit parameters is set to `NFX_OTF_NEVER`).
`NFXERR_FAX_SERVICE`	`0X050217`	A fatal error occurred in the FAX service. Contact NMS Developer Support.
`NFXERR_FXM_SERVICE`	`0X05021A`	A fatal error occurred in the FXM service. Contact NMS Developer Support.
`NFXERR_INCOMPATIBLE_RECEIVER`	`0X050216`	The application has disabled on-the-fly conversion and the receiver can not handle the specified image format.
`NFXERR_INTERNAL_ERROR`	`0X58000 -` `0X5FFFF`	An unexpected internal error has occurred. Contact NMS Developer Support.
`NFXERR_LICENSE_ALREADY_ALLOC`	`0x050205`	A fax license unit is already allocated to this CTA context
`NFXERR_NEGOTIATION_FAILED`	`0x050202`	Failed T.30 fax negotiation at the beginning of a session or between documents. When transmitting, this error indicates that training failed (usually due to bad phone line quality) or that the transmitter and receiver capabilities do not match. When receiving, this error indicates that training failed.
`NFXERR_NO_MODEMS`	0x050213	The required DSP files are not configured or loaded to the AG board. The FXM service failed to start.
`NFXERR_NO_LICENSE`	`0x050204`	No fax license unit is allocated to this CTA context.
`NFXERR_NO_MORE_LICENSES`	`0x050203`	There are no available fax license units.
`NFXERR_NO_MORE_DOCUMENTS`	`0x05020F`	The fax session ended because there were no more receive files in the receive document queue.
`NFXERR_NO_PPM`	0x050214	The receiver has not received a correct post-page message.
`NFXERR_NO_PPM_RESPONSE`	0x050215	The receiver has not returned a correct response to the post-page message.
`NFXERR_NO_REMOTE`	0x05021C	The called fax terminal did not send a DIS signal.
`NFXERR_OPEN_QUEUE_FAILED`	`0x05020A`	Could not open the specified document queue. Check that you have a valid transmit queue.
`NFXERR_PROTOCOL_ERROR`	0x050217	A T.30 protocol error occurred.
`NFXERR_QUEUE_EMPTY`	`0x050206`	The specified document queue is empty.
`NFXERR_QUEUE_TOO_LATE`	`0x050208`	Attempted to enqueue a file in an active transmit or receive queue too late in the fax session.
`NFXERR_RATE_TOO_LOW`	`0x050210`	The receiving or transmitting fax terminal is attempting to receive or transmit at a rate lower than the `minrate`
`NFXERR_REMOTE_DCN`	0x05021B	The remote terminal has sent an unexpected disconnect (DCN) command frame.
`NFXERR_RETRAIN_NEGATIVE`	0x05021E	The page was received with errors, and NaturalFax has requested that the remote transmitter retransmit the last page.
`NFXERR_SESSION_FAILED`	`0x050209`	The fax session failed due to an unexpected event. May indicate a T.30 timeout or failure to receive a post page message. Check your host processor CPU and I/O loading.

Informational Events

The following events, which are presented in alphabetical order, provide additional information during a fax session: Event Hex Description NFXEVN_CANNOT_OPEN_FILE 0x052007 The specified file was not located by nfxSendFax, nfxReceiveFax, or nfxAnswerFaxPoll. On transmit, the function continues to the next file in the document queue. NFXEVN_DOC_BEGIN 0x052003 Document transmission or reception has started. Once you receive this event, you can call nfxGetSessionStatus to verify the negotiated values. NFXEVN_DOC_END 0x052004 Document transmission or reception has ended. To retrieve additional status information, call nfxGetSessionStatus or nfxGetDocStatus. NFXEVN_PAGE_BEGIN 0x052001 Page transmission or reception has started. To retrieve additional status information, call nfxGetSessionStatus. NFXEVN_PAGE_END 0x052002 Page transmission or reception has ended. To retrieve additional status information, call nfxGetSessionStatus. NFXEVN_POLLED 0x052005 The calling fax machine has polled NaturalFax. NFXEVN_PROCEDURE_INTERRUPT 0x052006 A Procedure Interrupt has been received from the remote fax machine. NFXEVN_REMOTE_IDENTIFIED 0x05200A The remote terminal information is available. You can check the session status to verify the remote SID and NSF.
The following values may appear in the event value field of the NFXEVN_DOC_END event when NaturalFax is receiving a fax: Event Hex Description SUCCESS 0 Transmission of the document is complete. NFX_T30_EOM 1 End of message received from remote fax terminal (more documents to follow). NFX_T30_EOP 2 End of procedure received from remote fax terminal (no more documents will be transmitted).

Event	Hex	Description
`NFXEVN_CANNOT_OPEN_FILE`	`0x052007`	The specified file was not located by `nfxSendFax`, `nfxReceiveFax`, or `nfxAnswerFaxPoll`. On transmit, the function continues to the next file in the document queue.
`NFXEVN_DOC_BEGIN`	`0x052003`	Document transmission or reception has started. Once you receive this event, you can call `nfxGetSessionStatus` to verify the negotiated values.
`NFXEVN_DOC_END`	`0x052004`	Document transmission or reception has ended. To retrieve additional status information, call `nfxGetSessionStatus` or `nfxGetDocStatus`.
`NFXEVN_PAGE_BEGIN`	`0x052001`	Page transmission or reception has started. To retrieve additional status information, call `nfxGetSessionStatus`.
`NFXEVN_PAGE_END`	`0x052002`	Page transmission or reception has ended. To retrieve additional status information, call `nfxGetSessionStatus`.
`NFXEVN_POLLED`	`0x052005`	The calling fax machine has polled NaturalFax.
`NFXEVN_PROCEDURE_INTERRUPT`	`0x052006`	A Procedure Interrupt has been received from the remote fax machine.
`NFXEVN_REMOTE_IDENTIFIED`	`0x05200A`	The remote terminal information is available. You can check the session status to verify the remote SID and NSF.

Event	Hex	Description
`SUCCESS`	`0`	Transmission of the document is complete.
`NFX_T30_EOM`	`1`	End of message received from remote fax terminal (more documents to follow).
`NFX_T30_EOP`	`2`	End of procedure received from remote fax terminal (no more documents will be transmitted).

Confirmation Events

The following events confirm the successful start of a NaturalFax session: Event Hex Description NFXEVN_RECEIVE_STARTED 0x052009 Confirms that nfxReceiveFax or nfxSendFax (in response to a poll request) has started a receive operation. NFXEVN_SEND_STARTED 0x052008 Confirms that nfxSendFax or nfxAnswerFaxPoll has started.

Event	Hex	Description
`NFXEVN_RECEIVE_STARTED`	`0x052009`	Confirms that `nfxReceiveFax` or `nfxSendFax` (in response to a poll request) has started a receive operation.
`NFXEVN_SEND_STARTED`	`0x052008`	Confirms that `nfxSendFax` or `nfxAnswerFaxPoll` has started.

(Page 1 of 1 in this chapter)

tech_support@nmss.com