fx_getDIS( )

Description | Example | Errors

Name:	int fx_getDIS(dev,dis_buf)
Inputs:	int dev	fax channel device handle
	DF_DIS * dis_buf	pointer to DF_DIS structure
Returns:	0 if success
	-1 if failure
Includes:	srllib.h
	dxxxlib.h
	faxlib.h
Category:	miscellaneous
Mode:	synchronous

Description

The fx_getDIS( ) function returns the most recent DIS message (T.30 Digital Information Signal), if available, for the specified channel.

The DIS message contains information about the receiver's capabilities. The DIS message is sent by the receiver to the transmitter as part of Phase B negotiation of a fax transfer.

NOTE:

Only use this function when your application requires specific receiver capability information provided in the DIS message. For most applications, retrieving the DIS message information is not required.

Parameter	Description
dev	Specifies the channel device handle for the fax channel obtained when the channel was opened.
dis_buf	A pointer to the DF_DIS structure where the DIS information is stored.

The most recent DIS message from the receiver is available to the application after the completion of the first Phase B negotiation. If available, the DIS message can be retrieved after each Phase B negotiation during the fx_sendfax( ), fx_rcvfax( ) or fx_rcvfax2( ) function call. The DIS message information remains valid until the next Phase B negotiation is completed for the current function call or until a new send or receive is initiated.

NOTE:

Phase B negotiations take place at the beginning of a fax send or receive function call and after a T.30 End of Message (EOM) message is sent by the transmitter during a fax send or receive function call.

To determine when the DIS message is available, call the ATFX_BSTAT( ) function. This function returns a bitmap with the DFS_DIS bit set indicating that the receiver's DIS message is available.

For DIS message details, see the ITU-T publication Procedures for Document Facsimile Transmission in the General Switched Telephone Network, Recommendation T.30 (see Section 1.3.2. Other Publications).

Example

#include <windows.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <faxlib.h>  
DF_IOTT iott[10];  
/* Handler for Phase B events. */  
int phb_hdlr( );  
main( )  
{  
   int voxdev;   /* Voice channel device handle. */  
   int dev;   /* Fax channel device handle. */  
   /*  
    * Open the channel using dx_open( ) to obtain the Dialogic  
    * VOICE device handle in voxdev.  
    * Open the channel using fx_open( ) to obtain the FAX channel  
    * device handle in dev.  
    */  
   .  
   .  
   /*  
    * Install handler using sr_enbhdlr( ) to service  
    * TFX_PHASEB events.  
    */  
    if (sr_enbhdlr(dev, TFX_PHASEB, phb_hdlr) == -1) {  
        printf("Failed to install Phase B handler \n");  
        return;  
    }  
   /*  
    * Call fx_sendfax( ) in asynchronous mode after setting  
    * up the DF_IOTT array.  Set DF_PHASEB bit in mode field  
    * to enable generation of Phase B events.  
    */  
   if (fx_sendfax(dev, iott, EV_ASYNC|DF_PHASEB) == -1) {  
      printf("Error - %s (error code %d)\n",  
         ATDV_ERRMSGP(dev),ATDV_LASTERR(dev));  
      if (ATDV_LASTERR(dev)==EDX_SYSTEM) {  
         /* Perform system error processing */  
      }  
   }  
   .  
   .  
}  
/*  
 * Handler registered with SRL to handle TFX_PHASEB events.  
 */  
int phb_hdlr( )  
{  
   int dev = sr_getevtdev( );  
   DF_DIS dis_buf;  
   if (ATFX_BSTAT(dev) & DFS_DIS) {  
      /* T.30 DIS available. */  
      if (fx_getDIS(dev, &dis_buf) == -1) {  
         /* Error processing. */  
         .  
         .  
      } else {  
         /* Application specific analysis of the DIS. */  
         .  
         .  
      }  
   }  
   .  
   .  
   return(0);  
}

Errors

ATDV_LASTERR( ) returns the following fax error codes for the following reasons:

EFX_NODATA	The function is called before completion of the initial Phase B negotiation.
EFX_UNSUPPORTED	The function is called for an unsupported board.

See Appendix D for a list of error codes that may be returned for this function.

Click here to contact Dialogic Customer Engineering