nfxEnqueueDoc

Allocates a document entry in a document queue.

Prototype

DWORD nfxEnqueueDoc ( CTAHD ctahd, NFX_QUEUE_HANDLE queue_handle, char *file_name, NFX_DOC_PARMS *ptr_doc_parms, DWORD *ptr_doc_number)

Argument

Description

ctahd

Context handle returned by ctaCreateContext.

queue_handle

Identifies a valid queue to receive the new document.

file_name

Pointer to an existing file to send or a file to create.

ptr_doc_parms

Pointer to an NFX_DOC_PARMS structure (or NULL to use default values), as follows:

typedef struct 
{
  DWORD size;         /* Size of this structure                 */
  DWORD resolution;   /* NFX_RESOLUTION_HIGH, NFX_RESOLUTION_LOW*/
                      /* or NFX_RESOLUTION_SUPER_HIGH           */
  DWORD encoding;     /* NFX_ENCODE_1D, NFX_ENCODE_2D or        */
                      /* NFX_ENCODE_MMR                         */
  DWORD pagewidth;    /* NFX_PAGE_WIDTH_A4, NFX_PAGE_WIDTH_B4 or*/
                      /* NFX_PAGE_WIDTH_A3                      */
} NFX_DOC_PARMS;

See NFX_DOC_PARMS for complete field descriptions.

ptr_doc_number

Pointer to a location to receive a valid document number.

Return values

Return value

Description

SUCCESS

 

CTAERR_BAD_ARGUMENT

Invalid function argument passed.

CTAERR_FILE_EXISTS

Attempted to enqueue an existing file to a receive queue. No queue entry is made.

CTAERR_FILE_NOT_FOUND

Attempted to enqueue a nonexistent file to the send queue. No queue entry is made.

CTAERR_INVALID_CTAHD

The specified context handle is invalid.

CTAERR_INVALID_HANDLE

The specified document queue handle is invalid.

NFXERR_BAD_FILE_FORMAT

The specified file is not in TIFF-F or TIFF-S format.

NFXERR_QUEUE_TOO_LATE

Attempted to enqueue a file in an active transmit or receive queue too late in the fax session. No queue entry is made.

Events

None.

Details

Use nfxEnqueueDoc to build transmit queues or receive queues of documents before calling nfxSendFax, nfxReceiveFax, or nfxAnswerFaxPoll. You can also use nfxEnqueueDoc to add documents to transmit queues or receive queues while a send or receive operation is under way.

The file_name is passed as a separate argument and differs with each call to nfxEnqueueDoc. The file specified by file_name enqueued to a transmit queue must exist in the correct format for transmission (TIFF-F or TIFF-S). The file specified by file_name enqueued to a receive queue must not exist when it is enqueued to the receive queue.

The document number is placed in ptr_doc_number and identifies the position of the document in the queue. The document number and the queue handle are used for subsequent calls to nfxGetDocStatus.

The parameter values in NFX_DOC_PARMS can be changed with each call to nfxEnqueueDoc, but most of them are likely to be set once and used thereafter without changes.

Refer to Using document queues for more information.

See also

nfxCreateQueue, nfxDestroyQueue