dx_dial( )

Description | Cautions | Example 1: | Example 2: | Example 3: | Example 4: | Errors | See Also

Name:	int dx_dial(chdev,dialstrp,capp,mode)
Inputs:	int chdev	valid Dialogic channel device handle
	char *dialstrp	pointer to the ASCIIZ dial string
	DX_CAP *capp	pointer to Call Analysis Parameter Structure
	unsigned short mode	asynchronous/synchronous setting and Call Analysis flag
Returns:	0 to indicate successful initiation (Asynchronous)
	>=0 to indicate Call Analysis result if successful (Synchronous)
	-1 if failure
Includes:	srllib.h dxxxlib.h
Category:	I/O
Mode:	synchronous/asynchronous

Description

The dx_dial( ) function dials an ASCIIZ string on an open, idle channel and optionally enables Call Analysis to provide information about the call. If the channel is onhook, the dialing will take place without Call Analysis. The dx_dial( ) function doesn't affect the hook state.

The function parameters are defined as follows:

Parameter	Description
chdev	specifies the valid channel device handle obtained when the channel was opened using dx_open( ).
dialstrp	points to the ASCII dial string. dialstrp must contain a null-terminated string of ASCII characters. Valid dialing and control characters are described in Table 7. Valid Dial String Characters.
capp	points to the Call Analysis Parameter Structure, DX_CAP.
	To use the default Call Analysis parameters, specify NULL in capp and DX_CALLP in mode .
	The D/40 board does not have the Call Analysis feature. When using dx_dial( ), do not pass capp to D/40 channels; pass a NULL pointer and do not set mode to DX_CALLP.
mode	specifies whether an ASCIIZ string should be dialed with or without Call Analysis enabled, and whether the function should run asynchronously or synchronously. mode is a bit mask that can be set to a combination of the following values:
	DX_CALLP	Enable Call Analysis. Note: If the channel is onhook, the dialing will take place without Call Analysis.
	EV_ASYNC	Run dx_dial( ) asynchronously.
	EV_SYNC	Run dx_dial( ) synchronously. (default)
	To run dx_dial( ) without Call Analysis, specify only EV_ASYNC or EV_SYNC. Note that a dx_dial( ) without Call Analysis cannot be terminated using dx_stopch( ), unlike most I/O functions.

Table 7. Valid Dial String Characters

		Valid in Dial Mode
Characters	Description	DTMF	MF	Pulse
On Keypad
0 1 2 3 4 5 6 7 8 9	digits	Yes	Yes	Yes
*	asterisk or star	Yes	Yes (KP)
#	pound, hash, number, or octothorpe	Yes	Yes (ST)
Not on Keypad
a		Yes	Yes (ST1)
b		Yes	Yes (ST2)
c		Yes	Yes (ST3)
d		Yes
Special Control
,	pause (comma)	Yes	Yes
&	flash (ampersand)	Yes	Yes
T	Dial Mode: Tone (DTMF) (default)	Yes	Yes	Yes
P	Dial Mode: Pulse	Yes	Yes	Yes
M	Dial Mode: MF	Yes	Yes	Yes
L	Call Analysis: local dial tone	Yes	Yes	Yes
I	Call Analysis: international dial tone	Yes	Yes	Yes
X	Call Analysis: special dial tone	Yes	Yes	Yes

NOTES:

1. Dial string characters are case sensitive.

2. The default dialing mode is "T" (DTMF tone dialing).

3. Dialogic Scbus and CT Bus boards do not support pulse digit dialing using dx_dial( ).

4. The L, I, and X control characters function only when dialing with PerfectCall Call Progress Analysis.

5. MF dialing is only available on systems with MF capability.

6. The pause character "," and the flash character "&" are not available in MF dialing mode. To send these characters with a string of MF digits, switch to DTMF or pulse mode before sending "," or "&", and then switch back to MF mode by sending an "M". For example:

M*1234T,M5678a

7. Dialing parameter default values can be set or retrieved using dx_getparm( ) and dx_setparm( ); see the board and channel parameter defines in Chapter 6. Voice Device Parameters.

To determine the state of the channel during a dial and/or Call Analysis, use ATDX_STATE( ), which will return one of the following:

CS_DIAL	dial state (with or without Call Analysis)
CS_CALL	Call Analysis state

Asynchronous Operation

