Version

Appendix E

NaturalFax for TAPI Events

Introduction

Completion Events

Errors and Reasons for the Value Field

Informational Events

: Confirmation Events
: NaturalFax Events and NaturalFax for TAPI Events

Introduction

This appendix describes the events that NaturalFax for TAPI can expect. It also compares NaturalFax for TAPI events with NaturalFax events.

Completion Events

The FAXMSG_SESSION_DONE event is sent as the last event for all asynchronous NaturalFax for TAPI functions, regardless of the results or function requested. Always wait for this event before attempting the next NaturalFax for TAPI function. Event Name Hex Description FAXMSG_SESSION_DONE 0x052001 The current fax session has completed.

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

Errors and Reasons for the Value Field

The following error and reason codes, which are presented in alphabetical order, can appear in the value field of the FAXEVN_SESSION_DONE event:

Reason or Error

Hex

Description

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.

CTA_REASON_STOPPED

0X1002

The fax function was stopped by calling faxStopSession.

FAXERR_BAD_FILE_FORMAT

0X050207

The specified file is not in TIFF-F format.

FAXERR_BAD_PAGE_SIZE

0X05020B

Unsupported page size.

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

FAXERR_CARRIER_LOST

0X05021D

The received signal has fallen below the level specified by the threshold parameter in FAX_RECEIVE_PARMS and the fax session has been terminated.

FAXERR_CONNECT_FAILED

0X050201

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

FAXERR_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 FAX_TRANSMIT_PARMS or FAX_RECEIVE_PARMS is set to NFX_OTF_NEVER).

FAXERR_FAX_SERVICE

0X050219

A fatal error occurred in the FAX service. Contact NMS Technical Services.

FAXERR_FXM_SERVICE

0X05021A

A fatal error occurred in the FXM service. Contact NMS Technical Services.

FAXERR_INCOMPATIBLE_RECEIVER

0X050216

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

FAXERR_INTERNAL_ERROR

0X58000 -
0X5FFFF

An unexpected internal error has occurred. Contact NMS Technical Services.

FAXERR_NEGOTIATION_FAILED

0x050202

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

FAXERR_NO_MODEMS

0x050213

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

FAXERR_NO_MORE_DOCUMENTS

0x05020F

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

FAXERR_NO_PPM

0x050214

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

FAXERR_NO_PPM_RESPONSE

0x050215

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

FAXERR_NO_REMOTE

0x05021C

The called fax terminal did not send a DIS signal.

FAXERR_OPEN_QUEUE_FAILED

0x05020A

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

FAXERR_PROTOCOL_ERROR

0x050217

A T.30 protocol error occurred.

FAXERR_QUEUE_EMPTY

0x050206

The specified document queue is empty.

FAXERR_QUEUE_TOO_LATE

0x050208

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

FAXERR_RATE_TOO_LOW

0x050210

The receiving or transmitting fax terminal is attempting to receive or transmit at a rate lower than the minrate (in the corresponding FAX_TRANSMIT_PARMS or FAX_RECEIVE_PARMS structure).

FAXERR_REMOTE_DCN

0x05021B

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

FAXERR_RETRAIN_NEGATIVE

0x05021E

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

