fx_rcvfax( )

Description | Examples | Errors | See Also

Name:	int fx_rcvfax(dev, faxname, rcvflag)
Inputs:	int dev	fax channel device handle (to receive fax data)
	char * faxname	name to assign received document
	unsigned long rcvflag	mode flag
Returns:	0 if success (on invocation in asynchronous mode)
	-1 if failure (on invocation in asynchronous mode)
Includes:	srllib.h
	dxxxlib.h
	faxlib.h
Category:	receive fax
Mode:	synchronous/asynchronous

Description

The fx_rcvfax( ) function receives fax data from an open channel device and stores it as a TIFF/F file or a raw file.

NOTE:

A raw file stores fax data as a single page of unstructured, unformatted data.

The fx_rcvfax( ) function can be issued by the fax receiver or the fax transmitter. To stop a fax reception in progress, use fx_stopch( ).

The encoding scheme in which the incoming fax data may be stored (MH or MMR) is based on the capability of the Dialogic fax product. For product capabilities, see Section 2.4. Key Product Features on page 8.

For more information on setting up the channel device to receive fax data, see Chapter 5. Implementing Fax Capability -- Receive Fax.

Parameter	Description
dev	Specifies the channel device handle for the fax channel obtained when the channel was opened.
faxname	Specifies the file name to assign to the incoming fax data.
	The TIFF/F or raw file, named in faxname, is created or overwritten as needed. When storing multi-page fax data in raw files, you must specify a different file for each incoming fax page.
rcvflag	A logical OR bit mask that indicates the following:
	The file format in which to save the incoming fax data
	Polling request from the transmitter is valid or not
	The mode of operation, synchronous or asynchronous
	Enable generation of Phase B events (T.30 pre-message procedure)
	Enable generation of Phase D events (T.30 post-message procedure)
	Enable accepting and issuing operator intervention (voice request) from remote station
	Set maximum receive width
	Set preferred receive length
	Store all incoming fax data at low (coarse) or high (fine) vertical resolution
	Enable user-defined I/O functions (fx_rcvfax2( ) only)
	The rcvflag bit mask can have the following values:
	File format bit:
	Value	Description
	DF_TIFF	TIFF/F structured formatted fax data
	DF_RAW	Raw, unformatted fax data
	Poll bit:
	Value	Description
rcvflag	DF_NOPOLL	Polling invalid (default)
(cont.)	DF_POLL	Polling valid
	Mode bit (for more information, see Section 5.3.2. Mode of Operation on page 81):
	Value	Description
	EV_SYNC	Synchronous mode operation.
	EV_ASYNC	Asynchronous mode operation.
	Phase B, Phase D and Voice Request enable bits. Set one or more of the following (the default is disabled):
	Value	Description
	DF_PHASEB	Enable Phase B event generation. When this bit is set, a TFX_PHASEB event is returned each time Phase B is completed during the receive fax operation. For more information, see Section 5.3.3. Enable Phase B Event Generation on page 82.
	DF_PHASED	Enable Phase D event generation. When this bit is set, a TFX_PHASED event is returned each time Phase D is completed during the receive fax operation, except for the last page. After the last page, fx_rcvfax( ) completes (synchronous mode) or a TFX_FAXRECV event occurs (asynchronous mode). For more information, see Section 5.3.4. Enable Phase D Event Generation on page 83.
	DF_ACCEPT_VRQ	Enable accepting operator intervention (voice request) from remote station
	DF_ISSUE_VRQ	Enable issuing operator intervention (voice request) to remote station
	Maximum receive width bits:
	Value	Description