Set the mode field to EV_ASYNC, using a bitwise OR. When running asynchronously, the function will return 0 to indicate it has initiated successfully, and will generate one of the following termination events to indicate completion (use the SRL Event Management functions to handle the termination event):

TDX_DIAL	termination of dialing (without Call Analysis)
TDX_CALLP	termination of dialing (with Call Analysis)

If asynchronous dx_dial( ) terminates with a TDX_DIAL event, use ATDX_TERMMSK( ) to determine the reason for termination. If dx_dial( ) terminates with a TDX_CALLP event, use ATDX_CPTERM( ) to determine the reason for termination.

Synchronous Operation

By default, this function runs synchronously, and will return a 0 to indicate that it has completed successfully.

When synchronous dialing terminates, the function will return the Call Progress result (if Call Analysis is enabled) or 0 to indicate success (if Call Analysis isn't enabled).

Call Analysis

Call Analysis provides information about the call. It is enabled to run on the call after dialing completes by setting the mode field. The function can be set to run using default Call Analysis parameters, or by using the Call Analysis Parameter structure (DX_CAP).

Call Analysis results can be retrieved using ATDX_CPTERM( ).

If dx_dial( ) is running synchronously, the Call Analysis results will also be returned by the dx_dial( ) function.

For more information about Call Analysis see the Voice Software Reference: Voice Features Guide.

Possible Call Analysis termination reasons are listed below:

CR_BUSY	line was busy
CR_CEPT	operator intercept
CR_CNCT	call connected
CR_ERROR	Call Analysis error
CR_FAXTONE	fax machine or modem
CR_NOANS	no answer
CR_NODIALTONE	no dial tone
CR_NORB	no ringback
CR_STOPD	Call Analysis stopped due to dx_stopch( )

If Call Analysis is enabled, additional information about the call can be obtained using the following Extended Attribute functions:

ATDX_ANSRSIZ( )	Returns duration of answer
ATDX_CONNTYPE( )	Returns the connection type for a completed call
ATDX_CPERROR( )	Returns Call Analysis error
ATDX_CPTERM( )	Returns last Call Analysis termination
ATDX_CRTNID( )	Returns tone identifier
ATDX_DTNFAIL( )	Returns dial tone fail character
ATDX_FRQDUR( )	Returns duration of first frequency detected
ATDX_FRQDUR2( )	Returns duration of second frequency detected
ATDX_FRQDUR3( )	Returns duration of third frequency detected
ATDX_FRQHZ( )	Returns frequency detected in Hz
ATDX_FRQHZ2( )	Returns frequency of second detected tone
ATDX_FRQHZ3( )	Returns frequency of third detected tone
ATDX_LONGLOW( )	Returns duration of longer silence
ATDX_FRQOUT( )	Returns percent of frequency out of bounds
ATDX_SHORTLOW( )	Returns duration of shorter silence
ATDX_SIZEHI( )	Returns duration of non-silence

Cautions

1. If you attempt to dial a channel in MF mode and do not have MF capabilities on that channel, DTMF tone dialing is used.
2. Issuing a dx_stopch( ) on a channel that is dialing without Call Analysis enabled has no effect on the dial, and will return 0. The digits specified in the dialstrp parameter will still be dialed.
    
   Issuing a dx_stopch( ) on a channel that is dialing with Call Analysis enabled will cause the dialing to complete, but Call Analysis will not be executed. The digits specified in the dialstrp parameter will be dialed. Any Call Analysis information collected prior to the stop will be returned by Extended Attribute functions.

3. This function must be issued when the channel is idle.

Example 1: Call Analysis with user-specified parameters (Synchronous Mode)

/* Call Analysis with user-specified parameters and synchronous mode. */  
   
#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
main()  
{  
   int cares, chdev;  
   DX_CAP capp;  
   .  
   .  
   /* open the channel using dx_open( ).  Obtain channel device descriptor in  
    * chdev  
    */  
   if ((chdev = dx_open("dxxxB1C1",NULL)) == -1)  {  
     /* process error */  
   }  
   
   /* take the phone off-hook */  
   if ((dx_sethook(chdev,DX_OFFHOOK,EV_SYNC)) == -1) {  
     /* process error */  
   }  
   
   /* Clear DX_CAP structure */  
   dx_clrcap(&capp);  
   
   /* Set the DX_CAP structure as needed for call analysis.  
    * Allow 3 rings before no answer.  
    */  
   capp.ca_nbrdna = 3;  
   
   /*  Perform the outbound dial with call analysis enabled. */  
   if ((cares = dx_dial(chdev,"5551212",&capp,DX_CALLP|EV_SYNC)) == -1) {  
     /* perform error routine */  
   }  
   
   switch (cares) {  
     case CR_CNCT:     /* Call Connected, get some additional info */  
      printf("\nDuration of short low - %ld ms",ATDX_SHORTLOW(chdev)*10);  
      printf("\nDuration of long low  - %ld ms",ATDX_LONGLOW(chdev)*10);  
      printf("\nDuration of answer    - %ld ms",ATDX_ANSRSIZ(chdev)*10);  
      break;  
     case CR_CEPT:     /* Operator Intercept detected */  
      printf("\nFrequency detected - %ld Hz",ATDX_FRQHZ(chdev));  
      printf("\n%% of Frequency out of bounds - %ld Hz",ATDX_FRQOUT(chdev));  
      break;  
     case CR_BUSY:  
      .  
      .  
   }  
   /* carry out the next state */  
   .  
   .  
}

Example 2: Call Analysis with default parameters (Synchronous Mode)

/* Call Analysis with default parameters and synchronous mode. */  
   
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
main()  
{  
   int cares, chdev;  
   DX_CAP capp;  
   
   /* open the channel using dx_open( ).  Obtain channel device descriptor  
    * in chdev  
    */  
   if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {  
     /* process error */  
   }  
   
   /* take the phone off-hook */  
   if ((dx_sethook(chdev,DX_OFFHOOK,EV_SYNC)) == -1) {  
     /* process error */  
   }  
   
   /* Perform the outbound dial with call analysis enabled and capp set to  
    * NULL  
    */  
   if ((cares = dx_dial(chdev,"5551212",(DX_CAP *)NULL,DX_CALLP|EV_SYNC)) ==   
        -1) {  
     /* perform error routine */  
   }  
   /* Analyze the call analysis results as in Example 1 */  
   .  
   .  
}

Example 3: Call Analysis with default parameters (Asynchronous, Callback Mode)

/* Call Analysis with user-specified parameters and asynchronous, callback mode. */  
   
#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
#define MAXCHAN 24  
   
int dial_handler();  
   
DX_CAP capp;  
   
main()  
{  
   int i, chdev[MAXCHAN];  
   char *chnamep;  
   int srlmode;  
   /* Set SRL to run in polled mode. */  
   srlmode = SR_POLLMODE;  
   if (sr_setparm(SRL_DEVICE, SR_MODEID, (void *)&srlmode) == -1) {  
      /* process error */  
   }  
   
   for (i=0; i<MAXCHAN; i++) {  
   
      /* Set chnamep to the channel name, e.g., dxxxB1C1, dxxxB1C2,... */  
   
      /* Open the device using dx_open( ).  chdev[i] has channel device  
       * descriptor.  
       */  
       if ((chdev[i] = dx_open(chnamep,NULL)) == -1)   {  
          /* process error */  
       }  
   
      /* Using sr_enbhdlr(), set up handler function to handle call analysis  
       * completion events on this channel.  
       */  
       if (sr_enbhdlr(chdev[i], TDX_CALLP, dial_handler) == -1) {  
          /* process error */  
       }  
      /* Before issuing dx_dial(), place the phone off-hook. */  
   
      /* Clear DX_CAP structure */  
      dx_clrcap(&capp);  
   
      /* Set the DX_CAP structure as needed for call analysis.  
       * Allow 3 rings before no answer.  
       */  
      capp.ca_nbrdna = 3;  
   
      /*  Perform the outbound dial with call analysis enabled. */  
       if (dx_dial(chdev[i],"5551212",&capp,DX_CALLP|EV_ASYNC) == -1) {  
          /* perform error routine */  
       }  
   
       /* Use sr_waitevt() to wait for the completion of call analysis.  
        * On receiving the completion event,TDX_CALLP,control is transferred  
        * to the handler function previously established using sr_enbhdlr().  
        */  
         .  
         .  
   
   }  
}  
   
int dial_handler()  
{  
   int chdev;  
   
   chdev = sr_getevtdev();  
   switch (ATDX_CPTERM(chdev)) {  
     case CR_CNCT:	/* Call Connected, get some additional info */  
      printf("\nDuration of short low - %ld ms",ATDX_SHORTLOW(chdev)*10);  
      printf("\nDuration of long low  - %ld ms",ATDX_LONGLOW(chdev)*10);  
      printf("\nDuration of answer    - %ld ms",ATDX_ANSRSIZ(chdev)*10);  
      break;  
     case CR_CEPT:     /* Operator Intercept detected */  
      printf("\nFrequency detected - %ld Hz",ATDX_FRQHZ(chdev));  
      printf("\n%% of Frequency out of bounds - %ld Hz",ATDX_FRQOUT(chdev));  
      break;  
     case CR_BUSY:  
       .  
      .  
   }  
   
   /* Kick off next function in the state machine model. */  
   .  
   .  
   
   return 0;  
}

Example 4: PerfectCall Call Analysis (Synchronous Mode)

#include <stdio.h>  
   
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
main()  
{  
   DX_CAP  cap_s;  
   int    	ddd, car;  
   char     *chnam, *dialstrg;  
   
   chnam    = "dxxxB1C1";  
   dialstrg = "L1234";  
   /*  
    *  Open channel  
    */  
   if ((ddd = dx_open( chnam, NULL )) == -1 ) {  
      /* handle error */  
   }  
   
/*  
    *  Delete any previous tones  
    */  
   if ( dx_deltones(ddd) < 0 ) {  
      /* handle error */  
   }  
   
/*  
    *  Change Enhanced call progress default local dial tone  
    */  
   if (dx_chgfreq( TID_DIAL_LCL, 425, 150, 0, 0 ) < 0) {  
      /* handle error */  
   }  
   
   /*  
    *  Change Enhanced call progress default busy cadence  
    */  
   if (dx_chgdur( TID_BUSY1, 550, 400, 550, 400 ) < 0) {  
      /* handle error */  
   }  
   
   if (dx_chgrepcnt( TID_BUSY1, 4 ) < 0) {  
      /* handle error */  
   }  
   
   /*  
    * Now enable Enhanced call progress with above changed settings.  
    */  
   if (dx_initcallp( ddd )) {  
      /* handle error */  
   }  
   
   /*  
    *  Set off Hook  
    */  
   if ((dx_sethook( ddd, DX_OFFHOOK, EV_SYNC )) == -1) {  
      /* handle error */  
   }  
   /*  
    *  Dial  
    */  
   if ((car = dx_dial( ddd, dialstrg,(DX_CAP *)&cap_s, DX_CALLP|EV_SYNC))==-1) {  
      /* handle error */  
   }  
   
   switch( car ) {  
   case CR_NODIALTONE:  
      printf(" Unable to get dial tone\n");  
      break;  
   
   case CR_BUSY:  
      printf(" %s engaged\n", dialstrg );  
      break;  
   
   case CR_CNCT:  
      printf(" Successful connection to %s\n", dialstrg );  
      break;  
   
   default:  
      break;  
   }  
   
   /*  
    *  Set on Hook  
    */  
   if ((dx_sethook( ddd, DX_ONHOOK, EV_SYNC )) == -1) {  
      /* handle error */  
   }  
   dx_close( ddd );  
}

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_BUSY	Channel is busy
EDX_SYSTEM	Error from operating system; use dx_fileerrno( ) to obtain error value

See Also

• dx_stopch( )

Retrieving termination reasons and events for dx_dial( ) with Call Analysis:

• Event Management functions (Voice Software Reference: Standard Runtime Library)
• ATDX_CPTERM( )

Retrieving termination reasons for dx_dial( ) without Call Analysis:

• ATDX_TERMMSK( )

Call Analysis:

• DX_CAP structure
• Call Analysis (Voice Software Reference: Voice Features Guide)
• ATDX_ANSRSIZ( )
• ATDX_CPERROR
• ATDX_FRQDUR( )
• ATDX_FRQDUR2( )
• ATDX_FRQDUR3( )
• ATDX_FRQHZ( )
• ATDX_FRQHZ2( )
• ATDX_FRQHZ3( )
• ATDX_FRQOUT( )
• ATDX_LONGLOW( )
• ATDX_SHORTLOW( )
• ATDX_SIZEHI( )

Click here to contact Dialogic Customer Engineering