Warning:
Headers are mandated in certain countries, including those under FCC or DoC jurisdiction. Check telecommunications regulations in the target countries for your fax application.
Starts the transmit side of a T.30 protocol fax session, and sends all the documents in the send queue to the called fax terminal.
DWORD nfxSendFax ( CTAHD ctahd, NFX_QUEUE_HANDLE send_queue_handle, NFX_TRANSMIT_PARMS *ptr_transmit_parms, NFX_QUEUE_HANDLE receive_queue_handle, NFX_RECEIVE_PARMS *ptr_receive_parms)
Argument |
Description |
ctahd |
Context handle returned by ctaCreateContext. |
send_queue_handle |
Handle of a queue of documents to send, returned by nfxCreateQueue. |
ptr_transmit_parms |
Pointer to an NFX_TRANSMIT_PARMS structure (or NULL to use default values), as follows: typedef struct See NFX_TRANSMIT_PARMS for complete field descriptions. |
receive_queue_handle |
Handle of a queue to receive polled documents (NULL to disable polling). |
ptr_receive_parms |
Pointer to an NFX_RECEIVE_PARMS structure (or 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 handle. |
CTAERR_INVALID_CTAHD |
The specified context handle is invalid. |
CTAERR_INVALID_HANDLE |
The specified document queue handle is invalid. |
NFXERR_QUEUE_EMPTY |
The specified document queue is empty. |
Event |
Description |
NFXEVN_CANNOT_OPEN_FILE |
nfxSendFax could not find the specified file. The fax operation continues with the next document in the queue. |
NFXEVN_DOC_BEGIN |
A start-of-message signal was transmitted. |
NFXEVN_DOC_END |
An end-of-message signal was transmitted. The value field for this event contains SUCCESS or an error code. |
NFXEVN_PAGE_BEGIN |
A start-of-page signal was transmitted. |
NFXEVN_PAGE_END |
The value field contains SUCCESS or an error code. SUCCESS indicates that the receiving fax terminal received the transmitted page, and sent an acknowledgment to the transmitting fax terminal. |
NFXEVN_PROCEDURE_INTERRUPT |
The called fax terminal acknowledged a procedure interrupt signal. |
NFXEVN_RECEIVE_STARTED |
The remote terminal acknowledged a poll request. |
NFXEVN_REMOTE_IDENTIFIED |
The remote terminal was identified. You can now verify the remote SID and NSF by checking the session status. |
NFXEVN_SEND_STARTED |
The fax session started. |
NFXEVN_SESSION_DONE |
The fax session completed. The value field for this event can contain any of the following reasons or an error code:
|
The specified context must have an established call in the conversation state.
Events indicate the progress and completion of the fax session. The previously listed events indicate that the fax session status was updated. The application can use nfxGetSessionStatus to examine the current session status in more detail when any of the information events is received.
Note: The application must continue processing events during an active fax session. If file I/O intensive operations interfere with the handling of events, the fax session could time out. The application should process events within three seconds.
TIFF-F files with different image attributes on different pages can be sent using nfxSendFax.
nfxSendFax uses the NFX_TRANSMIT_PARMS and NFX_RECEIVE_PARMS structures to control fax transmission or fax reception behavior. It sets context values first using NFX_RECEIVE_PARMS and then with NFX_TRANSMIT_PARMS. Some common context values can be set using both parameters (for example, SID-Subscriber Identification). NaturalFax sets these common values with the values specified in NFX_TRANSMIT_PARMS by overwriting values set using NFX_RECEIVE_PARMS.
Use the addheader parameter in the NFX_TRANSMIT_PARMS structure to add headers to the transmitted image data:
Header option |
Description |
|---|---|
NFX_NO |
Do not add a header. |
NFX_YES |
Add a header that is a fixed string in the following format: FROM transmit_SID Date Time Page N of M |
NFX_CUSTOM |
Add a customized header of up to 80 ASCII characters. |
Use C style format strings to include the page number, the date, and the time in the custom header:
Format string |
Description |
|---|---|
%d |
Date/time string. |
%p |
Page number. |
%P |
Total number of pages in this fax. |
%y |
Current page number in fax session. |
%Y |
Total number of pages in all documents in queue. |
For example, the following code:
txparms.addheader = NFX_CUSTOM;
strcpy (txparms.custom_header," Page %p of %P.\
This is a test of custom headers %d");
Creates a fax header similar to the following example:
Page 1 of 5. This is a test of custom headers Fri Apr29
12:25:12 1999
Do not exceed the 80 character limit when using the custom header. Include expanded format strings (%d, %p, %P, %y, %Y) in the 80 character limit.
By default, addheader is set to NFX_YES, and a header is added to the document being transmitted.
Warning: |
Headers are mandated in certain countries, including those under FCC or DoC jurisdiction. Check telecommunications regulations in the target countries for your fax application. |
You must define the environment variable NFXHEADERFONT to add a header. Refer to Setting environment variables in UNIX and Setting environment variables in Windows for more information.
In addition to sending documents, nfxSendFax supports polling. The fax polling operation allows the called fax terminal to respond by sending a queue of documents to the calling fax terminal. The calling fax terminal sends its send queue before trying to poll the called fax terminal. If the send_queue_handle is NULL, nfxSendFax tries to poll the called fax terminal. The event NFXEVN_RECEIVE_STARTED indicates that the remote fax terminal responded to the poll request and the calling fax terminal began receiving the polled documents.
Note: Either the send_queue_handle or the receive_queue_handle can be NULL, but not both.
Specifying NFX_ENCODE_TIFF_S in the NFX_RECEIVE_PARMS structure overrides the encoding, resolution, and pagewidth values to the values for TIFF-S. The new values are 1D, LOW and A4, respectively.
Use nfxSendFax to transmit a procedure interrupt (PRI) signal to the called terminal after completing the transmission of all documents in the send queue. A PRI signal ends an nfxSendFax operation and prevents the receiving fax terminal from hanging up the call. The receiving fax terminal prompts a person to pick up the handset, accepting the request and enabling the application to perform voice functions (such as playing a voice prompt, or recording a message). If no one picks up the handset or the receiving fax terminal does not respond to the PRI, the transmitting fax terminal completes operations normally.
To send a procedure interrupt, the application must set the PRIenabled parameter in NFX_TRANSMIT_PARMS to NFX_YES. A procedure interrupt request is transmitted to the called fax terminal after the last document in the send queue is transmitted. The default setting for PRIenabled is NFX_NO. When the called terminal acknowledges a procedure interrupt request, the event NFXEVN_PROCEDURE_INTERRUPT is sent to the application, followed by an NFXEVN_SESSION_DONE event. Voice functions may be performed after receiving the done event.
Note: Disable polling before using the procedure interrupt feature.
Refer to Transmitting faxes for more information. Refer to Polling the called fax terminal for more information about fax polling.