fx_getDCS( )

Description | Example | Errors

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

Description

The fx_getDCS( ) function returns the most recent DCS message (T.30 Digital Command Signal), if available, for the specified channel.

Parameter	Description
dev	Specifies the channel device handle for the fax channel obtained when the channel was opened.
dcs_buf	A pointer to the DF_DCS structure where the DCS message information is stored.

The DCS message contains information about negotiated settings between the transmitter and receiver. The DCS message is sent by the transmitter to the receiver as part of Phase B negotiation of a fax transfer.

Use this function only when your application requires the specific Phase B negotiation information provided in the DCS message. For most applications, using fx_getDCS( ) to retrieve the DCS message information is not required because the fax extended attribute functions provide access to most of the information contained in the DCS message; see ATFX_RESLN( ), ATFX_SPEED( ), ATFX_WIDTH( ).

The most recent DCS message sent from the transmitter is available to the application after the completion of the first Phase B negotiation. If available, the DCS message can be retrieved after each Phase B negotiation during the fx_sendfax( ), fx_rcvfax( ) or fx_rcvfax2( ) function call. The DCS 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.

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

NOTE:

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

For DCS 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_DCS dcs_buf;  
   if (ATFX_BSTAT(dev) & DFS_DCS) {  
      /* T.30 DCS available. */  
      if (fx_getDCS(dev, &dcs_buf) == -1) {  
         /* Error processing */  
         .  
         .  
      } else {  
         /* Application specific analysis of the DCS */  
         .  
         .  
      }  
   }  
   .  
   .  
   return(0);  
}

Errors

ATDV_LASTERR( ) returns these 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