Table of Contents

Index

NMS Glossary

Previous Page

Next Page

(Page 2 of 15 in this chapter) Version

nfxAnswerFaxPoll

Description

Provides a send queue of documents to send in response to a poll request from the remote fax terminal.

Prototype

DWORD nfxAnswerFaxPoll ( CTAHD ctahd,
NFX_QUEUE_HANDLE send_queue_handle,
NFX_TRANSMIT_PARMS *ptr_transmit_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 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, 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 level 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;

Return Values

SUCCESS
CTAERR_FUNCTION_NOT_ACTIVE
The receive fax operation is not running on the specified CTA context.
CTAERR_INVALID_CTAHD
The specified CTA context handle is invalid.
CTAERR_INVALID_HANDLE
The specified document queue handle is invalid.
NFXERR_CONVERSION_REQUIRED
Current fax operation requires image conversion, but on-the-fly conversion is disabled.
NFXERR_QUEUE_EMPTY
The specified document queue is empty.

Events

NFXEVN_CANNOT_OPEN_FILE
The specified file in the document queue was not located by nfxAnswerFaxPoll. The fax operation continues with the next document in the queue.
NFXEVN_DOC_BEGIN
Started transmission of a document.
NFXEVN_DOC_END
The transmitting fax terminal has indicated that the last page of the document has been sent. The value field contains SUCCESS, or an error code.
NFXEVN_PAGE_BEGIN
Started transmission of a page.
NFXEVN_PAGE_END
The 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_INTERRUPT
A Procedure Interrupt signal has been received from the called fax machine.
NFXEVN_SEND_STARTED
The polled fax session has started.
NFXEVN_SESSION_DONE
The fax session has completed. The value field in this event may 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 operation was cancelled by a call to nfxStopSession.

Details

When NFXEVN_POLLED is received, nfxStopSession may be called to refuse the poll request from the called fax terminal.
Note: nfxAnswerFaxPoll must be called within three seconds of receiving NFXEVN_POLLED, which is the event that indicates a poll request. If nfxAnswerPoll is not called within three seconds, the fax session times out and the application receives an NFXEVN_SESSION_DONE event.
Receiving any of the events listed above indicates that the fax session status has been updated. Use nfxGetSessionStatus to examine the current session status in more detail when any of the information events are received.
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 the custom header. Remember to 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.
If the environment variable NFXHEADERFONT is not defined, no header is added, regardless of the value of addheader. See Chapter 2 - Configuring NaturalFax for details.

See Also

nfxGetSessionStatus, nfxReceiveFax

Table of Contents

Index

NMS Glossary

Previous Page

Next Page

(Page 2 of 15 in this chapter) Version

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

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