rcvflag (cont.)	DF_1728MAX	Maximum receive width: 1728 pixels
	DF_2048MAX	Maximum receive width: 2048 pixels
	DF_2432MAX	Maximum receive width: 2432 pixels (default)
	Preferred receive length bits:
	Value	Description
	DF_A4MAXLEN	Maximum receive length: A4 size (approximately 11 inches)
	DF_B4MAXLEN	Maximum receive length: B4 size (approximately 14 inches)
	DF_NOMAXLEN	Maximum receive length: unlimited (default)
	Vertical resolution of fax data storage. The default is the incoming fax data's specified resolution.
	Value	Description
	DF_RXRESLO	Store all incoming fax data at low vertical resolution.
	DF_RXRESHI	Store all incoming fax data at high vertical resolution.
	Enable user-defined I/O bit, available for fx_rcvfax2( ) only:
	Value	Description
	IO_UIO	User-defined I/O functions for fx_rcvfax2( )

Examples

• Example 1: Receive Fax Data into TIFF/F File Format - Synchronous
• Example 2: Receive Fax Data into Raw File - Synchronous
• Example 3: Receive Fax Data using Asynchronous Programming Mode

Examples 1 and 2 use fx_rcvfax( ) for receiving fax data into TIFF/F and raw format files in synchronous mode. The synchronous programming code fragments shown can be used in a multi-threaded application where the program creates a separate thread for every channel. Each thread would control a single channel using a synchronous mode of operation.

Example 3 uses fx_rcvfax( ) in asynchronous mode. The asynchronous programming code fragments shown can be used in a multi-threaded application where the program creates multiple threads. Each thread could control a single channel or multiple channels using an asynchronous mode of operation. See the Voice Software Reference - Standard Runtime Library for information on programming modes and the Standard Runtime Library (SRL) functions.

Example 1: Receive Fax Data into TIFF/F File Format - Synchronous

#include <stdio.h>  
#include <windows.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <faxlib.h>  
int voxdev;   /* Voice channel device handle. */  
int dev;      /* Fax channel device handle. */  
unsigned long rcvflag = DF_NOPOLL|DF_TIFF|EV_SYNC;  
unsigned short value;  
/*  
 * Open the channel using dx_open( ) to obtain the Dialogic  
 * VOICE channel device handle in voxdev. Use voxdev for  
 * all Voice API calls.  
 */  
if ((voxdev = dx_open("dxxxB1C1", NULL)) == -1) {  
   /* Error opening device. */  
      /* Perform system error processing */  
      exit(1);  
}  
/*  
 * Open the channel using fx_open( ) to obtain the FAX  
 * channel device handle in dev. Use dev for all Fax API  
 * calls.  
 */  
if ((dev = fx_open("dxxxB1C1", NULL)) == -1) {  
   /* Error opening device. */  
   /* Perform system error processing */  
   exit(1);  
}  
.  
.  
/*  
 * Set channel on-hook using dx_sethook( ) in synchronous  
 * mode.  
 */  
.  
.  
/*  
 * Wait for 1 ring and go off-hook using dx_wtring( ).  
 */  
.  
.  
/* If this is a channel on a VFX/40SC (return type DFS_FAX40)  
 * or VFX/40ESC (return type DFS_FAX40E),  
 * a vertical resolution for the receive file can  
 * be specified in rcvflag. For the VFX/40ESC, the  
 * received data can be stored as MMR encoded data.  
 */  
switch (ATFX_CHTYPE(dev))  {  
case DFS_FAX40:  
   /* Store the received file in low vertical resolution. */  
   rcvflag |= DF_RXRESLO;  
   break;  
case DFS_FAX40E:  
   /*  
    * Store the received file in low vertical resolution  
    * and MMR encoding.  
    */  
   rcvflag |= DF_RXRESLO;  
   value = DF_MMR;  
   if (fx_setparm(dev,FC_RXCODING,(void *)&value) == -1) {  
      printf("Error - %s (error code %d)\n", ATDV_ERRMSGP(dev),  
         ATDV_LASTERR(dev));  
      if (ATDV_LASTERR(dev) == EDX_SYSTEM) {  
         /* Perform system error processing */  
      }  
   }  
   break;  
default:  
   break;  
}  
/* Set initial state of FAX channel to RECEIVER. */  
if (fx_initstat(dev,DF_RX) == -1) {  
   printf("Error - %s (error code %d)\n", ATDV_ERRMSGP(dev),  
      ATDV_LASTERR(dev));  
   if (ATDV_LASTERR(dev) == EDX_SYSTEM) {  
      /* Perform system error processing */  
   }  
}  
/*  
 * Receive the fax data into "myfax.tif" file - synchronous  
 * mode.  
 */  
