(Page 14 of 19 in this chapter)

nfxReceiveFax

Description

This function starts the receive side of T.30 protocol session and then places all received documents into the receive queue.

Prototype

DWORD nfxReceiveFax (CTAHD ctahd,
NFX_QUEUE_HANDLE receive_queue_handle,
NFX_RECEIVE_PARMS *ptr_receive_parms)
ctahd Handle returned by ctaCreateContext
receive_queue_handle Queue to receive documents
ptr_receive_parms Pointer to parameters for receiving fax documents, or NULL to use default parameters; the NFX_RECEIVE_PARMS structure is as follows: typedef struct { DWORD size; /* size of this structure */ DWORD modemtype; /* NFX_MODEM_TYPE_V27 */ /* NFX_MODEM_TYPE_V29.*/ /* Advertised capabilities */ /* for fax receiver */ 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 */ /* NFX_RESOLUTION_SUPER_HIGH */ DWORD encoding; /* NFX_ENCODE_1D or NFX_ENCODE_2D */ DWORD pollingenabled; /* NFX_YES or NFX_NO */ DWORD badlineaction; /* NFX_BAD_LINE_ACTION_NONE */ /* NFX_BAD_LINE_ACTION_DROP */ /* NFX_BAD_LINE_ACTION_REPT */ /* NFX_BAD_LINE_ACTION_TICK */ DWORD pagewidth; /* NFX_PAGE_WIDTH_A4 */ /* NFX_PAGE_WIDTH_B4 */ /* NFX_PAGE_WIDTH_A3 */ DWORD OTFmode; /* NFX_OTF_NEVER, */ /* NFX_OTF_ALWAYS, */ /* NFX_OTF_ONLY_IF_FAIL */ DWORD reserved; DWORD lineerrors; /* % line errors before */ /* retrain negative */ DWORD NSFlength; /* Length of NSF field or */ /* 0 if none */ char SID[NFX_MAX_SID]; /* Subscriber ID string */ BYTE NSF[NFX_MAX_USER_NSF]; /* default NSF for session */ } NFX_RECEIVE_PARMS;

Return Values

SUCCESS
The function completed successfully.
CTAERR_BAD_ARGUMENTInvalid function argument passed.
CTAERR_FUNCTION_ACTIVEA fax function is already active on the given CTA context handle.
CTAERR_INVALID_CTAHDThe specified CTA context handle is invalid.
CTAERR_INVALID_HANDLEThe specified document queue handle is invalid.
NFXERR_NO_MORE_LICENSESThere are no available fax license units.

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_END An end-of-message signal has been received. The event value field for this event may contain any of the following values:
NFX_T30_EOM An end-of-message signal was received from the
called fax terminal (more documents to follow).
NFX_T30_EOP An end-of-procedure signal was received from
the called fax terminal (no more documents to
follow);
NFX_T30_DTC A Digital Transmit Command was received from
the called fax terminal (the calling fax terminal is
being polled);
NFX_T30_DCN A Disconnect signal (a request to hang up the
phone) was received from the called fax
terminal;
NFX_T30_TIMEOUT No command was received within the allocated
time.
NFXEVN_PAGE_BEGINA start-of-page signal has been received.
NFXEVN_PAGE_ENDAn end-of-page signal has been received.
NFXEVN_POLLED
The calling fax machine has polled NaturalFax.
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 conditions or an error code:
CTA_REASON_FINISHED The fax session terminated normally.
CTA_REASON_RELEASED The fax session ended because the call was
disconnected.
CTAERR_FUNCTION_ACTIVE Function is already running on this CTA context.
CTAERR_FUNCTION_NOT_AVAIL The NaturalFax DSP overlay has not been
downloaded to the board.
CTAERR_OUT_OF_RESOURCES A NaturalFax DSP function could not be started.
NFX_REASON_STOPPED The fax session was cancelled by a call to
nfxStopSession.
NFXERR_BUFFER_OVERRUN On receive, buffers to receive the incoming
image data have not been provided in time.
NFXERR_CONVERSION_REQUIRED
The fax session failed to receive or transmit
because a conversion is required and
on-the-fly conversion has been disabled
(otfmode in the receive or transmit parameters
is set to NFX_OTF_NEVER).
NFXERR_NEGOTIATION_FAILED Negotiations between NaturalFax and the remote
fax terminal failed.
NFXERR_NO_MORE_DOCUMENTS The fax session ended because there were no
more receive files in the receive queue.
NFXERR_RATE_TOO_LOW The receiving or transmitting fax terminal is
attempting to receive or transmit at a rate
lower than the minrate.

Details

If a fax license unit has not been allocated to this CTA context, this function will attempt to allocate one. NFXEVN_nnn events indicate progress of the fax session and completion of the fax session. Note: Keep in mind that 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.
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.
Receiving any of the events above indicates that the fax session status has been updated. Use nfxGetSessionStatus to examine the current session status in more detail.

See Also

nfxAnswerFaxPoll, nfxGetLicenseStatus, nfxSendFax

(Page 14 of 19 in this chapter)

tech_support@nmss.com

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