Table of Contents

Index

NMS Glossary

Previous Page

Next Page

(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 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_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;

Return Values

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

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 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_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 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

Table of Contents

Index

NMS Glossary

Previous Page

Next Page

(Page 11 of 15 in this chapter) Version

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

Copyright © 2001, NMS Communications Corporation. All rights reserved.