if((fx_rcvfax(dev,"myfax.tif",rcvflag))  
    == -1) {  
   printf("Error - %s (error code %d)\n", ATDV_ERRMSGP(dev),  
       ATDV_LASTERR(dev));  
   if (ATDV_LASTERR(dev) == EDX_SYSTEM) {  
      /* Perform system error processing */  
   }  
   printf("Phase E status: %ld\n", ATFX_ESTAT(dev));  
   /* Application specific error handling. */  
   .  
   .  
}




Example 2: Receive Fax Data into Raw File - Synchronous

#include <stdio.h>  
#include <windows.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <faxlib.h>  
int count = 0;  
char faxname[30];  
int voxdev;   /* Voice channel device handle. */  
int dev;      /* Fax channel device handle. */  
unsigned long rcvflag = DF_NOPOLL|DF_RAW|EV_SYNC;  
unsigned short value;  
/*  
 * Open the channel using dx_open( ) to obtain the Dialogic  
 * VOICE channel device handle in voxdev. Use voxdev for  
 * all Voice API calls.  
 */  
if ((voxdev = dx_open("dxxxB1C1", NULL)) == -1) {  
   /* Error opening device. */  
      /* Perform system error processing */  
      exit(1);  
}  
/*  
 * Open the channel using fx_open( ) to obtain the FAX  
 * channel device handle in dev. Use dev for all Fax API  
 * calls.  
 */  
if ((dev = fx_open("dxxxB1C1", NULL)) == -1) {  
   /* Error opening device. */  
   /* Perform system error processing */  
   exit(1);  
}  
.  
.  
/*  
 * Set channel on-hook using dx_sethook( ) in synchronous  
 * mode.  
 */  
.  
.  
/*  
 * Wait for 1 ring and go off-hook using dx_wtring( ).  
 */  
.  
.  
/* If this is a channel on a VFX/40SC (return type DFS_FAX40)  
 * or VFX/40ESC (return type DFS_FAX40E),  
 * a vertical resolution for the receive file can  
 * be specified in rcvflag. For the VFX/40ESC, the  
 * received data can be stored as MMR encoded data.  
 */  
