NaturalFax Error Codes

Alphabetical Error Summary

Numerical Error Summary

NaturalFax Events

Completion Events

NFXEVN_SESSION_DONE Values

Informational Events

NFXEVN_DOC_END Values

NFXEVN_DOC_END and NFXEVN_PAGE_END Values

Confirmation Events

NaturalFax Error Codes

Error codes, with their corresponding descriptions are presented in two tables for quick reference:

• Alphabetically ordered by error code name including a description of the problem

• Numerically ordered in hexadecimal with the decimal equivalent and error name

All Natural Access and Natural Access service functions return a status code. If the return code is not SUCCESS (0), it is an error code indicating that the function has failed and a reason for the failure.

Additional information about an error condition may be available by calling nfxGetSessionStatus or nfxGetDocStatus and examining the error field in the NFX_FAX_STATUS structure or the lasterror field in NFX_DOC_STATUS. A table with these error codes is also provided.

NaturalFax error codes are prefixed with NFXERR, and are defined in nfxdef.h. For information about Natural Access error codes (prefixed with CTAERR), refer to the Natural Access Developer's Reference Manual.

Alphabetical Error Summary

The following table lists NaturalFax errors in alphabetical order. All errors are 32 bit.

Error Name	Hex	Decimal	Description
NFXERR_BAD_FILE_FORMAT	0x050207	328199	The specified file is not in TIFF-F or TIFF-S format.
NFXERR_BAD_PAGE_SIZE	0x05020B	328203	Unsupported page size.
NFXERR_BUFFER_UNDERRUN	0x050211	328209	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	328221	The received signal has fallen below the level specified by NFX_RECEIVE_PARMS.threshold, and the fax session has been terminated.
NFXERR_CHECK_BAD_LINES	0x05020D	328205	Returned by nfxCheckTIFF to indicate that there are bad lines in the TIFF-F or TIFF-S file. The file can still be transmitted by NaturalFax, and status information returned by nfxCheckTIFF is valid.
NFXERR_CHECK_DIFF_ATTRIB	0x05020E	328206	Returned by nfxCheckTIFF to indicate that all pages in the TIFF-F or TIFF-S file do not have the same attributes (for encoding, page width, and resolution). The file may not be transmitted by NaturalFax, but the status information returned by nfxCheckTIFF is valid.
NFXERR_CONNECT_FAILED	0x050201	328193	The called fax machine was not detected. Check that the number you are dialing is a fax machine.
NFXERR_CONVERSION_REQUIRED	0x05020C	328204	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	0x050219	328217	A fatal error occurred in the FAX service.
NFXERR_FXM_SERVICE	0x05021A	328218	A fatal error occurred in the FXM service.
NFXERR_INCOMPATIBLE_RECEIVER	0x050216	328214	The application has disabled on-the-fly conversion and the receiver can not handle the specified image format.
NFXERR_INTERNAL_ERROR	0x58000 - 0x5FFFF	360448 - 393215	An unexpected internal error has occurred.
NFXERR_NEGOTIATION_FAILED	0x050202	328194	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	328211	The required DSP files are not configured or loaded to the board. The FXM service failed to start.
NFXERR_NO_PPM	0x050214	328212	The receiver has not received a correct post-page message.
NFXERR_NO_PPM_RESPONSE	0x050215	328213	The receiver has not returned a correct response to the post-page message.
NFXERR_NO_REMOTE	0x05021C	328220	The called fax terminal did not send a DIS signal.
NFXERR_OPEN_QUEUE_FAILED	0x05020A	328202	Could not open the specified document queue. Check that you have a valid transmit queue.
NFXERR_PROTOCOL_ERROR	0x050217	328215	A T.30 protocol error occurred.
NFXERR_QUEUE_EMPTY	0x050206	328198	The specified document queue is empty.
NFXERR_QUEUE_TOO_LATE	0x050208	328200	Attempted to enqueue a file in an active transmit queue too late in the fax session.
NFXERR_RATE_TOO_LOW	0x050210	328208	The receiving or transmitting fax terminal is attempting to receive or transmit at a rate lower than the minrate.
NFXERR_REMOTE_DCN	0x05021B	328219	The remote terminal has sent an unexpected disconnect (DCN) command frame.
NFXERR_RETRAIN_NEGATIVE	0x05021E	328222	The page was received with errors, and NaturalFax has requested that the remote transmitter retransmit the last page.
NFXERR_SESSION_FAILED	0x050209	328201	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.

Numerical Error Summary

The following table lists NaturalFax errors in numerical order:

