Table of Contents

Index

NMS Glossary

Previous Page

Next Page

(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 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, NFX_BIT_RATE_9600, */ /* NFX_BIT_RATE_12000, NFX_BIT_RATE_14400 */ 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 */ char SUB[NFX_MAX_SUB]; /* Sub-Address string */ DWORD useSUBADD;/* NFX_YES or NFX_NO */ DWORD txrate; /* NFX_BIT_RATE_2400, NFX_BIT_RATE_4800, */ /*NFX_BIT_RATE_7200, NFX_BIT_RATE_9600, */ /*NFX_BIT_RATE_12000, NFX_BIT_RATE_14400 */ DWORD ForceRate;/*NFX_YES or NFX_NO */ } 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_V17, NFX_MODEM_TYPE_V27, */ /* or NFX_MODEM_TYPE_V29 */ DWORD minrate; /* NFX_BIT_RATE_2400, NFX_BIT_RATE_4800, */ /* NFX_BIT_RATE_7200, NFX_BIT_RATE_9600, */ /* NFX_BIT_RATE_12000, NFX_BIT_RATE_14400 */ DWORD resolution;/* NFX_RESOLUTION_HIGH, NFX_RESOLUTION_LOW, */ /* or 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 */ char SUB[NFX_MAX_SUB];/* Sub-Address string */ DWORD useSUBADD;/* NFX_YES or NFX_NO */ } NFX_RECEIVE_PARMS;

Return Values

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.

Events

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:
CTA_REASON_FINISHED
The fax function terminated normally.
CTA_REASON_RELEASED
The fax session ended because the call was disconnected.
CTA_REASON_STOPPED
The fax session was cancelled by a call to nfxStopSession.

Details

The specified context must have an established call in the conversation state.
Events indicate progress and completion of the fax session. Receiving any of the events previously listed indicates that the fax session status was 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
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 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.
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
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 the custom header. Include expanded format strings (%d, %p, %P) 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. See Section 2.2, Setting Environment Variables 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 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, which are 1D, LOW and A4, respectively.
Sending a Procedure Interrupt
You can 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 field 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.

See Also

nfxGetSessionStatus, nfxReceiveFax

Table of Contents

Index

NMS Glossary

Previous Page

Next Page

(Page 13 of 15 in this chapter) Version

Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com

Copyright © 2001, NMS Communications Corporation. All rights reserved.