switch (ATFX_CHTYPE(dev))  {  
case DFS_FAX40:  
   /* Store the received file in low vertical resolution. */  
   rcvflag |= DF_RXRESLO;  
   break;  
case DFS_FAX40E:  
   /*  
    * Store the received file in low vertical resolution  
    * and MMR encoding.  
    */  
   rcvflag |= DF_RXRESLO;  
   value = DF_MMR;  
   if (fx_setparm(dev,FC_RXCODING,(void *)&value) == -1) {  
      printf("Error - %s (error code %d)\n", ATDV_ERRMSGP(dev),  
         ATDV_LASTERR(dev));  
      if (ATDV_LASTERR(dev) == EDX_SYSTEM) {  
         /* Perform system error processing */  
      }  
   }  
   break;  
default:  
   break;  
}  
/* Set initial state of the FAX channel to RECEIVER. */  
if (fx_initstat(dev,DF_RX) == -1) {  
   printf("Error - %s (error code %d)\n", ATDV_ERRMSGP(dev),  
      ATDV_LASTERR(dev));  
   if (ATDV_LASTERR(dev) == EDX_SYSTEM) {  
      /* Perform system error processing */  
   }  
}  
do {  
/* Receive each page into a separate file until the application  
 * receives a DFS_EOP Phase D status value. fx_rcvfax( ) is  
 * being used in synchronous mode.  
 */  
.  
.  
/*  
 * Generate a file name in faxname, for example, rcv_pg0.raw,  
 * rcv_pg1.raw, etc.  
 */  
.  
.  
   if(fx_rcvfax(dev,faxname,rcvflag) == -1)  
      printf("Error - %s (error code %d)\n",  
         ATDV_ERRMSGP(dev), ATDV_LASTERR(dev));  
      if (ATDV_LASTERR(dev) == EDX_SYSTEM) {  
         /* Perform system error processing */  
      }  
      printf("Phase E status: %ld\n", ATFX_ESTAT(dev));  
      /* Application specific error handling. */  
      .  
      .  
   }  
} while(ATFX_PHDCMD(dev) != DFS_EOP);  
/* Show results. */  
printf("Fax received: %ld pages\n",ATFX_PGXFER(dev));  
/*  
 * Note: The encoding scheme of the received RAW data is specified  
 * in the variable 'value' used for setting the FC_RXCODING  
 * parameter. If these RAW files have to be transmitted, the same  
 * encoding scheme value will have to be specified in the DF_IOTT  
 * entry.  
 */  
.  
.




Example 3: Receive Fax Data using Asynchronous Programming Mode

#include <stdio.h>  
#include <windows.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <faxlib.h>  
#define MAXCHANS  24  
int catchall( );  
int recv_fax( );  
/* Error routine - print error information. */  
void print_err(dev)  
   int dev;  
{  
   printf("Error - %s (error code %ld)\n",  
      ATDV_ERRMSGP(dev),ATDV_LASTERR(dev));  
   if (ATDV_LASTERR(dev)==EDX_SYSTEM) {  
      /* Perform system error processing */  
   }  
   return;  
}  
/*  
 * main( ): Opens all channels and enables handler for  
 * asynchronous operation. Channels go on-hook and wait for  
 * rings. On receiving rings, the channel goes off-hook and  
 * receives a fax.  
 */  