FAXERR_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
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.
CTA_REASON_STOPPED	0X1002	The fax function was stopped by calling faxStopSession.
FAXERR_BAD_FILE_FORMAT	0X050207	The specified file is not in TIFF-F format.
FAXERR_BAD_PAGE_SIZE	0X05020B	Unsupported page size.
FAXERR_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.
FAXERR_CARRIER_LOST	0X05021D	The received signal has fallen below the level specified by the threshold parameter in FAX_RECEIVE_PARMS and the fax session has been terminated.
FAXERR_CONNECT_FAILED	0X050201	The called fax machine was not detected. Check that the number you are dialing is connected to a fax machine.
FAXERR_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 FAX_TRANSMIT_PARMS or FAX_RECEIVE_PARMS is set to NFX_OTF_NEVER).
FAXERR_FAX_SERVICE	0X050219	A fatal error occurred in the FAX service. Contact NMS Technical Services.
FAXERR_FXM_SERVICE	0X05021A	A fatal error occurred in the FXM service. Contact NMS Technical Services.
FAXERR_INCOMPATIBLE_RECEIVER	0X050216	The application has disabled on-the-fly conversion and the receiver can not handle the specified image format.
FAXERR_INTERNAL_ERROR	0X58000 - 0X5FFFF	An unexpected internal error has occurred. Contact NMS Technical Services.
FAXERR_NEGOTIATION_FAILED	0x050202	Failed T.30 fax negotiation at the beginning of a session or between documents. This error indicates that training failed (usually due to bad phone line quality) when transmitting. This error may also indicate that the transmitter and receiver capabilities do not match. When receiving, this error indicates that training failed.
FAXERR_NO_MODEMS	0x050213	The required DSP files are not configured or loaded to the AG board. The FXM service failed to start.
FAXERR_NO_MORE_DOCUMENTS	0x05020F	The fax session ended because there were no more receive files in the receive document queue.
FAXERR_NO_PPM	0x050214	The receiver has not received a correct post-page message.
FAXERR_NO_PPM_RESPONSE	0x050215	The receiver has not returned a correct response to the post-page message.
FAXERR_NO_REMOTE	0x05021C	The called fax terminal did not send a DIS signal.
FAXERR_OPEN_QUEUE_FAILED	0x05020A	Could not open the specified document queue. Check that you have a valid transmit queue.
FAXERR_PROTOCOL_ERROR	0x050217	A T.30 protocol error occurred.
FAXERR_QUEUE_EMPTY	0x050206	The specified document queue is empty.
FAXERR_QUEUE_TOO_LATE	0x050208	Attempted to enqueue a file in an active transmit or receive queue too late in the fax session.
FAXERR_RATE_TOO_LOW	0x050210	The receiving or transmitting fax terminal is attempting to receive or transmit at a rate lower than the minrate (in the corresponding FAX_TRANSMIT_PARMS or FAX_RECEIVE_PARMS structure).
FAXERR_REMOTE_DCN	0x05021B	The remote terminal has sent an unexpected disconnect (DCN) command frame.
FAXERR_RETRAIN_NEGATIVE	0x05021E	The page was received with errors, and NaturalFax for TAPI has requested that the remote transmitter retransmit the last page.
FAXERR_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

FAXMSG_CANNOT_OPEN_FILE

0x052007

The specified file was not located by faxSendFax, faxReceiveFax, or faxAnswerFaxPoll. On transmit, the function continues to the next file in the document queue.

FAXMSG_DOC_BEGIN

0x052003

Document transmission or reception has started. Call faxGetSessionStatus to verify the negotiated values.

FAXMSG_DOC_END

0x052004

Document transmission or reception has ended. To retrieve additional status information, call faxGetSessionStatusor faxGetDocStatus.

FAXMSG_PAGE_BEGIN

0x052001

Page transmission or reception has started. To retrieve additional status information, call faxGetSessionStatus.

FAXMSG_PAGE_END

0x052002

Page transmission or reception has ended. To retrieve additional status information, call faxGetSessionStatus.

FAXMSG_POLLED

0x052005

The calling fax machine has polled NaturalFax for TAPI.

FAXMSG_PROCEDURE_INTERRUPT

0x052006

A procedure interrupt has been received from the remote fax machine.

FAXMSG_REMOTE_IDENTIFIED

0x05200A

The remote terminal information is available. Check the session status to verify the remote SID and NSF.
The following values may appear in the event value field of the FAXMSG_DOC_END event when NaturalFax for TAPI is successfully receiving a fax: Value Hex Description SUCCESS 0 Transmission of the document is complete. 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. 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).

The following values may appear in the event value field of FAXMSG_DOC_END and FAXMSG_PAGE_END events when errors occur when NaturalFax for TAPI is receiving a fax:

