dx_getdig( )

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

Name:	int dx_getdig(chdev,tptp,digitp,mode)
Inputs:	int chdev	valid Dialogic channel device handle
	DV_TPT *tptp	pointer to Termination Parameter Table Structure
	DV_DIGIT *digitp	pointer to User Digit Buffer Structure
	unsigned short mode	asynchronous/synchronous setting
Returns:	0 to indicate successful initiation (asynchronous)
	number of digits (+1 for NULL) if successful (synchronous)
	-1 if failure
Includes:	srllib.h
	dxxxlib.h
Category:	I/O
Mode:	synchronous/asynchronous

Description

The dx_getdig( ) function collects digits from a channel digit buffer. Upon termination of the function, the collected digits are written in ASCIIZ format into the local buffer, which is arranged as a DV_DIGIT structure.

The type of digits collected depends on the digit detection mode set by the dx_setdigtyp( ) function (for standard Voice board digits) or by the dx_addtone( ) function (for user-defined digits).

See dx_setdigtyp( ) and dx_addtone( ) and the DV_DIGIT structure in chapter on Data Structures for more information.

Set termination conditions using the DV_TPT structure. This structure is pointed to by the tptp parameter described below.

Asynchronous Operation

To run this function asynchronously set the mode field to EV_ASYNC. When running asynchronously, this function will return 0 to indicate it has initiated successfully, and will generate a TDX_GETDIG termination event to indicate completion. Use the SRL Event Management functions to handle the termination event.

Termination of asynchronous digit collection is indicated by a TDX_GETDIG event. After dx_getdig( ) terminates, use the ATDX_TERMMSK( ) function to determine the reason for termination.

Synchronous Operation

By default, this function runs synchronously. Termination of synchronous digit collection is indicated by a return value greater than 0 that represents the number of digits received (+1 for NULL). Use ATDX_TERMMSK( ) to determine the reason for termination.

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( ).
tptp	points to the Termination Parameter Table Structure, DV_TPT, which specifies termination conditions for this function. Termination conditions are listed below:
	DX_DIGTYPE		User-defined digits
	DX_MAXDTMF		Maximum number of digits received
	DX_MAXSIL		Maximum silence
	DX_MAXNOSIL		Maximum non-silence
	DX_LCOFF		Loop current off
	DX_IDDTIME		Inter-digit delay
	DX_MAXTIME		Function time
	DX_DIGMASK		Digit mask termination
	DX_PMOFF		Pattern match silence off
	DX_PMON		Pattern match silence on
	DX_TONE		Tone-off or Tone-on detection
digitp	points to the User's Digit Buffer Structure, , where collected digits and their types are stored in arrays. The digit types in DV_DIGIT can be one of the following:
	DG_DTMF		DTMF digit
	DG_MF		MF digit
	DG_USER1		User-defined digit
	DG_USER2		User-defined digit
	DG_USER3		User-defined digit
	DG_USER4		User-defined digit
	DG_USER5		User-defined digit
	Refer to the DV_DIGIT structure in the chapter on Data Structures for details.
	See dx_addtone( ) for information about creating user-defined digits.
mode	specifies whether to run dx_getdig( ) asynchronously or synchronously. Specify one of the following:
	EV_ASYNC:	Run dx_getdig( ) asynchronously.
	EV_SYNC:	Run dx_getdig( ) synchronously (default).

The channel's digit buffer contains up to 31 digits, collected on a First-In
First-Out (FIFO) basis. Since the digits remain in the channel's digit buffer until they are overwritten or cleared using dx_clrdigbuf( ), the digits in the channel's buffer may have been received prior to this function call. DG_MAXDIGS is the define for the maximum number of digits that can be returned by a single call to dx_getdig( ).

NOTE:

By default, after the 31st digit, all subsequent digits will be discarded. You can use the dx_setdigbuf( ) function with the mode parameter set to DX_DIGCYCLIC, which will cause all incoming digits to overwrite the oldest digit in the buffer. See the dx_setdigbuf( ) function.

Cautions

1. Some MF digits use approximately the same frequencies as DTMF digits (see Appendix C). Because there is a frequency overlap, if you have the incorrect kind of detection enabled, MF digits may be mistaken for DTMF digits, and vice versa. To ensure that digits are correctly detected, only one kind of detection should be enabled at any time. To set MF digit detection, use the dx_setdigtyp( ) function.
2. A digit that is set to adjust play-speed or play-volume (using dx_setsvcond( )) will not be passed to dx_getdig( ), and will not be used as a terminating condition. If a digit is defined to adjust play and to terminate play, then the play adjustment will take priority.
3. When operating asynchronously, ensure that the digit buffer stays in scope for the duration of the function.
4. The channel must be idle, or the function will return an EDX_BUSY error.
5. If the function is operating synchronously and there are no digits in the buffer, the return value from this function will be 1, which indicates the NULL terminator.

Example 1: Using dx_getdig( ) in synchronous mode