main( )  
{  
   int chan;  
   char * chnamep;  
   int mode = SR_STASYNC;  
   int voxdev;   /* Voice channel device handle. */  
   int faxdev;   /* Fax channel device handle. */  
     /* Set SRL to turn off creation of internal thread */  
     if( sr_setparm( SRL_DEVICE, SR_MODELTYPE, &mode ) == -1 ){  
        printf( "Error: cannot set srl mode\n" );  
        exit( 1 );  
     }  
   for (chan=0; chan < MAXCHANS; chan++) {  
      /*  
       * Set chnamep to the channel device name, e.g.,  
       * dxxxB1C1, dxxxB1C2, etc.  
       * Open the channel using dx_open( ) so that voxdev  
       * has the VOICE channel device handle.  
       * Open the channel using fx_open( ) so that faxdev  
       * has the FAX channel device handle.  
       */  
     if(( voxdev = dx_open( chnamep, NULL )) == -1 ){  
          printf( "Error: cannot open vox device\n" );  
          exit( 1 );  
     }  
     if(( faxdev = fx_open( chnamep, NULL )) == -1 ){  
          printf( "Error: cannot open fax device\n" );  
          exit( 1 );  
     }  
       .  
       .  
       .  
     /* enable a handler for all events on any devices */  
     if( sr_enbhdlr( EV_ANYDEV, EV_ANYEVT, dx_handler ) == -1 ){  
        printf( "Error: could not enable handler\n" );  
        exit( 1 );  
     }  
       .  
       .  
       .  
      /*  
       * Place channel on-hook by calling dx_sethook( ) with  
       * its mode field set to EV_ASYNC (asynchronous).  
       */  
     if( dx_sethook( voxdev, DX_ONHOOK, EV_ASYNC ) == -1 ){  
        printf( "dx_sethook failed: error = %s\n", ATDV_ERRMSGP( voxdev ));  
        exit( 1 );  
     }  
      .  
      .  
   }  
   /*  
    * All channels have been opened and a sethook function  
    * issued to place the channels on-hook. Use sr_waitevt( )  
    * to wait for completion events.  
    * On receiving any completion event, control is transferred  
    * to the catchall( ) handler function.  
    */  
    while(sr_waitevt(-1))  
    .  
    .  
/* Event handler. */  
/*  
 * This routine is called when sr_waitevt( ) receives an event.  
 * Maintain a state machine for every channel and issue the  
 * appropriate function depending on the next action to be  
 * performed on the channel, e.g., the application may wish  
 * to wait for rings after an on-hook completion event and  
 * start receiving a fax as soon as rings are received.  
 */  
int catchall( )  
{  
   int dev = sr_getevtdev( );  
   char * fnamep;  
   /* Determine the event. */  
   switch(sr_getevttype( ))  {  
   case TDX_SETHOOK:  
      /*  
       * If channel has gone off-hook, start receiving the  
       * fax.  
       */  
      if (ATDX_HOOKST(dev) == DX_OFFHOOK) {  
         /*  
          * Set the fax state of the channel to DF_RX using  
          * fx_initstat( ).  
          */  
         .  
         .  
         /*  
          * Set up fnamep to point to TIFF/F file name.  
          * Start receiving the fax.  
          */  
         if (fx_rcvfax(dev, fnamep, DF_TIFF|DF_NOPOLL|EV_ASYNC) == -1) {  
            print_err(dev);  
            printf("Phase E status: %ld\n",  
              ATFX_ESTAT(dev));  
            /* Application specific error handling here. */  
            .  
            .  
         }  
      } else {  
         /*  
          * Channel is on-hook. State machine dependent  
          * action.  
          */  
         .  
         .  
      }  
      break;  
   case TDX_CST:  
      /* Handle rings received event. */  
      .  
      .  
      break;  
   case TFX_FAXRECV:  
      /* The document has been successfully received. */  
      printf("Received %ld pages at speed %ld, resln %ld,  
         width %ld\n", ATFX_PGXFER(dev), ATFX_SPEED(dev),  
         ATFX_RESLN(dev), ATFX_WIDTH(dev));  
      .  
      .  
      break;  
   case TFX_FAXERROR:  
      /* Error during the fax session. */  
      print_err(dev);  
      printf("Phase E status %d\n", ATFX_ESTAT(dev));  
      /* Application specific error handling. */  
      .  
      .  
      break;  
   default:  
      .  
      .  
      break;  
   } /* End of switch. */  
   return(0);  
}

Errors

In synchronous mode, this function returns a zero to indicate successful completion or a -1 to indicate an error.

In asynchronous mode, this function returns a zero to indicate successful invocation or a -1 to indicate an invocation error.

Errors that occur during reception generate a Standard Runtime Library event (TFX_FAXERROR). To access the Dialogic defined error code, call the Dialogic standard attribute functions ATDV_LASTERR( ) and ATDV_ERRMSGP( ). The latter returns a string describing the error (see the Voice Software Reference-Programmer's Guide). See Appendix D for a list of Dialogic defined fax error codes.

If the fx_rcvfax( ) function successfully completes, a TFX_FAXRECV Dialogic Standard Runtime Library event is generated.

The fax extended attribute ATFX_ESTAT( )) provides additional error information for T.30 Phase E fax protocol.

System errors return an EDX_SYSTEM error; use dx_fileerrno( ) to obtain error value. Refer to the dx_fileerrno( ) function in the Voice Software Reference - Programmer's Guide for a list of the possible system error values.

See Also

• ATFX_name functions
• fx_rcvfax2( )
• fx_getDCS( )
• fx_getDIS( )
• fx_getNSF( )

Click here to contact Dialogic Customer Engineering