Value

Hex

Description

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.

CTA_REASON_STOPPED

0X1002

The fax function was stopped by calling faxStopSession.

FAXMSG_CARRIER_LOST

0X05021D

The received signal has fallen below the level specified by the threshold parameter in FAX_RECEIVE_PARMS and the fax session has been terminated.

FAXMSG_CONNECT_FAILED

0X050201

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

FAXMSG_FAX_SERVICE

0X050219

A fatal error occurred in the FAX service. Contact NMS Technical Services.

FAXMSG_FXM_SERVICE

0X05021A

A fatal error occurred in the FXM service. Contact NMS Technical Services.

FAXMSG_INTERNAL_ERROR

0X58000 -
0X5FFFF

An unexpected internal error has occurred. Contact NMS Technical Services.

FAXMSG_NEGOTIATION_FAILED

0x050202

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

FAXMSG_NO_MORE_DOCUMENTS

0x05020F

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

FAXMSG_NO_PPM

0x050214

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

FAXMSG_PROTOCOL_ERROR

0x050217

A T.30 protocol error occurred.

FAXMSG_QUEUE_EMPTY

0x050206

The specified document queue is empty.

FAXMSG_RATE_TOO_LOW

0x050210

The receiving or transmitting fax terminal is attempting to receive or transmit at a rate lower than the minrate(in the corresponding FAX_TRANSMIT_PARMS or FAX_RECEIVE_PARMS structure).

FAXMSG_REMOTE_DCN

0x05021B

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

FAXMSG_RETRAIN_NEGATIVE

0x05021E

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

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

Event	Hex	Description
FAXMSG_CANNOT_OPEN_FILE	0x052007	The specified file was not located by faxSendFax, faxReceiveFax, or faxAnswerFaxPoll. On transmit, the function continues to the next file in the document queue.
FAXMSG_DOC_BEGIN	0x052003	Document transmission or reception has started. Call faxGetSessionStatus to verify the negotiated values.
FAXMSG_DOC_END	0x052004	Document transmission or reception has ended. To retrieve additional status information, call faxGetSessionStatusor faxGetDocStatus.
FAXMSG_PAGE_BEGIN	0x052001	Page transmission or reception has started. To retrieve additional status information, call faxGetSessionStatus.
FAXMSG_PAGE_END	0x052002	Page transmission or reception has ended. To retrieve additional status information, call faxGetSessionStatus.
FAXMSG_POLLED	0x052005	The calling fax machine has polled NaturalFax for TAPI.
FAXMSG_PROCEDURE_INTERRUPT	0x052006	A procedure interrupt has been received from the remote fax machine.
FAXMSG_REMOTE_IDENTIFIED	0x05200A	The remote terminal information is available. Check the session status to verify the remote SID and NSF.

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

Value	Hex	Description
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.
CTA_REASON_STOPPED	0X1002	The fax function was stopped by calling faxStopSession.
FAXMSG_CARRIER_LOST	0X05021D	The received signal has fallen below the level specified by the threshold parameter in FAX_RECEIVE_PARMS and the fax session has been terminated.
FAXMSG_CONNECT_FAILED	0X050201	The called fax machine was not detected. Check that the number you are dialing is connected to a fax machine.
FAXMSG_FAX_SERVICE	0X050219	A fatal error occurred in the FAX service. Contact NMS Technical Services.
FAXMSG_FXM_SERVICE	0X05021A	A fatal error occurred in the FXM service. Contact NMS Technical Services.
FAXMSG_INTERNAL_ERROR	0X58000 - 0X5FFFF	An unexpected internal error has occurred. Contact NMS Technical Services.
FAXMSG_NEGOTIATION_FAILED	0x050202	Failed T.30 fax negotiation at the beginning of a session or between documents. This error indicates that training failed (usually due to bad phone line quality) when transmitting. This error may also indicate that the transmitter and receiver capabilities do not match. When receiving, this error indicates that training failed.
FAXMSG_NO_MORE_DOCUMENTS	0x05020F	The fax session ended because there were no more receive files in the receive document queue.
FAXMSG_NO_PPM	0x050214	The receiver has not received a correct post-page message.
FAXMSG_PROTOCOL_ERROR	0x050217	A T.30 protocol error occurred.
FAXMSG_QUEUE_EMPTY	0x050206	The specified document queue is empty.
FAXMSG_RATE_TOO_LOW	0x050210	The receiving or transmitting fax terminal is attempting to receive or transmit at a rate lower than the minrate(in the corresponding FAX_TRANSMIT_PARMS or FAX_RECEIVE_PARMS structure).
FAXMSG_REMOTE_DCN	0x05021B	The remote terminal has sent an unexpected disconnect (DCN) command frame.
FAXMSG_RETRAIN_NEGATIVE	0x05021E	The page was received with errors and NaturalFax for TAPI has requested that the remote transmitter retransmit the last page.
FAXMSG_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 for TAPI session:

