(Page 11 of 15 in this chapter) Version

nfxReceiveFax

Description

Starts the receive side of T.30 protocol fax session and stores all received documents in the nonexistent files in the specified receive queue.

Prototype

DWORD nfxReceiveFax ( CTAHD ctahd,
NFX_QUEUE_HANDLE receive_queue_handle,
NFX_RECEIVE_PARMS *ptr_receive_parms)
ctahd CTA context handle returned by ctaCreateContext.
receive_queue_handle Handle for queue of documents to receive, returned by nfxCreateQueue.
ptr_receive_parms Pointer to NFX_RECEIVE_PARMS structure (NULL to use default values), as follows: typedef struct { DWORD size; DWORD modemtype;/* 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 */ 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 */ } NFX_RECEIVE_PARMS;

Return Values

SUCCESS
CTAERR_BAD_ARGUMENTInvalid function argument passed.
CTAERR_FUNCTION_ACTIVEA fax function is already active on the given CTA context.
CTAERR_INVALID_CTAHDThe specified CTA context handle is invalid.
CTAERR_INVALID_HANDLEThe specified document queue handle is invalid.

Events

NFXEVN_CANNOT_OPEN_FILEThe specified file could not be created by nfxReceiveFax and the fax operation continues with the next document in the queue.
NFXEVN_DOC_BEGINA start-of-message signal has been received.
NFXEVN_DOC_ENDAn end-of-message signal has been received. The event value field can contain any of the following values, or an error code:
NFX_T30_EOMAn 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 documents sent by the transmitting fax into the last document enqueued. This may result in a TIFF-F file with different attributes on some pages.
NFX_T30_EOPAn end-of-procedure signal was received from the called fax terminal (no more documents to follow).
NFXEVN_PAGE_BEGINA start-of-page signal has been received.
NFXEVN_PAGE_ENDThe value field contains SUCCESS, or an error code. SUCCESS indicates that the receiving fax terminal has received an end-of-page signal, and has sent an acknowledgment to the transmitting fax terminal.
NFXEVN_POLLED
The calling fax machine has polled the application.
NFXEVN_PROCEDURE_INTERRUPTA Procedure Interrupt has been received from the called fax machine.
NFXEVN_RECEIVE_STARTEDConfirms that the fax session has started.
NFXEVN_REMOTE_IDENTIFIEDThe remote terminal has been identified. You may now verify the remote SID and NSF by checking the session status.
NFXEVN_SESSION_DONEThe fax session has completed with one of the following terminating reasons, or an error code:
CTA_REASON_FINISHEDThe fax session terminated normally.
CTA_REASON_RELEASEDThe fax session ended because the call was disconnected.
CTA_REASON_STOPPEDThe fax session was cancelled by a call to nfxStopSession.

Details

Using a value of NFX_ENCODE_TIFF_S encoding forces the values for encoding, resolution and page width to be overridden to the TIFF-S values of 1D, LOW and A4, respectively.
NFXEVN_nnn events indicate progress of the fax session and 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. Events should be processed within three seconds.
Some computer-based fax programs may send documents with different image attributes in a single fax session. For example, a PC based fax transmitter may 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, seperate documents will be 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.
Receiving any of the previously listed events indicates that the fax session status has been updated. Use nfxGetSessionStatus to examine the current session status in more detail.
After a fax session has completed, the application must release the call and tear down or reset any document queues. NaturalFax sends a DCN (disconnect) frame at the end of a fax session, which signals the remote fax terminal to disconnect. The application can use functions from the ADI service to release the call after a completed fax session.
Some fax terminals may disconnect the call before they receive the DCN frame. Under these conditions, the NaturalFax application may receive an ADIEVN_CALL_DISCONNECTED event before it receives the NFXEVN_SESSION_DONE event. The application should release the call as usual. The NFXEVN_SESSION_DONE event will contain a reason of CTA_REASON_RELEASED or CTA_REASON_FINISHED.
To enable polling, make sure that the called fax terminal has pollingenabled 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.

See Also

nfxAnswerFaxPoll, nfxSendFax

(Page 11 of 15 in this chapter) Version

tech_support@nmss.com

Copyright © 1999, Natural MicroSystems, Inc. All rights reserved.