Hex	Decimal	Error Name
0x050201	328193	NFXERR_CONNECT_FAILED
0x050202	328194	NFXERR_NEGOTIATION_FAILED
0x050206	328198	NFXERR_QUEUE_EMPTY
0x050207	328199	NFXERR_BAD_FILE_FORMAT
0x050208	328200	NFXERR_QUEUE_TOO_LATE
0x050209	328201	NFXERR_SESSION_FAILED
0x05020A	328202	NFXERR_OPEN_QUEUE_FAILED
0x05020B	328203	NFXERR_BAD_PAGE_SIZE
0x05020C	328204	NFXERR_CONVERSION_REQUIRED
0x05020D	328205	NFXERR_CHECK_BAD_LINES
0x05020E	328206	NFXERR_CHECK_DIFF_ATTRIB
0x050210	328208	NFXERR_RATE_TOO_LOW
0x050211	328209	NFXERR_BUFFER_UNDERRUN
0x050212	328210	NFXERR_BUFFER_OVERRUN
0x050213	328211	NFXERR_NO_MODEMS
0x050214	328212	NFXERR_NO_PPM
0x050215	328213	NFXERR_NO_PPM_RESPONSE
0x050217	328215	NFXERR_PROTOCOL_ERROR
0x050219	328217	NFXERR_FAX_SERVICE
0x05021A	328218	NFXERR_FXM_SERVICE
0x05021B	328219	NFXERR_REMOTE_DCN
0x05021C	328220	NFXERR_NO_REMOTE
0x05021D	328221	NFXERR_CARRIER_LOST
0x05021E	328222	NFXERR_RETRAIN_NEGATIVE
0x058000-0x05FFFF	360448 - 393215	NFX_INTERNAL_ERROR

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            */
  DWORD reserved;     /* must be 0            */
  } 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.
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 Natural Access Developer's Reference Manual for a detailed explanation of events, errors, and reason codes in Natural Access.

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

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

NFXEVN_SESSION_DONE Values

The following values can appear in the value field of the NFXEVN_SESSION_DONE event:

Error or Reason	Hex	Description
CTAERR_BAD_ARGUMENT	0x7	Invalid modem rate specified for the modem type. Specify a valid modem type/modem rate combination.
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 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 was not downloaded to the board.
CTAERR_INVALID_CTAHD	0X5	An invalid 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 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 board 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	0X1002	The fax function was stopped by calling nfxStopSession.
NFXERR_BAD_FILE_FORMAT	0X050207	The specified file is not in TIFF-F or TIFF-S 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	0X050219	A fatal error occurred in the FAX service.
NFXERR_FXM_SERVICE	0X05021A	A fatal error occurred in the FXM service.
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.
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 board. The FXM service failed to start.
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 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, 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 started. After you receive this event, you can call nfxGetSessionStatus to verify the negotiated values.
NFXEVN_DOC_END	0x052004	Document transmission or reception ended. To retrieve additional status information, call nfxGetSessionStatus or nfxGetDocStatus.
NFXEVN_PAGE_BEGIN	0x052001	Page transmission or reception started. To retrieve additional status information, call nfxGetSessionStatus.
NFXEVN_PAGE_END	0x052002	Page transmission or reception ended. To retrieve additional status information, call nfxGetSessionStatus.
NFXEVN_POLLED	0x052005	The calling fax machine polled NaturalFax.
NFXEVN_PROCEDURE_INTERRUPT	0x052006	A Procedure Interrupt was 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.

NFXEVN_DOC_END Values

The following values can appear in the event value field of the NFXEVN_DOC_END event when NaturalFax successfully receives a fax:

Value	Hex	Description
SUCCESS	0	Transmission of the document is complete.
CTA_REASON_RELEASED	0X1007	The call was 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.
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).

NFXEVN_DOC_END and NFXEVN_PAGE_END Values

The following values can appear in the event value field of NFXEVN_DOC_END and NFXEVN_PAGE_END events when errors occur when NaturalFax is receiving a fax:

Value	Hex	Description
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_OUT_OF_MEMORY	0X6	Unable to allocate memory for queue, driver or 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 board configuration for your application. Check to see that you have not exceeded the maximum number of fax operations for your hardware configuration.
CTA_REASON_RELEASED	0X1007	The remote fax machine disconected the call. 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	0X1002	The fax function was stopped by calling nfxStopSession.
NFXERR_CARRIER_LOST	0X05021D	The received signal fell below the level specified by NFX_RECEIVE_PARMS.threshold, and the fax session was 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_FAX_SERVICE	0X050219	A fatal error occurred in the FAX service.
NFXERR_FXM_SERVICE	0X05021A	A fatal error occurred in the FXM service.
NFXERR_INTERNAL_ERROR	0X58000 - 0X5FFFF	An unexpected internal error occurred.
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_PPM	0x050214	The receiver has not received a correct post-page message.
NFXERR_PROTOCOL_ERROR	0x050217	A T.30 protocol error occurred.
NFXERR_QUEUE_EMPTY	0x050206	The specified document queue is empty.
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.

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.