r2_playbsig( )

Description | Example | Errors | Cautions | See Also

Name:	int r2_playbsig(chdev,backwardsig,forwardsig,mode)
Inputs:	int chdev	channel device handle
	int backwardsig	group A/B backward signal
	int forwardsig	group I/II forward signal
	int mode	asynchronous/synchronous
Returns:	0 if success
	error return code
Includes:	srllib.h
	dxxxlib.h
Category:	R2MF
Mode:	asynchronous/synchronous

Description

The r2_playbsig( ) function plays a specified backward R2MF signal on the specified channel until a tone-off event is detected for the specified forward signal.

The r2_playbsig( ) function is a convenience function that plays a tone and controls the timing sequence required by the R2MF compelled signaling procedure.

Compelled signaling sends each signal, until it is responded to by a return signal, which in turn is sent until responded to by the other party. See the Voice Software Reference: Voice Features Guide for more information about R2MF Compelled signaling.

NOTE:

This function calls the dx_playtone( ) function to play the tone.

Asynchronous Operation

1. Enable forward signal detection using r2_creatfsig( ).
2. Use SRL to asynchronously wait for TDX_CST event(s).
3. Use sr_getevtdatap( ) to retrieve the DX_CST structure, which will contain a DE_TONEON event in the cst_event field.
4. Determine which forward signal was detected by matching the tone ID returned cst_data field (from 101 to 115) with the forward signal Group I or Group II defines (see forwardsig argument description for a list of the forward signal defines).
5. Decide which backward signal should be played in response to the forward signal.
6. Use the r2_playbsig( ) function to play the desired backward signal.
7. r2_playbsig( ) will terminate automatically when a tone-off event is detected. There is a 60-second default duration for playing the backward signal. If the forward signal tone-off is not detected within 60 seconds, the backward signal will terminate with a TDX_PLAYTONE event, and ATDX_TERMMSK will return TM_MAXTIME.

Synchronous Operation

1. Enable forward signal detection using r2_creatfsig( ).
2. Call dx_getevt( ) to wait for a DX_TONEON event. Events are returned in the DX_EBLK structure.
3. Determine which forward signal was detected by matching the tone ID contained in the ev_data field (from 101 to 115) with the forward signal Group I or Group II defines (see forwardsig argument description for a list of the forward signal defines).
4. Decide which backward signal should be played in response to the forward signal.
6. Use the r2_playbsig( ) function to play the desired backward signal.
7. r2_playbsig( ) will terminate automatically when a tone-off event is detected. There is a 60-second default duration for playing the backward signal. If the forward signal tone-off is not detected within 60 seconds, the backward signal will terminate, and ATDX_TERMMSK( ) will return TM_MAXTIME.

Parameter	Description
chdev	specifies the valid channel device handle obtained when the channel was opened using dx_open( ).
backwardsig	specifies the name of a Group A or Group B backward signal to play. Set to one of the defines in Group A or one of the defines in Group B: Specify one of: Associated Tone ID Group A Group B SIGA_1 SIGB_1 101 SIGA_2 SIGB_2 102 SIGA_3 SIGB_3 103 SIGA_4 SIGB_4 104 SIGA_5 SIGB_5 105 SIGA_6 SIGB_6 106 SIGA_7 SIGB_7 107 SIGA_8 SIGB_8 108 SIGA_9 SIGB_9 109 SIGA_10 SIGB_10 110 SIGA_11 SIGB_11 111 SIGA_12 SIGB_12 112 SIGA_13 SIGB_13 113 SIGA_14 SIGB_14 114 SIGA_15 SIGB_15 115
forwardsig:	specifies the name of the Group I or Group II forward signal for which a tone-on event was detected, and for which a tone-off event will terminate this function. Set to one of defines from Group I or one of the defines from Group II: Specify one of: Associated Tone ID Group I Group II SIGI_1 SIGII_1 101 SIGI_2 SIGII_2 102 SIGI_3 SIGII_3 103 SIGI_4 SIGII_4 104 SIGI_5 SIGII_5 105 SIGI_6 SIGII_6 106 SIGI_7 SIGII_7 107 SIGI_8 SIGII_8 108 SIGI_9 SIGII_9 109 SIGI_10 SIGII_10 110 SIGI_11 SIGII_11 111 SIGI_12 SIGII_12 112 SIGI_13 SIGII_13 113 SIGI_14 SIGII_14 114 SIGI_15 SIGII_15 115

