(Page 6 of 13 in this chapter)
2.5 Working with Document Queues
- NaturalFax functions manipulate document queues. NaturalFax functions can operate only on document queues, not on individual files. You must use a document queue for any fax operation, even when transmitting or receiving a single document.
- A document queue contains a list of one or more document files (the document files must be in TIFF-F format). NaturalFax has two kinds of document queues: send queues and receive queues. Use send queues to transmit documents, and receive queues to receive documents.
- Each document queue is linked to a specific CTA context. Each CTA context may have multiple send and receive queues.
2.5.1 Building a Document Queue
- To create a new document queue, call nfxCreateQueue. It returns a queue handle upon successful completion, which the application uses to manipulate the queue. When you call nfxCreateQueue, one of its arguments determines which kind of queue is created, send or receive.
- After creating a send queue, use nfxEnqueueDoc to add document files to the queue. Only files that already exist may be added to a send queue. The same file can be placed in multiple send queues simultaneously.
- NaturalFax sends each enqueued file as a separate message. For example, if you enqueue a three page file and a five page file, the remote fax machine will receive a three page message followed by a five page message. NaturalFax will not send both files in a single eight page message.
Note: NaturalFax does not modify or delete any document files when sending. Only received document files are modified.
- Each document to be received must have an entry in the receive queue. When adding files using nfxEnqueueDoc, the receive name may not be NULL, and the file must not already exist.
- NaturalFax receives each multiple page message into a single file. The next document in the queue is used only if the remote fax machine sends a new message. This is common only in computer-based fax applications.
2.5.2 Tearing Down or Resetting a Document Queue
- Once a document queue has been transmitted or received, it can be either reset or destroyed using nfxResetQueue or nfxDestroyQueue, respectively.
- Each page in a document is flagged as "sent" when it has been successfully transmitted. Resetting a send queue resets the flags for each page of each of its component documents to "unsent."
- The application developer is free to choose how to use document queues. One scenario is to use one document queue per fax operation. For a fax broadcast application, you can use one 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.
Note: Once a receive queue is changed to a send queue, it cannot be changed back to a receive queue.
(Page 6 of 13 in this chapter)
tech_support@nmss.com
Copyright © 1997, Natural MicroSystems, Inc. All rights
reserved.