(Page 13 of 15 in this chapter) Version

nfxSendFax

Description

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.

Prototype

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)
ctahd CTA context handle returned by ctaCreateContext.
send_queue_handle Handle for queue of documents to send, returned by nfxCreateQueue.
ptr_transmit_parms Pointer to NFX_TRANSMIT_PARMS (or NULL to use default values), as follows: typedef struct { DWORD size; DWORD modemtype; /* NFX_MODEM_TYPE_V17. NFX_MODEM_TYPE_V27, */ /* or NFX_MODEM_TYPE_V29 */ DWORD minrate; /* NFX_BIT_RATE_2400, NFX_BIT_RATE_4800, */ /* NFX_BIT_RATE_7200, or NFX_BIT_RATE_9600 */ 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 */ DWORD OTFmode; /* NFX_OTF_NEVER, NFX_OTF_ALWAYS, */ /* or NFX_OTF_ONLY_IF_FAIL */ DWORD useECM; /* NFX_YES or NFX_NO */ DWORD useCNG; /* NFX_YES or NFX_NO */ DWORD PRIenabled; /* NFX_YES or NFX_NO */ DWORD timeout; /* number of seconds to wait for receiver */ DWORD retrainaction; /* NFX_RTN_REPEAT_PAGE or NFX_RTN_NEXT_PAGE */ DWORD addheader; /* NFX_YES, NFX_NO or NFX_CUSTOM */ INT32 level; /* transmit level in tenths of dBm */ /* (-150 to -60) */ INT32 threshold; /* lowest lev. for receive, in tenths of dBm */ DWORD NSFlength; /* length of NSF field or 0 if none */ char SID[NFX_MAX_SID]; /* Subscriber ID string */ BYTE NSF[NFX_MAX_NSF]; /* default NSF for session */ char custom_header[NFX_MAX_HEADER]; /* customizable fax header */ } NFX_TRANSMIT_PARMS;
receive_queue_handle Handle of a queue to receive polled documents (NULL to disable polling).
ptr_receive_parms Pointer to NFX_RECEIVE_PARMS structure (or NULL to use default values), as follows: typedef struct { DWORD size; DWORD modemtype; /* NFX_MODEM_TYPE_V27 or NFX_MODEM_TYPE_V29. */ DWORD minrate; /* NFX_BIT_RATE_2400, NFX_BIT_RATE_4800, */ /* NFX_BIT_RATE_7200, or NFX_BIT_RATE_9600 */ DWORD resolution; /* NFX_RESOLUTION_HIGH, NFX_RESOLUTION_LOW, */ /* NFX_RESOLUTION_SUPER_HIGH */ DWORD encoding; /* NFX_ENCODE_1D, NFX_ENCODE_2D, */ /* NFX_ENCODE_MMR, or NFX_ENCODE_TIFF_S */ DWORD pollingenabled; /* NFX_YES or NFX_NO */ DWORD badlineaction; /* NFX_BAD_LINE_ACTION_NONE, */ /* NFX_BAD_LINE_ACTION_DROP, */ /* NFX_BAD_LINE_ACTION_REPT, or */ /* NFX_BAD_LINE_ACTION_TICK */ DWORD pagewidth; /* NFX_PAGE_WIDTH_A4. NFX_PAGE_WIDTH__B4, or */ /* NFX_PAGE_WIDTH_A3 */ DWORD OTFmode; /* NFX_OTF_NEVER, NFX_OTF_ALWAYS, or */ /* NFX_OTF_ONLY_IF_FAIL */ DWORD useECM; /* NFX_YES or NFX_NO */ DWORD lineerrors; /* % line errors before retrain negative */ INT32 level; /*xmit level in tenths of dBm (-150 to -60) */ INT32 threshold; /* lowest lev. for receive, in tenths of dBm */ DWORD NSFlength; /* Length of NSF field or 0 if none */ char SID[NFX_MAX_SID]; /* Subscriber ID string */ BYTE NSF[NFX_MAX_NSF]; /* default NSF for session */ } NFX_RECEIVE_PARMS;

