ATFX_RTNPAGES( )

Description | Example | Errors

Name:	long ATFX_RTNPAGES(dev)
Inputs:	int dev	fax channel device handle
Returns:	number of pages RTN was returned to the remote station
	AT_FAILURE if error
Includes:	srllib.h
	dxxxlib.h
	faxlib.h
Category:	extended attribute
Mode:	synchronous

Description

The ATFX_RTNPAGES( ) function returns the number of RTN pages; that is, the number of received pages for which the receiver returned an RTN (Retrain Negative) message to the remote transmitter.

If an unacceptable percentage of bad scan lines is received for a fax page (controlled by the FC_RTN parameter in fx_setparm( )), an RTN is returned to the remote station. The received page is still written to the specified receive file. After receiving the RTN, the transmitter may or may not retransmit the same page.

Parameter	Description
dev	Specifies the channel device handle for the fax channel obtained when the channel was opened.

At the completion of the fx_rcvfax( ) or fx_rcvfax2( ) function, the receiver application may call ATFX_RTNPAGES( ) to determine the total number of RTN pages received.

NOTE:

To monitor the RTN status for each page of a multi-page fax, you must enable Phase D events (DF_PHASED) in each fx_rcvfax( ) or fx_rcvfax2( ) function called and issue ATFX_PHDRPY( ) to monitor for an RTN message.

The data provided by this function is updated each time the fax transfer completes Phase D of the T.30 protocol.

To monitor the number of RTN pages, you must enable Phase D events and issue ATFX_RTNPAGES( ) when the TFX_PHASED event occurs. Note that since Phase D also occurs at the end of a send or receive when a Phase D event is not generated, you can issue this function after a TFX_FAXSEND or TFX_FAXRECV event.

The final RTN page count value returned by ATFX_RTNPAGES( ) at the end of a fax session remains available to the application until a new send or receive is initiated on that channel.

If the receive file is a TIFF/F file, you can examine the tag 'BadFaxLines' for each page to determine the page's image quality (see TIFF/F tags in Appendix A).

Example

#include <stdio.h>  
#include <windows.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <faxlib.h>  
int dev;  
long badpages;  
/*  
 * Open the channel using fx_open( ) and obtain the Dialogic  
 * FAX device handle in dev.  
 */  
.  
.  
/*  
 * Call fx_rcvfax( ) to receive a fax into the file  
 * "myfax.tif".  
 */  
if (fx_rcvfax(dev, "myfax.tif", DF_TIFF|EV_SYNC) == -1) {  
   printf("Error - %s (error code %ld)\n",  
      ATDV_ERRMSGP(dev),ATDV_LASTERR(dev));  
   if (ATDV_LASTERR(dev)==EDX_SYSTEM) {  
      /* Perform system error processing */  
   }  
   /*  
    * Additional error processing - check Phase E status to  
    * determine cause of error during fax protocol.  
    */  
   printf("Phase E status: %ld\n", ATFX_ESTAT(dev));  
   .  
   .  
}  
/*  
 * Check if the received file has any pages for  
 * which a RTN was returned.  
 */  
badpages = ATFX_RTNPAGES(dev);

Errors

This function fails and returns AT_FAILURE if an invalid fax channel device handle is specified in dev.

Click here to contact Dialogic Customer Engineering