Event

Hex

Description

FAXMSG_RECEIVE_STARTED

0x052009

Confirms that faxReceiveFax or faxSendFax (in response to a poll request) has started a receive operation.

FAXMSG_SEND_STARTED

0x052008

Confirms that faxSendFax or faxAnswerFaxPoll has started.

Event	Hex	Description
FAXMSG_RECEIVE_STARTED	0x052009	Confirms that faxReceiveFax or faxSendFax (in response to a poll request) has started a receive operation.
FAXMSG_SEND_STARTED	0x052008	Confirms that faxSendFax or faxAnswerFaxPoll has started.

NaturalFax Events and NaturalFax for TAPI Events

The following table lists events returned by NaturalFax for TAPI compared to events that NaturalFax would return, if your application was using NaturalFax.
Note: Error codes returned by NaturalFax for TAPI events match the error codes in the corresponding NaturalFax events.

NaturalFax for TAPI events

NaturalFax events

FAXMSG_SEND_STARTED

NFXEVN_SEND_STARTED

FAXMSG_RECEIVE_STARTED

NFXEVN_RECEIVE_STARTED

FAXMSG_SESSION_DONE

NFXEVN_SESSION_DONE

FAXMSG_DOC_BEGIN

NFXEVN_DOC_BEGIN

FAXMSG_DOC_END

NFXEVN_DOC_END

FAXMSG_PAGE_BEGIN

NFXEVN_PAGE_BEGIN

FAXMSG_PAGE_END

NFXEVN_PAGE_END

FAXMSG_REMOTE_IDENTIFIED

NFXEVN_REMOTE_IDENTIFIED

FAXMSG_POLLED

NFXEVN_POLLED

FAXMSG_PROCEDURE_INTERRUPTED

NFXEVN_PROCEDURE_INTERRUPTED

FAXMSG_CANNOT_OPEN_FILE

NFXEVN_CANNOT_OPEN_FILE

NaturalFax for TAPI events	NaturalFax events
FAXMSG_SEND_STARTED	NFXEVN_SEND_STARTED
FAXMSG_RECEIVE_STARTED	NFXEVN_RECEIVE_STARTED
FAXMSG_SESSION_DONE	NFXEVN_SESSION_DONE
FAXMSG_DOC_BEGIN	NFXEVN_DOC_BEGIN
FAXMSG_DOC_END	NFXEVN_DOC_END
FAXMSG_PAGE_BEGIN	NFXEVN_PAGE_BEGIN
FAXMSG_PAGE_END	NFXEVN_PAGE_END
FAXMSG_REMOTE_IDENTIFIED	NFXEVN_REMOTE_IDENTIFIED
FAXMSG_POLLED	NFXEVN_POLLED
FAXMSG_PROCEDURE_INTERRUPTED	NFXEVN_PROCEDURE_INTERRUPTED
FAXMSG_CANNOT_OPEN_FILE	NFXEVN_CANNOT_OPEN_FILE

Version

Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com