Table of Contents Index NMS Glossary Previous Page Next Page 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

IntroductionTop of Page

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

Completion EventsTop of Page

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.

Errors and Reasons for the Value FieldTop of Page

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.

Informational Events Top of Page

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.

Confirmation Events Top of Page

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.

NaturalFax Events and NaturalFax for TAPI EventsTop of Page

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



Table of Contents Index NMS Glossary Previous Page Next Page Version


Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com
Copyright © 2001, Natural MicroSystems, Inc. All rights reserved.