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

(Page 2 of 2 in this chapter)

Introduction

NaturalFax uses the same event reporting mechanism as CT Access. All NaturalFax events are represented by an CTA_EVENT data structure. The structure informs the application about which event occurred on which CTA context, as well as including information specific to the event. The CTA_EVENT structure contains the following fields:
id A NaturalFax event code 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 The CTA context handle, as returned by ctaCreateCntext.
timestamp The time in milliseconds when the event was created. The resolution for AG board events is 10 milliseconds.
userid The user context value supplied to the ctaCreateContext
function.
value An event-specific value. NFX_REASON_XXX or NFXERR_XXX codes may be placed here.
size NaturalFax does not use this field.
buffer NaturalFax does not use this field.
Two of the NaturalFax events, NFXEVN_SESSION_DONE and NFXEVN_DOC_END, may contain reason codes, as described below. Refer to the ADI Service Function Reference Manual for a detailed explanation of events and reason codes in the ADI Service and the CT Access Function Reference Manual for a detailed explanation of events and reason codes in CT Access.

Completion Events

The NFXEVN_SESSION_DONE event is sent as the last event for all asynchronous fax 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 Code Description NFXEVN_SESSION_DONE 0x052001 The current fax session has completed.

The following reason codes may appear in the value field of the NFXEVN_SESSION_DONE event:

Reason Name

Code

Description

CTA_REASON_FINISHED

0x1001

The fax function terminated normally.

NFX_REASON_STOPPED

0x51101

The fax function was stopped by calling nfxStopSession.

NFXERR _CONNECT_FAILED

0x050201

A called fax terminal was not detected within the specified time.

NFXERR_NEGOTIATION_FAILED

0x050202

Negotiations between NaturalFax and the remote fax terminal failed.

NFXERR_OPEN_QUEUE_FAILED

0x05020A

Could not open the specified application event queue.

CTAERR_FUNCTION_NOT_AVAIL

0xD

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_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.

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.

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.

Reason Name	Code	Description
CTA_REASON_FINISHED	0x1001	The fax function terminated normally.
NFX_REASON_STOPPED	0x51101	The fax function was stopped by calling `nfxStopSession`.
NFXERR _CONNECT_FAILED	0x050201	A called fax terminal was not detected within the specified time.
NFXERR_NEGOTIATION_FAILED	0x050202	Negotiations between NaturalFax and the remote fax terminal failed.
NFXERR_OPEN_QUEUE_FAILED	0x05020A	Could not open the specified application event queue.
CTAERR_FUNCTION_NOT_AVAIL	0xD	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_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.
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.
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.

Information Events

The following events provide information during a fax session: Event Name Code Description NFXEVN_DOC_BEGIN 0x052003 A start-of-message has been transmitted or received. Once you receive this event, you can call nfxGetSessionStatus to verify the negotiated values. NFXEVN_DOC_END 0x052004 An end-of-message has been transmitted or received. NFXEVN_PAGE_BEGIN 0x052001 A start-of-page has been transmitted or received. NFXEVN_PAGE_END 0x052002 An end-of-page has been transmitted or received. 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_CANNOT_OPEN_FILE 0x052007 The specified file was not located by nfxSendFax, nfxReceiveFax, or nfxAnswerFaxPoll. The function continues to the next file in the document queue. 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:Value Code Description 0 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). NFX_T30_DTC 3 Digital transmit command received from remote fax terminal. NFX_T30_DCN 4 Disconnect signal received from remote fax terminal. NFX_T30_TIMEOUT 5 No command was received from the remote fax terminal within the allotted time.

Event Name	Code	Description
NFXEVN_DOC_BEGIN	0x052003	A start-of-message has been transmitted or received. Once you receive this event, you can call `nfxGetSessionStatus` to verify the negotiated values.
NFXEVN_DOC_END	0x052004	An end-of-message has been transmitted or received.
NFXEVN_PAGE_BEGIN	0x052001	A start-of-page has been transmitted or received.
NFXEVN_PAGE_END	0x052002	An end-of-page has been transmitted or received.
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_CANNOT_OPEN_FILE	0x052007	The specified file was not located by `nfxSendFax`, `nfxReceiveFax`, or `nfxAnswerFaxPoll`. The function continues to the next file in the document queue.
NFXEVN_REMOTE_IDENTIFIED	0x05200A	The remote terminal information is available. You can check the session status to verify the remote SID and NSF.

Value	Code	Description
0	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).
NFX_T30_DTC	3	Digital transmit command received from remote fax terminal.
NFX_T30_DCN	4	Disconnect signal received from remote fax terminal.
NFX_T30_TIMEOUT	5	No command was received from the remote fax terminal within the allotted time.

Confirmation Events

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

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

(Page 2 of 2 in this chapter)

tech_support@nmss.com