Table of Contents Index NMS Glossary Previous Page Next Page (Page 14 of 15 in this chapter) Version

faxSendFax

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

LONG faxSendFax ( HFAX hFax,
FAX_QUEUE_HANDLE hSendQueue,
FAX_TRANSMIT_PARMS *ptrTransmitParms,
 FAX_QUEUE_HANDLE hReceiveQueue,
FAX_RECEIVE_PARMS *ptrReceiveParms)

hFax Handle returned by TAPI.

hSendQueue Handle for queue of documents to send, returned by faxCreateQueue.

ptrTransmitParms Pointer to FAX_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,                */
     /* 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 or NFX_NO            */
 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            */
} FAX_TRANSMIT_PARMS;
hReceiveQueue Handle of a queue to receive polled documents (NULL to disable polling).

ptrReceiveParms Pointer to FAX_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, or            */
     /* NFX_ENCODE_MMR            */
 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            */
} FAX_RECEIVE_PARMS;

Return Values

Events

Details

The specified fax device 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. When any of the information events is received, the application can use faxGetSessionStatus to examine the current session status in more detail.

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.

Using Fax Polling

In addition to sending documents, faxSendFax 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 hsendqueue is NULL, faxSendFax immediately starts trying to poll the called fax terminal. The event FAXMSG_SEND_BEGIN 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 hsendqueue or hreceivequeue can be NULL, but not both.

Sending a Procedure Interrupt (PRI)

It is possible to use faxSendFax 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 faxSendFax 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 FAX_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 FAXMSG_INTERRUPTED is sent to the application, followed by a FAXMSG_SESSION_DONE event. Voice functions can be performed after receiving the done event.

Note: The PRIenabled field can be used only when polling is not enabled.

For more information, refer to Section 7.6, Transmitting and Receiving Faxes.

See Also

faxGetSessionStatus, faxReceiveFax


Table of Contents Index NMS Glossary Previous Page Next Page (Page 14 of 15 in this chapter) Version

Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com
Copyright © 2001, Natural MicroSystems, Inc. All rights reserved.