dx_rec( )

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

Name:	int dx_rec(chdev,iottp,tptp,mode)
Inputs:	int chdev	valid Dialogic channel device handle
	DX_IOTT *iottp	pointer to I/O Descriptor Table
	DV_TPT *tptp	pointer to Termination Parameter Table Structure
	unsigned short mode	asynchronous/synchronous setting and recording mode bit mask for this record session
Returns:	0 if successful
	-1 if failure
Includes:	srllib.h
	dxxxlib.h
Category:	I/O
Mode:	synchronous/asynchronous

Description

The dx_rec( ) function records voice data from a single channel. The data may be recorded to a combination of data files, memory, or custom devices.

The order in which voice data is recorded is specified in the DX_IOTT structure. The DX_IOTT structure must remain in scope for the duration of the function if running asynchronously.

After dx_rec( ) is called, recording continues until dx_stopch( ) is called, the data requirements specified in the DX_IOTT are fulfilled, or until one of the conditions for termination in the DV_TPT is satisfied. When dx_rec( ) terminates, the current channel's status information, including the reason for termination, can be accessed using Extended Attribute functions.

NOTE:

For a single file synchronous record, dx_recf( ) is more convenient because you do not have to set up a DX_IOTT structure. See the function description of dx_recf( ) for information.

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_RECORD termination event to indicate completion.

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

Termination of asynchronous recording is indicated by a TDX_RECORD event.

Use the SRL Event Management functions to handle the termination event.

After dx_rec( ) terminates, use the ATDX_TERMMSK( ) function to determine the reason for termination.

NOTE:

The DX_IOTT data area must remain in scope for the duration of the function if running asynchronously.

Synchronous Operation

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

Set termination conditions using the DV_TPT structure. This structure is pointed to by the tptp parameter described below. After dx_rec( ) terminates, use the ATDX_TERMMSK( ) function 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( ).
iottp	points to the I/O Transfer Table Structure, DX_IOTT, which specifies the order in which and media onto which the voice data will be recorded. This structure is defined in the chapter on Data Structures and must remain in scope for the duration of the function if using asynchronously.
tptp	points to the Termination Parameter Table Structure, DV_TPT, which specifies termination conditions for recording. Valid termination conditions for this function are listed below: DX_DIGTYPE   Digit termination for user defined tone 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 NOTE: In addition to DV_TPT terminations, the function can fail due to maximum byte count, dx_stopch( ), or end of file. See ATDX_TERMMSK( ) for a full list of termination reasons.
mode	defines the recording mode. One or more of the values listed below may be selected in the bit mask (see Table 15 for record mode combinations). Choose one only: EV_ASYNC: Run dx_rec( ) asynchronously. EV_SYNC: Run dx_rec( ) synchronously (default). Choose one or more: MD_ADPCM: Record using Adaptive Differential Pulse Code Modulation encoding algorithm (4 bits per sample). Recording with ADPCM is the default setting. MD_PCM: Record using Pulse Code Modulation encoding algorithm (8 bits per sample). MD_GAIN: Record with Automatic Gain Control (AGC). Recording with AGC is the default setting. MD_NOGAIN: Record without AGC. RM_ALAW: Record using A-Law. RM_TONE: Transmit a tone before initiating record. If this mode is not selected, no tone will be transmitted (the default setting). RM_SR6: Record using 6KHz sampling rate (6,000 samples per second). This is the default setting. RM_SR8: Record using 8KHz sampling rate (8,000 samples per second).
NOTES: 1. The rate specified in the last record function will apply to the next record function, unless the rate was changed in the parameter DXCH_RECRDRATE using dx_setparm( ). 2. Specifying RM_SR6 or RM_SR8 in mode changes the setting of the parameter DXCH_RECRDRATE. DXCH_RECRDRATE can also be set and queried using dx_setparm( ) and dx_getparm( ). The default setting for DXCH_RECRDRATE is 6KHz. 3. If both MD_ADPCM and MD_PCM are set, MD_PCM will take precedence. If both MD_GAIN and MD_NOGAIN are set, MD_NOGAIN will take precedence. If both RM_TONE and NULL are set, RM_TONE takes precedence. If both RM_SR6 and RM_SR8 are set, RM_SR6 will take precedence. 4. MD_PCM and MD_NOGAIN can be used on D/12x or D/81A boards. 5. When playing pre-recorded data, make sure it is played using the same encoding algorithm and sampling rate used when the data was recorded. 6. dx_rec( ) will run synchronously if you do not specify EV_ASYNC, or if you specify EV_SYNC (default). 7. The D/21E, D/41E, D/41ESC, D/160SC-LS, D/240SC, D/240SC-T1, D/300SC-E1 and D/320SC boards enable the user to select either A-Law or mu-Law encoding of data. The default on the board is set to mu-Law and returns to mu-Law after each record. The A-Law parameters must be passed each time the record function is called. Enable A-Law record by OR'ing the new record, RM_ALAW.

