NMS nfxReceiveFax

Home > Function reference > nfxReceiveFax

nfxReceiveFax

Starts the receive side of a T.30 protocol fax session and stores all received document files in the specified receive queue. These files must not exist before you use this function.

Prototype

DWORD nfxReceiveFax ( CTAHD ctahd, NFX_QUEUE_HANDLE receive_queue_handle, NFX_RECEIVE_PARMS *ptr_receive_parms)

Argument

Description

ctahd

Context handle returned by ctaCreateContext.

receive_queue_handle

Handle for queue of documents to receive, returned by nfxCreateQueue.

ptr_receive_parms

Pointer to an NFX_RECEIVE_PARMS structure (NULL to use default values), as follows:

typedef struct

{

DWORD size;

DWORD modemtype;     /* NFX_MODEM_TYPE_V17, NFX_MODEM_TYPE_V27,*/

/* or NFX_MODEM_TYPE_V29                  */

DWORD minrate;       /* NFX_BIT_RATE_2400, NFX_BIT_RATE_4800,  */

/* NFX_BIT_RATE_7200, NFX_BIT_RATE_9600,  */

/* NFX_BIT_RATE_12000, NFX_BIT_RATE_14400 */

DWORD resolution;    /* NFX_RESOLUTION_HIGH,                   */

/* NFX_RESOLUTION_LOW, or                 */

/* NFX_RESOLUTION_SUPER_HIGH              */

DWORD encoding;      /* NFX_ENCODE_1D, NFX_ENCODE_2D,          */

/* NFX_ENCODE_MMR, or NFX_ENCODE_TIFF_S   */

DWORD pollingenabled;/* NFX_YES or NFX_NO                      */

DWORD badlineaction; /* NFX_BAD_LINE_ACTION_NONE,              */

/* NFX_BAD_LINE_ACTION_DROP,              */

/* NFX_BAD_LINE_ACTION_REPT, or           */

/* NFX_BAD_LINE_ACTION_TICK               */

DWORD pagewidth;     /* NFX_PAGE_WIDTH_A4, NFX_PAGE_WIDTH__B4, */

/* or NFX_PAGE_WIDTH_A3                   */

DWORD OTFmode;       /* NFX_OTF_NEVER, NFX_OTF_ALWAYS, or      */

/* NFX_OTF_ONLY_IF_FAIL                   */

DWORD useECM;        /* NFX_YES or NFX_NO                      */

DWORD lineerrors;    /* % line errors before retrain negative  */

INT32 level;         /* Tx level in tenths of dBm(-150 to -60) */

INT32 threshold;     /* Lowest lev. for receive, tenths of dBm */

DWORD NSFlength;     /* Length of NSF field or 0 if none       */

char SID[NFX_MAX_SID];/* Subscriber ID string                  */

BYTE NSF[NFX_MAX_NSF];/* Default NSF for session               */

char SUB[NFX_MAX_SUB];/* Sub-Address string                    */

DWORD useSUBADD;      /* NFX_YES or NFX_NO                     */

}NFX_RECEIVE_PARMS;

See NFX_RECEIVE_PARMS for complete field descriptions.

Return values

Return value

Description

SUCCESS

CTAERR_BAD_ARGUMENT

A function argument is invalid.

CTAERR_FUNCTION_ACTIVE

A fax function is already active on the given context.

CTAERR_INVALID_CTAHD

The specified context handle is invalid.

CTAERR_INVALID_HANDLE

The specified document queue handle is invalid.

Events

Event

Description

NFXEVN_CANNOT_OPEN_FILE

nfxReceiveFax could not create the specified file. The fax operation continues with the next document in the queue.

NFXEVN_DOC_BEGIN

A start-of-message signal was received.

NFXEVN_DOC_END

An end-of-message signal was received. The event value field can contain any of the following values or an error code:

NFX_T30_EOM

An end-of-message signal was received from the called fax terminal (more documents to follow). If no more documents are in the receive queue, NaturalFax puts any additional sent documents into the last document enqueued. This may result in a TIFF-F file with different attributes on some pages.

NFX_T30_EOP

An end-of-procedure signal was received from the called fax terminal (no more documents to follow).

NFXEVN_PAGE_BEGIN

A start-of-page signal was received.

NFXEVN_PAGE_END

The value field contains SUCCESS or an error code. SUCCESS indicates that the receiving fax terminal received an end-of-page signal, and sent an acknowledgment to the transmitting fax terminal.

NFXEVN_POLLED

The calling fax machine polled the application.

NFXEVN_PROCEDURE_INTERRUPT

A procedure interrupt was received from the called fax machine.

NFXEVN_RECEIVE_STARTED

Confirms that the fax session has started.

NFXEVN_REMOTE_IDENTIFIED

The remote terminal was identified. You can now verify the remote SID and NSF by checking the session status.

NFXEVN_SESSION_DONE

The fax session completed with one of the following terminating reasons, or an error code:

CTA_REASON_FINISHED

The fax session terminated normally.

CTA_REASON_RELEASED

The fax session ended because the call was disconnected.

CTA_REASON_STOPPED

The fax session was cancelled by a call to nfxStopSession.

Details

Using an encoding value of NFX_ENCODE_TIFF_S forces the values for encoding, resolution, and page width to be overridden. The new values for the TIFF-S are 1D, LOW and A4, respectively.

NFXEVN_nnn events indicate the progress of the fax session and the completion of the fax session.

Note: You must continue processing events during an active fax session. Make sure that file I/O intensive operations do not interfere with the handling of events and cause the fax session to time out. The application should process events within three seconds.

Some computer-based fax programs can send documents with different image attributes in a single fax session. For example, a PC-based fax transmitter can send a cover page at low resolution and send the rest of the document at high resolution. NaturalFax handles this situation differently depending on the number of documents enqueued. If the application enqueued multiple documents, separate documents are created for each change in resolution. If only one document remains in the queue, the pages with different resolution will be added to the last document in the queue.

Receipt of any of the previously listed events indicates that the fax session status was updated. Use nfxGetSessionStatus to examine the current session status in more detail.

After a fax session completes, the application releases the call and tears down or resets any document queues. NaturalFax sends a DCN (disconnect) frame at the end of a fax session to signal the remote fax terminal to disconnect. The application can use functions from the NCC service to release the call after a completed fax session.

A normal fax session ends with the transmitter sending the DCN (disconnect) frame, signaling the remote fax terminal to disconnect. Some fax terminals may disconnect the call before they receive or transmit the DCN frame. Under these conditions, the NaturalFax application may receive an NCCEVN_CALL_DISCONNECTED event before it receives the NFXEVN_SESSION_DONE event.

The application should wait for the NFXEVN_SESSION_DONE event, and then release the call as usual. The NFXEVN_SESSION_DONE event will contain a reason code of CTA_REASON_RELEASED or CTA_REASON_FINISHED.

To enable polling, make sure that the called fax terminal has the pollingenabled parameter in NFX_RECEIVE_PARMS set to NFX_YES. If polling is enabled and the sender subsequently requests polling, the event NFXEVN_POLLED is received. Use nfxAnswerFaxPoll to continue the fax operation.

For more information, refer to Receiving faxes.

See also

nfxAnswerFaxPoll, nfxSendFax