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.
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 See NFX_RECEIVE_PARMS for complete field descriptions. |
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. |
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:
|
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:
|
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.