#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
main()  
{  
   DV_TPT tpt[3];  
   DV_DIGIT digp;  
   int chdev, numdigs, cnt;  
   /* open the channel with dx_open( ). Obtain channel device descriptor  
    * in chdev  
    */  
   if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {  
     /* process error */  
   }  
   /* initiate the call */  
   .  
   .  
   /* Set up the DV_TPT and get the digits */  
   dx_clrtpt(tpt,3);  
   tpt[0].tp_type   = IO_CONT;  
   tpt[0].tp_termno = DX_MAXDTMF;       /* Maximum number of digits */  
   tpt[0].tp_length = 4;                /* terminate on 4 digits */  
   tpt[0].tp_flags  = TF_MAXDTMF;       /* terminate if already in buf. */  
   tpt[1].tp_type   = IO_CONT;  
   tpt[1].tp_termno = DX_LCOFF;         /* LC off termination */  
   tpt[1].tp_length = 3;                /* Use 30 ms (10 ms resolution  
                                         * timer) */  
   tpt[1].tp_flags  = TF_LCOFF|TF_10MS; /* level triggered, clear history,  
                                         * 10 ms resolution */  
   tpt[2].tp_type   = IO_EOT;  
   tpt[2].tp_termno = DX_MAXTIME;       /* Function Time */  
   tpt[2].tp_length = 100;              /* 10 seconds (100 ms resolution  
                                         * timer) */  
   tpt[2].tp_flags  = TF_MAXTIME;       /* Edge-triggered */  
   /* clear previously entered digits */  
   if (dx_clrdigbuf(chdev) == -1) {  
     /* process error */  
   }  
if ((numdigs = dx_getdig(chdev,tpt, &digp, EV_SYNC)) == -1) {  
     /* process error */  
   }  
   for (cnt=0; cnt < numdigs; cnt++) {  
      printf("\nDigit received = %c, digit type = %d",  
             	digp.dg_value[cnt], digp.dg_type[cnt]);  
   }  
   /* go to next state */  
   .  
   .  
}

Example 2: Using dx_getdig( ) in asynchronous mode

#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
#define MAXCHAN 24  
int digit_handler();  
DV_TPT stpt[3];  
DV_DIGIT digp[256];  
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 */  
      /* open the channel with dx_open( ). Obtain channel device  
       * descriptor in chdev[i]  
       */  
if ((chdev[i] = dx_open(chnamep,NULL)) == -1) {  
           /* process error */  
       }  
      /* Using sr_enbhdlr(), set up handler function to handle dx_getdig()  
       * completion events on this channel.  
       */  
       if (sr_enbhdlr(chdev[i], TDX_GETDIG, digit_handler) == -1) {  
           /* process error */  
       }  
      /* initiate the call */  
      .  
      .  
      /* Set up the DV_TPT and get the digits */  
       dx_clrtpt(tpt,3);  
       tpt[0].tp_type   = IO_CONT;  
       tpt[0].tp_termno = DX_MAXDTMF;       /* Maximum number of digits */  
       tpt[0].tp_length = 4;                /* terminate on 4 digits */  
       tpt[0].tp_flags  = TF_MAXDTMF;       /* terminate if already in buf*/  
       tpt[1].tp_type   = IO_CONT;  
       tpt[1].tp_termno = DX_LCOFF;         /* LC off termination */  
       tpt[1].tp_length = 3;                /* Use 30 ms (10 ms resolution  
                                             * timer) */  
       tpt[1].tp_flags  = TF_LCOFF|TF_10MS; /* level triggered, clear  
                                             * history, 10 ms resolution */  
       tpt[2].tp_type   = IO_EOT;  
       tpt[2].tp_termno = DX_MAXTIME;        /* Function Time */  
       tpt[2].tp_length = 100;               /* 10 seconds (100 ms resolution  
                                             * timer) */  
       tpt[2].tp_flags  = TF_MAXTIME;        /* Edge triggered */  
      /* clear previously entered digits */  
       if (dx_clrdigbuf(chdev[i]) == -1) {  
          /* process error */  
       }  
       if (dx_getdig(chdev[i], tpt, &digp[chdev[i]], EV_ASYNC) == -1) {  
          /* process error */  
       }  
   }  
 /* Use sr_waitevt() to wait for the completion of dx_getdig().  
  * On receiving the completion event, TDX_GETDIG, control is transferred  
  * to the handler function previously established using sr_enbhdlr().  
  */  
      .  
         .  
}  
int digit_handler()  
{  
   int chfd;  
   int cnt, numdigs;  
   chfd = sr_getevtdev();  
   numdigs = strlen(digp[chfd].dg_value);  
   for(cnt=0; cnt < numdigs; cnt++) {  
      printf("\nDigit received = %c, digit type = %d",  
                         digp[chfd].dg_value[cnt], digp[chfd].dg_type[cnt]);  
   }  
   /* Kick off next function in the state machine model. */  
   .  
   .  
   return 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_BADTPT	Invalid DV_TPT entry
EDX_BUSY	Channel busy
EDX_SYSTEM	Error from operating system; use dx_fileerrno( ) to obtain error value

See Also

Setting User-Defined Digits:

• dx_addtone( )
• dx_setdigtyp( )

Collecting Digits:

• DV_DIGIT
• dx_sethook( )

Click here to contact Dialogic Customer Engineering