Table 15 shows recording mode selections. The first column of the table lists all possible combinations of record features, and the first row lists each type of encoding algorithm (ADPCM or PCM) and the data-storage rate for each algorithm/sampling rate combination in parenthesis (24 Kbps, 32 Kbps, 48 Kbps, or 64 Kbps).

Select the desired record feature in the first column of the table and move across that row until the column containing the desired encoding algorithm and data-storage rate is reached. The record modes that must be entered in dx_rec( ) are provided where the features row, and encoding algorithm/data-storage rate column intersect. Parameters listed in { } are default settings and do not have to be specified.

Table 15. Record Mode Selections

Feature	ADPCM (24 Kbps)	ADPCM (32 Kbps)	PCM (48 Kbps)	PCM (64 Kbps)
_ AGC _ No Tone	RM_SR6 {MD_ADPCM} {MD_GAIN}	RM_SR8 {MD_ADPCM} {MD_GAIN}	RM_SR6 RM_ALAW* MD_PCM {MD_GAIN}	RM_SR8 RM_ALAW* MD_PCM {MD_GAIN}
_ No AGC _ No Tone	MD_NOGAIN RM_SR6 {MD_ADPCM}	MD_NOGAIN RM_SR8 {MD_ADPCM}	MD_NOGAIN RM_SR6 MD_PCM	MD_NOGAIN RM_SR8 MD_PCM
_ AGC _ Tone	RM_TONE RM_SR6 {MD_ADPCM} {MD_GAIN}	RM_TONE RM_SR8 {MD_ADPCM} {MD_GAIN}	RM_TONE RM_ALAW* RM_SR6 MD_PCM {MD_GAIN}	RM_TONE RM_ALAW* RM_SR8 MD_PCM {MD_GAIN}
_ No AGC _ Tone	MD_NOGAIN RM_TONE RM_SR6 {MD_ADPCM}	MD_NOGAIN RM_TONE RM_SR8 {MD_ADPCM}	MD_NOGAIN MD_PCM RM_SR6 RM_TONE RM_ALAW*	MD_NOGAIN MD_PCM RM_SR8 RM_TONE RM_ALAW*
{ } = Default modes. * = Select if A-Law encoding is required (supported on D/41ESC, D/160SC-LS, D/240SC, D/240SC-T1, D/300SC-E1 and D/320SC boards only).
NOTE: dx_rec( ) will run synchronously if you do not specify EV_ASYNC, or if you specify EV_SYNC (default).

Cautions

None.

Example 1: Using dx_rec( ) in synchronous mode

#include <fcntl.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
#define MAXLEN 10000  
main()  
{  
   DV_TPT tpt;  
   DX_IOTT iott[2];  
   int chdev;  
   char basebufp[MAXLEN];  
   /*  
    * open the channel using dx_open( )  
    */  
   if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {  
     /* process error */  
   }  
   /*  
    * Set up the DV_TPT structures for MAXDTMF  
    */  
   dx_clrtpt(&tpt,1);  
   tpt.tp_type   = IO_EOT;          /* last entry in the table */  
   tpt.tp_termno = DX_MAXDTMF;      /* Maximum digits */  
   tpt.tp_length = 1;               /* terminate on the first digit */  
   tpt.tp_flags  = TF_MAXDTMF;      /* Use the default flags */  
   /*  
    * Set up the DX_IOTT. The application records the voice data to memory  
    * allocated by the user.  
    */  
   iott[0].io_type = IO_MEM|IO_CONT;   /* Record to memory */  
   iott[0].io_bufp = basebufp;         /* Set up pointer to buffer */  
   iott[0].io_offset = 0;              /* Start at beginning of buffer */  
   iott[0].io_length = MAXLEN;         /* Record 10,000 bytes of voice data */  
   iott[1].io_type = IO_DEV|IO_EOT;    /* Record to file, last DX_IOTT  
                                        * entry */  
   iott[1].io_bufp = 0;                /* Set up pointer to buffer */  
   iott[1].io_offset = 0;              /* Start at beginning of buffer */  
   iott[1].io_length = MAXLEN;         /* Record 10,000 bytes of voice  
                                        * data */  
   if((iott[1].io_fhandle = dx_fileopen("file.vox",  
     O_RDWR|O_CREAT|O_TRUNC|O_BINARY,0666)) == -1)  {  
     /* process error */  
   }  
   /* clear previously entered digits */  
   if (dx_clrdigbuf(chdev) == -1) {  
     /* process error */  
   }  
   if (dx_rec(chdev,&iott[0],&tpt,RM_TONE|EV_SYNC) == -1) {  
     /* process error */  
   }  
   /* Analyze the data recorded */  
   .  
   .  
}