The following procedure describes how to use the r2_playbsig( ) function:

Example

#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
main()  
{  
   int  dxxxdev;  
   
   /*  
    * Open the Voice Channel Device and Enable a Handler  
    */  
   if ( ( dxxxdev = dx_open( "dxxxB1C1", NULL) ) == -1 ) {  
      perror( "dxxxB1C1" );  
      exit( 1 );  
   }  
   
   /*  
    * Create all forward signals  
    */  
   if ( r2_creatfsig( dxxxdev, R2_ALLFSIG ) == -1 ) {  
      printf( "Unable to Create the Forward Signals\n" );  
      printf( "Lasterror = %d  Err Msg = %s\n",  
          ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ) );  
      dx_close( dxxxdev );  
      exit( 1 );  
   }  
   
   /*  
    * Continue Processing  
    *   .  
    *   .  
    *   .  
    *  
    * Detect an incoming call using dx_wtring()  
    *  
    * Enable the detection of all forward signals using  
    * dx_enbtone(). In this example, only the first  
    * forward signal will be enabled.  
    */  
   if (dx_enbtone( dxxxdev, SIGI_1, DM_TONEON | DM_TONEOFF ) == -1 ) {  
      printf( "Unable to Enable Detection of Tone %d\n", SIGI_1 );  
      printf( "Lasterror = %d  Err Msg = %s\n",  
          ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ) );  
      dx_close( dxxxdev );  
      exit( 1 );  
   }  
   
   /*  
    * Now wait for the TDX_CST event and event type,  
    * DE_TONEON. The data part contains the ToneId of  
    * the forward signal detected. Based on the forward  
    * signal, determine the backward signal to generate.  
    *  
    * In this example, we will be generating the Group A  
    * backward signal A-1 (send next digit) assuming  
    * forward signal received is SIGI_1.  
    */  
   
   if ( r2_playbsig( dxxxdev, SIGA_1, SIGI_1, EV_SYNC ) == -1 ) {  
      printf( "Unable to generate the backward signals\n" );  
      printf( "Lasterror = %d  Err Msg = %s\n",  
          ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ) );  
      dx_close( dxxxdev );  
      exit( 1 );  
   }  
   
   /*  
    * Continue Processing  
    *   .  
    *   .  
    *   .  
    */  
   
   /*  
    * Close the opened Voice Channel Device  
    */  
   if ( dx_close( dxxxdev ) != 0 ) {  
      perror( "close" );  
   }  
   
   /* Terminate the Program */  
   exit( 0 );  
}

Errors

If this function returns -1 to indicate failure, use ATDV_LASTERR( ) and ATDV_ERRMSGP( ) to retrieve one of the following error reasons:

EDX_BADPARM	Invalid parameter
EDX_BADPROD	Function not supported on this board
EDX_BADTPT	Invalid DV_TPT entry
EDX_BUSY	Busy executing I/O function
EDX_AMPLGEN	Invalid amplitude value in TN_GEN structure
EDX_FREQGEN	Invalid frequency component in TN_GEN structure
EDX_FLAGGEN	Invalid tn_dflag field in TN_GEN structure
EDX_SYSTEM	Error from operating system; use dx_fileerrno( ) to obtain error value

Cautions

The channel must be idle when calling this function.

See Also

• r2_creatfsig( )
• dx_blddt( )
• dx_playtone( )
• R2MF Signaling - (Voice Software Reference: Voice Features Guide)

Click here to contact Dialogic Customer Engineering