nfxAnswerFaxPoll

Provides a 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)

Argument

Description

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 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, 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 */
  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;

See NFX_TRANSMIT_PARMS for complete field descriptions.

Return values

Return value

Description

SUCCESS

 

CTAERR_FUNCTION_NOT_ACTIVE

The receive fax operation is not running on the specified context.

CTAERR_INVALID_CTAHD

The specified 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

Event

Description

NFXEVN_CANNOT_OPEN_FILE

nfxAnswerFaxPoll could not find the specified file in the document queue. The fax operation continues with the next document in the queue.

NFXEVN_DOC_BEGIN

Document transmission started.

NFXEVN_DOC_END

The transmitting fax terminal indicated that the last page of the document was sent. The value field contains SUCCESS or an error code.

NFXEVN_PAGE_BEGIN

Page transmission started.

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 machine sent a procedure interrupt signal.

NFXEVN_SEND_STARTED

The polled fax session started.

NFXEVN_SESSION_DONE

The fax session completed. The value field in this event may contain any of the following reason codes 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, the application can call nfxStopSession to refuse the poll request from the called fax terminal.

Note: If nfxAnswerPoll is not called within three seconds of receiving NFXEVN_POLLED, the fax session times out and the application receives an NFXEVN_SESSION_DONE event.

Receiving any of these events indicates that the fax session status was updated. Use nfxGetSessionStatus to examine the current session status in more detail when any of the information events are received.

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 for each page:

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 required 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.

See also

nfxGetSessionStatus, nfxReceiveFax