(Page 13 of 18 in this chapter)


nfxReceiveFax

Description

Starts the receive side of T.30 protocol fax session and stores all received documents in the nonexistent files in the specified receive queue.

Prototype

DWORD nfxReceiveFax ( CTAHD ctahd,
NFX_QUEUE_HANDLE receive_queue_handle,
NFX_RECEIVE_PARMS *ptr_receive_parms)

ctahd CTA context handle returned by ctaCreateContext.

receive_queue_handle Handle for queue of documents to receive, returned by nfxCreateQueue.

ptr_receive_parms Pointer to NFX_RECEIVE_PARMS structure (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;     /* tx level in tenths of dBm(-150 to -60)           */
 INT32 threshold;     /* lowest level for receive, 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

Events

Details

If a fax license unit has not been allocated to the specified CTA context, this function will attempt to allocate one. NFXEVN_nnn events indicate progress of the fax session and completion of the fax session.

Note: You must continue processing events during an active fax session. Make sure that file I/O intensive operations do not interfere with the handling of events and cause the fax session to time out. Events should be processed within three seconds.

To enable polling, make sure that the called fax terminal has pollingenabled in NFX_RECEIVE_PARMS set to NFX_YES. If polling is enabled and the sender subsequently requests polling, the event NFXEVN_POLLED is received. Use nfxAnswerFaxPoll to continue the fax operation.

Receiving any of the previously listed events indicates that the fax session status has been updated. Use nfxGetSessionStatus to examine the current session status in more detail.

After a fax session has completed, the application must release the call and tear down or reset any document queues. NaturalFax sends a DCN (disconnect) frame at the end of a fax session, which signals the remote fax terminal to disconnect. The application must also use functions from the ADI service to release the call after a completed fax session.

Some fax terminals may disconnect the call before they receive the DCN frame. Under these conditions, the NaturalFax application may receive an ADIEVN_CALL_DISCONNECTED event before it receives the NFXEVN_SESSION_DONE event. The application should release the call as usual. The NFXEVN_SESSION_DONE event will contain a reason of CTA_REASON_RELEASED or CTA_REASON_FINISHED.

See Also

nfxAnswerFaxPoll, nfxGetLicenseStatus, nfxSendFax



(Page 13 of 18 in this chapter)


tech_support@nmss.com
Copyright © 1998, Natural MicroSystems, Inc. All rights reserved.