Return Values

SUCCESS
CTAERR_BAD_ARGUMENTInvalid function argument passed.
CTAERR_FUNCTION_ACTIVE
A fax function is already active on the given CTA context handle.
CTAERR_INVALID_CTAHDThe specified CTA context handle is invalid.
CTAERR_INVALID_HANDLEThe specified document queue handle is invalid.
NFXERR_QUEUE_EMPTYThe specified document queue is empty.

Events

NFXEVN_CANNOT_OPEN_FILEThe specified file was not located by nfxSendFax. The fax operation continues with the next document in the queue.
NFXEVN_DOC_BEGINA start-of-message signal has been transmitted.
NFXEVN_DOC_ENDAn end-of-message signal has been transmitted. The value field for this event contains SUCCESS, or an error code.
NFXEVN_PAGE_BEGINA start-of-page signal has been transmitted.
NFXEVN_PAGE_ENDThe value field contains SUCCESS, or an error code. SUCCESS indicates that the receiving fax terminal has received the transmitted page, and has sent an acknowledgment to the transmitting fax terminal.
NFXEVN_PROCEDURE_INTERRUPTA Procedure Interrupt signal has been acknowledged by the called fax terminal.
NFXEVN_RECEIVE_STARTEDThe remote terminal has acknowledged a poll request.
NFXEVN_REMOTE_IDENTIFIEDThe remote terminal has been identified. You may now verify the remote SID and NSF by checking the session status.
NFXEVN_SEND_STARTEDThe fax session has started.
NFXEVN_SESSION_DONEThe fax session has completed. The value field for this event can contain any of the following reasons, or an error code:
CTA_REASON_FINISHEDThe fax function terminated normally.
CTA_REASON_RELEASEDThe fax session ended because the call was disconnected.
CTA_REASON_STOPPEDThe fax session was cancelled by a call to nfxStopSession.

Details

The specified CTA context must have an established call in the conversation state.
Events indicate progress and completion of the fax session. Receiving any of the events listed above indicates that the fax session status has been updated. The application can use the nfxGetSessionStatus function 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. Events must be processed within three seconds.
TIFF-F files with different image attributes on different pages can be sent using nfxSendFax.
Using Fax Headers
The addheader parameter in the NFX_TRANSMIT_PARMS structure indicates whether headers are added to the transmitted image data. There are three header options: Header Option Description NFX_NO Do not add a header. NFX_YES Add a header which 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.

The custom header can include page number and the date and time for each page, by using C style format strings: Format String Description %d date/time string %p page number %P total number of pages in this fax
For example, txparms.addheader = NFX_CUSTOM; strcpy (txparms.custom_header," Page %p of %P.\ This is a test of custom headers %d"); will create a fax header: 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 format strings. Even when the unformatted header is less than the limit, the formatted header may exceed 80 characters.
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.
If the environment variable NMSHEADERFONT is not defined, no header is added, regardless of the value of addheader. See the NaturalFax Installation Manual for details.
Using Fax Polling
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 will send its send queue before trying to poll the called fax terminal. If the send_queue_handle is NULL, nfxSendFax skips straight to trying to poll the called fax terminal. The event NFXEVN_RECEIVE_STARTED indicates that the remote fax terminal has responded to the poll request, and the calling fax terminal has begun to receive 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, which are 1D, LOW and A4, respectively.
Sending a Procedure Interrupt
It is possible to use nfxSendFax to transmit a Procedure Interrupt 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 will prompt a person to pick up the handset, which accepts the request and enables 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 field in NFX_TRANSMIT_PARMS to NFX_YES. A procedure interrupt request will be transmitted to the called fax terminal after the last document in the send queue has been 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: The PRIenabled field can be used only when polling is not enabled.

See Also

nfxGetSessionStatus, nfxReceiveFax

(Page 13 of 15 in this chapter) Version

tech_support@nmss.com

Copyright © 1999, Natural MicroSystems, Inc. All rights reserved.