This topic presents the following information:
Transmitting or receiving document queues constitutes an active fax session. A fax session can include the polling of a remote fax terminal or responding to a poll request from a remote fax terminal.
After a document queue is transmitted or received, the queue can be reset. Each page in a document in a send queue is flagged as sent when it is successfully transmitted.
Note: You must continue processing events during an active fax session. Make sure that file I/O intensive operations, such as TIFF-F or TIFF-S format verification, do not interfere with the handling of events and cause the fax session to time out. Events must be processed within three seconds.
Use nfxSendFax to transmit all the documents in a specified send queue. You can track which documents are successfully sent by monitoring events during transmission.
NaturalFax typically ends a fax session by transmitting a DCN (disconnect) frame to the remote fax terminal and sending an NFXEVN_SESSION_DONE event to the application. The application can release the call as soon as it receives the NFXEVN_SESSION_DONE event; it does not need to wait for a response from the remote fax terminal. The application must use NCC service functions to release the call after the DONE event is received.
You can also transmit a procedure interrupt request (PRI) frame to the receiving fax terminal after completing a send operation. PRI requests that the receiving fax terminal permit an operator action such as picking up the handset for voice. Refer to nfxSendFax for information about sending PRI requests.
An application must create a receive queue before it can call nfxReceiveFax and receive a queue of documents. The receive queue can not be empty; it must contain one or more file names of nonexistent files. The files must not exist when the receive queue is created or when nfxReceiveFax is invoked.
NaturalFax stores each fax document received in a separate file, using the list of file names specified by the NaturalFax receive queue. If the sending fax terminal indicates that it is starting a new document and NaturalFax has already used all available empty file names in the receive queue, the received document is appended to the last file in the receive queue. This could result in a TIFF file with unused image attributes.
The fax polling operation enables the called fax terminal to send a queue of documents to the calling fax terminal. A caller can send any number of documents in a single queue and then poll the remote fax terminal. All documents in the send queue are transmitted before the called fax terminal can be polled.
To request polling, call nfxSendFax with a non-NULL receive_queue_handle argument. Since the calling fax terminal will be receiving faxes, it must have a receive queue ready to accept the received document files.
The receive_queue_handle argument controls polling. A call to nfxSendFax with a NULL send_queue_handle and a non-NULL receive_queue_handle initiates a fax session that polls the called fax terminal without transmitting any documents first.
The following illustration shows the exchanges between the application, the APIs, the hardware, and the remote fax terminal as an application transmits a fax, then receives the fax for which it sent a poll request:
To enable polling from the receiving fax terminal, set pollingenabled to NFX_YES in NFX_RECEIVE_PARMS. The application is notified of a poll request when it receives an NFXEVN_POLLED event. Even with polling enabled, the application must decide if it will answer a poll request, and prepare a send queue or use an already-prepared send queue of documents.
An application uses nfxAnswerFaxPoll to transmit its send queue in response to a poll request, rather than nfxSendFax. nfxAnswerFaxPoll must be called within three seconds of the receipt of NFXEVN_POLLED event. If the application does not respond to the poll within three seconds, it receives NFXEVN_SESSION_DONE. Alternatively, you can call nfxStopSession to refuse the poll request from the remote fax terminal.
If polling is not enabled, the NFXEVN_POLLED event is not generated even if a poll request is made by the remote transmitter. The fax session then terminates.
The following illustration shows NaturalFax receiving a document, and then transmitting a document in response to a poll:
After a document queue is transmitted or received, use nfxResetQueue to reset it.
Each page in a document is flagged as sent when it is successfully transmitted. Resetting a send queue resets the flags for each page of each of its component documents to unsent.
Use one document queue per fax operation. For a fax broadcast application, use one send queue per broadcast session, and continue to reset the queue and resend its contents multiple times.
Resetting a receive queue changes the queue type to a send queue with all the pages flagged as unsent. This use is typical of a fax store-and-forward application. Once a receive queue is changed to a send queue, it cannot be changed back to a receive queue.