Example 2: Using dx_rec( ) in asynchronous mode

#include <stdio.h>  
#include <fcntl.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
#define MAXLEN 10000  
#define MAXCHAN 24  
int record_handler();  
DV_TPT tpt;  
DX_IOTT iott[MAXCHAN];  
int chdev[MAXCHAN];  
char basebufp[MAXCHAN][MAXLEN];  
main()  
{  
   int i, srlmode;  
   char *chname;  
   /* Set SRL to run in polled mode. */  
   srlmode = SR_POLLMODE;  
   if (sr_setparm(SRL_DEVICE, SR_MODEID, (void *)&srlmode) == -1) {  
      /* process error */  
   }  
/* Start asynchronous dx_rec() on all the channels. */  
   for (i=0; i<MAXCHAN; i++) {  
     /* Set chname to the channel name, e.g., dxxxB1C1, dxxxB1C2,... */  
     /*  
      * open the channel using dx_open( )  
      */  
      if ((chdev[i] = dx_open(chname,NULL)) == -1) {  
        /* process error */  
      }  
     /* Using sr_enbhdlr(), set up handler function to handle record  
      * completion events on this channel.  
      */  
      if (sr_enbhdlr(chdev[i], TDX_RECORD, record_handler) == -1) {  
         /* process error */  
      }  
     /*  
      * Set up the DV_TPT structures for MAXDTMF  
      */  
      dx_clrtpt(&tpt,1);  
      tpt.tp_type   = IO_EOT;          /* last entry in the table */  
      tpt.tp_termno = DX_MAXDTMF;      /* Maximum digits */  
      tpt.tp_length = 1;               /* terminate on the first digit */  
      tpt.tp_flags  = TF_MAXDTMF;      /* Use the default flags */  
     /*  
      * Set up the DX_IOTT. The application records the voice data to memory  
      * allocated by the user.  
      */  
      iott[i].io_type = IO_MEM|IO_EOT;  /* Record to memory, last DX_IOTT  
                                         * entry */  
      iott[i].io_bufp = basebufp[i];    /* Set up pointer to buffer */  
      iott[i].io_offset = 0;            /* Start at beginning of buffer */  
      iott[i].io_length = MAXLEN;       /* Record 10,000 bytes voice data */  
      /* clear previously entered digits */  
      if (dx_clrdigbuf(chdev) == -1) {  
        /* process error */  
      }  
      /* Start asynchronous dx_rec() on the channel */  
      if (dx_rec(chdev[i],&iott[i],&tpt,RM_TONE|EV_ASYNC) == -1) {  
        /* process error */  
      }  
   }  
/* Use sr_waitevt to wait for the completion of dx_rec().  
    * On receiving the completion event, TDX_RECORD, control is transferred  
    * to a handler function previously established using sr_enbhdlr().  
    */  
   .  
      .  
}  
              
int record_handler()  
{  
  long term;  
  /* Use ATDX_TERMMSK() to get the reason for termination. */  
  term = ATDX_TERMMSK(sr_getevtdev());  
  if (term & TM_MAXDTMF) {  
     printf("record terminated on receiving DTMF digit(s)\n");  
  } else if (term & TM_NORMTERM) {  
     printf("normal termination of dx_rec()\n");  
  } else {  
     printf("Unknown termination reason: %x\n", term);  
  }  
  /* 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_BADDEV	Invalid Device Descriptor
EDX_BADPARM	Invalid Parameter
EDX_BADIOTT	Invalid DX_IOTT entry
EDX_BADTPT	Invalid DX_TPT entry
EDX_BUSY	Busy executing I/O function
EDX_SYSTEM	Error from operating system; use dx_fileerrno( ) to obtain error value

See Also

Related Functions:

• dx_recf( )
• dx_play( )
• dx_playf( )
• dx_setparm( )
• dx_getparm( )

Setting Order and Location for Voice Data:

• DX_IOTT structure

Retrieving and Handling Record Termination Events:

• Event Management functions the Voice Software Reference: Standard Runtime Library
• ATDX_TERMMSK( )
• DV_TPT

Click here to contact Dialogic Customer Engineering