Allocates a document entry in a document queue.
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 See NFX_DOC_PARMS for complete field descriptions. |
ptr_doc_number |
Pointer to a location to receive a valid document number. |
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. |
None.
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.