dx_play( )

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

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

Description

The dx_play( ) function plays recorded voice data or transfers Analog Display Services Interface (ADSI) data on a specified channel. The voice data may come from any combination of data files, memory, or custom devices.

NOTE:

Although this function can be used for transmitting ADSI data, the dx_RxIottData( ), dx_TxIottData( ), and dx_TxRxIottData( ) functions are recommended as the preferred method.

The order of play and the location of the voice data is specified in the DX_IOTT structure pointed to by iottp. The DX_IOTT structure is described in the chapter on Data Structures.

NOTE:

For a single file synchronous play, dx_playf( ) is more convenient because you do not have to set up a DX_IOTT structure. See the dx_playf( ) function description for more 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_PLAY termination event to indicate completion.

Termination conditions for play are set using the DV_TPT structure. Play continues until all data specified in DX_IOTT has been played, or until one of the conditions specified in DV_TPT is satisfied.

When dx_play( ) terminates, the current channel's status information, including the reason for termination, can be accessed using Extended Attribute functions.

Termination of asynchronous play is indicated by a TDX_PLAY event.

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

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

NOTE:

The DX_IOTT structure 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.

Termination conditions for play are set using the DV_TPT structure. Play continues until all data specified in DX_IOTT has been played, or until one of the conditions specified in DV_TPT is satisfied.

Termination of synchronous play is indicated by a return value of 0. After dx_play( ) terminates, use the ATDX_TERMMSK( ) function to determine the reason for termination.

Analog Display Services Interface (ADSI) Protocol

The following description is the older method for supporting one-way ADSI on Dialogic products. See the dx_RxIottData( ), dx_TxIottData( ), and dx_TxRxIottData( ) functions for the preferred implementation of one-way and two-way ADSI.

The Analog Display Services Interface (ADSI) protocol is used to transmit data to a display-based telephone that is connected to an analog loop start line. An ADSI alert tone is used to verify that Dialogic hardware is connected to an ADSI telephone and to alert the telephone that ADSI data will be transferred.

NOTE:

Check with your telephone manufacturer to verify that your telephone is a true ADSI-compliant device.

Each time a new call is initiated on a channel, send the alert tone to alert the telephone that ADSI data will be transferred.

The ADSI alert tone can be sent and acknowledged, and ADSI data can be transferred using the dx_setparm( ) and dx_play( ) or dx_playf( ) functions. This is accomplished by setting the voice channel parameter DXCH_DTINITSET to DM_A in the dx_setparm( ) function and executing the dx_play( ) or dx_playf( ) function with the PM_ADSIALERT define ORed in the mode parameter.

If the acknowledgment digit is not received from the telephone within 500 ms following the end of the alert tone, the function will return a 0 but the termination mask returned by ATDX_TERMMSK( ) will be TM_MAXTIME to indicate an ADSI protocol error.

NOTE:

The function will return a -1 if a failure is due to a general play error.

If the handshaking and transmission are successful, the function terminates normally with a TM_EOD (End of data reached on playback) termination mask returned by ATDX_TERMMSK( ) to indicate that the operation is complete.

To transfer ADSI data without an alert tone, use the dx_clrdigbuf( ) or dx_getdig( ) function to ensure that there are no pending digits. Transfer ADSI data using the dx_play( ) or dx_playf( ) function with the PM_ADSI define ORed in the mode parameter.

If the transmission is successful, the function terminates normally with a TM_EOD (End of data reached on playback) termination mask returned by ATDX_TERMMSK( ) to indicate that the operation is complete.

The application is responsible for determining whether the message count acknowledgement matches the number of messages that were transmitted and for retransmitting any messages. Use the dx_getdig( ) function with DV_TPT tp_termno set to DX_DIGTYPE to receive the DTMF string 'adx' where 'x' is the message count acknowledgement digit (1 - 5).

NOTE:

The ADSI data must conform to interface requirements described in Bellcore Technical Reference TR-NWT-000030, Voiceband Data Transmission Interface Generic Requirements.

For information about message requirements (how the data should be displayed on the Customer Premise Equipment), see Bellcore Technical Reference TR-NWT-001273, Generic Requirements for an SPCS to Customer Premises Equipment Data Interface for Analog Display Services.

Each technical reference can be obtained from Bellcore by calling 1-800-521-CORE.

Example code for defining and playing an alert tone, receiving acknowledgement of the alert tone, and transferring ADSI data is shown in Example 3.

The dx_play( ) 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 sets the order in which and media from which the voice data will be played. See the chapter on Data Structures for information about the DX_IOTT structure.
tptp	points to the Termination Parameter Table Structure, DV_TPT, which specifies termination conditions for playing. Valid DV_TPT terminating conditions for dx_play( ) are listed below: DX_DIGTYPE   User-defined digit occurred 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 play mode and asynchronous/synchronous mode. One or more of the play mode parameters listed below may be selected in the bit mask for play mode combinations (see Table 14). Choose one only: EV_ASYNC: Run dx_play( ) asynchronously. EV_SYNC: Run dx_play( ) synchronously (default). Choose one or more: MD_ADPCM: Play using Adaptive Differential Pulse Code Modulation encoding algorithm (4 bits per sample). Playing with ADPCM is the default setting. MD_PCM: Play using Pulse Code Modulation encoding algorithm (8 bits per sample). PM_ALAW Play using A-Law. PM_TONE: Transmit a tone before initiating play. If this mode is not selected, no tone will be transmitted. No tone transmitted is the default setting. PM_SR6: Play using 6KHz sampling rate (6,000 samples per second). PM_SR8: Play using 8KHz sampling rate (8,000 samples per second). PM_ADSIALERT: Play using the ADSI protocol with an alert tone preceding play. If ADSI protocol mode is selected, it is not necessary to select any other play mode parameters. PM_ADSIALERT should be ORed with the EV_SYNC or EV_ASYNC parameter in the mode parameter. PM_ADSI: Play using the ADSI protocol without an alert tone preceding play. If ADSI protocol mode is selected, it is not necessary to select any other play mode parameters. If ADSI data will be transferred, PM_ADSI should be ORed with the EV_SYNC or EV_ASYNC parameter in the mode parameter.
NOTES: 1. The rate specified in the last play function will apply to the next play function, unless the rate was changed in the parameter DXCH_PLAYDRATE using dx_setparm( ). 2. Specifying PM_SR6 or PM_SR8 using dx_play( ) changes the setting of the parameter DXCH_PLAYDRATE. DXCH_PLAYDRATE can also be set and queried using dx_setparm( )and dx_getparm( ). The default setting for DXCH_PLAYDRATE is 6KHz. 3. Make sure data is played using the same encoding algorithm and sampling rate used when the data was recorded. 4. MD_PCM can be used on D/12x or D/81A board. 5. 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 play. The A-Law parameters must be passed each time the play function is called. Enable A-Law playback by OR'ing the new play mode, PM_ALAW.

Table 14 shows play mode selections when transmitting or not transmitting a tone before initiating play. The first column of the table lists the two play features (tone or no tone), and the first row lists each type of encoding algorithm (ADPCM or PCM) and data-storage rate for each algorithm/sampling rate combination in parenthesis (24 Kbps, 32 Kbps, 48 Kbps, or 64 Kbps).

Select the desired play feature in the first column of the table and look across that row until the column containing the desired encoding algorithm and data-storage rate is reached. The play modes that must be entered in the mode bit mask are provided where the feature row and encoding algorithm/data-storage rate column intersect. Parameters listed in { } are default settings and do not have to be specified.

NOTE:

If PM_ADSI play mode is selected (not shown in Table 14), the ADSI protocol will be used to transfer ADSI data and it is not necessary to select any other play mode parameters. PM_ADSI should be ORed with the EV_SYNC or EV_ASYNC parameter in the mode parameter.

Table 14. Play Mode Selections

Feature(s)	ADPCM (24 Kbps)	ADPCM (32 Kbps)	PCM (48 Kbps)	PCM (64 Kbps)
_ Tone	PM_TONE PM_SR6 {MD_ADPCM}	PM_TONE PM_SR8 {MD_ADPCM}	PM_TONE PM_ALAW* PM_SR6 MD_PCM	PM_TONE PM_ALAW* PM_SR8 MD_PCM
_ No Tone	PM_SR6 {MD_ADPCM}	PM_SR8 {MD_ADPCM}	PM_SR6 MD_PCM	PM_SR8 MD_PCM
{ } = Default modes. * = Select if file was encoded using A-Law (supported by D/41ESC, D/160SC-LS, D/240SC, D/240SC-T1, D/300SC-E1 and D/320SC boards only).
NOTE: dx_play( ) will run synchronously if you do not specify EV_ASYNC, or if you specify EV_SYNC (default).

Cautions

Whenever dx_play( ) is called, its speed and volume is based on the most recent adjustment made using dx_adjsv( ) or dx_setsvcond( ).

Example 1: Using dx_play( ) in synchronous mode.

/* Play a voice file. Terminate on receiving 4 digits or at end of file*/  
#include <fcntl.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
main()  
{  
   int chdev;  
   DX_IOTT iott;  
   DV_TPT  tpt;  
   DV_DIGIT dig;  
   .  
   .  
   /* Open the device using dx_open( ). Get channel device descriptor in  
    * chdev.  
    */  
   if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {  
     /* process error */  
   }  
   /* set up DX_IOTT */  
   iott.io_type = IO_DEV|IO_EOT;  
   iott.io_bufp = 0;  
   iott.io_offset = 0;  
   iott.io_length = -1;  /* play till end of file */  
   if((iott.io_fhandle = dx_fileopen("prompt.vox", O_RDONLY|O_BINARY))  
   == -1)  {  
     /* process error */  
   }  
   /* set up DV_TPT */  
   dx_clrtpt(&tpt,1);  
   tpt.tp_type   = IO_EOT;          /* only entry in the table */  
   tpt.tp_termno = DX_MAXDTMF;      /* Maximum digits */  
   tpt.tp_length = 4;               /* terminate on four digits */  
   tpt.tp_flags  = TF_MAXDTMF;      /* Use the default flags */  
   /* clear previously entered digits */  
   if (dx_clrdigbuf(chdev) == -1)  {  
     /* process error */  
   }  
/* Now play the file */  
   if (dx_play(chdev,&iott,&tpt,EV_SYNC) == -1) {  
     /* process error */  
   }  
   /* get digit using dx_getdig( ) and continue processing. */  
   .  
   .  
}

Example 2: Using dx_play( ) in asynchronous mode.

#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
#define MAXCHAN 24  
int play_handler();  
DX_IOTT prompt[MAXCHAN];  
DV_TPT tpt;  
DV_DIGIT dig;  
main()  
{  
   int chdev[MAXCHAN], index, index1;  
   char *chname;  
   int i, srlmode, voxfd;  
   /* Set SRL to run in polled mode. */  
   srlmode = SR_POLLMODE;  
   if (sr_setparm(SRL_DEVICE, SR_MODEID, (void *)&srlmode) == -1) {  
      /* process error */  
   }  
   /* initialize all the DX_IOTT structures for each individual prompt */  
   .  
   .  
   /* Open the vox file to play; the file descriptor will be used  
    * by all channels.  
    */  
   if ((voxfd = dx_fileopen("prompt.vox", O_RDONLY|O_BINARY)) == -1) {  
      /* process error */  
   }  
/* For each channel, open the device using dx_open(), set up a DX_IOTT  
    * structure for each channel, and issue dx_play() in asynchronous mode. */  
   for (i=0; i<MAXCHAN; i++) {  
      /* Set chname 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(chname,NULL)) == -1)   {  
         /* process error */  
      }  
      /* Use sr_enbhdlr() to set up handler function to handle play  
      * completion events on this channel.  
      */  
      if (sr_enbhdlr(chdev[i], TDX_PLAY, play_handler) == -1) {  
         /* process error */  
      }  
      /*  
       * Set the DV_TPT structures up for MAXDTMF. Play until one digit is  
       * pressed or the file is played  
       */  
      dx_clrtpt(&tpt,1);  
      tpt.tp_type   = IO_EOT;            /* only 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 */  
      prompt[i].io_type = IO_DEV|IO_EOT; /* play from file */  
      prompt[i].io_bufp = 0;  
      prompt[i].io_offset = 0;  
      prompt[i].io_length = -1;          /* play till end of file */  
      prompt[i].io_nextp = NULL;  
      prompt[i].io_fhandle = voxfd;  
      /* play the data */  
      if (dx_play(chdev[i],&prompt[i],&tpt,EV_ASYNC) == -1) {  
         /* process error */  
      }  
   }  
/* Use sr_waitevt to wait for the completion of dx_play().  
    * On receiving the completion event, TDX_PLAY, control is transferred  
    * to the handler function previously established using sr_enbhdlr().  
    */  
   .  
   .  
}  
int play_handler()  
{  
   long term;  
   /* Use ATDX_TERMMSK() to get the reason for termination. */  
   term = ATDX_TERMMSK(sr_getevtdev());  
   if (term & TM_MAXDTMF) {  
      printf("play terminated on receiving DTMF digit(s)\n");  
   } else if (term & TM_EOD) {  
      printf("play terminated on reaching end of data\n");  
   } else {  
      printf("Unknown termination reason: %x\n", term);  
   }  
   /* Kick off next function in the state machine model. */  
   .  
   .  
   return 0;  
}

Example 3: Defining and playing an alert tone, receiving acknowledgement of the alert tone, and using dx_play( ) to transfer ADSI data.

#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
int parm;  
DV_TPT tpt[2];  
DV_DIGIT digit;  
TN_GEN tngen;  
DX_IOTT iott;  
main(argc,argv)  
   int argc;  
   char* argv[];  
{  
   int chfd;  
   char channame[12];  
   parm = SR_POLLMODE;  
   sr_setparm[SRL_DEVICE, SR_MODEID, &parm);  
   /*  
    * Open the channel using the command line arguments as input  
    */  
   sprintf(channame, "%sC%s", argv[1],argv[2]);  
if (( chfd = dx_open(channame, NULL)) == -1) {  
    printf("Board open failed on device %s\n",channame);  
    exit(1);  
}  
    printf("Devices open and waiting .....\n");  
    /*  
  * Take the phone off-hook to talk to the ADSI phone  
  * This assumes we are connected through a Skutch Box.  
  */  
 if (dx_sethook( chfd, DX_OFFHOOK, EV_SYNC) == -1)  {  
    printf("sethook failed\n");  
    while (1) {  
       sleep(5);  
       dx_clrdigbuf( chfd );  
    printf("Digit buffer cleared ..\n);  
   /*  
    * Generate the alert tone  
    */  
iott.io_type =IO_DEV|IO_EOT;  
    iott.io_fhandle = dx_fileopen("message.asc",O_RDONLY);  
iott.io_length = -1;  
    parm = DM_D  
    if (dx_setparm (chfd, DXCH_DTINITSET, (void *)parm) ==-1){  
        printf ("dx_setparm on DTINITSET failed\n");  
        exit(1);  
    {  
    if (dx_play(chfd,&iott,(DV_TPT *)NULL, PM_ADSIALERT|EV_SYNC) ==-1) {  
       printf("dx_play on the ADSI file failed\n");  
       exit(1);  
    }  
 }
  
 dx_close(chfd);  
 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_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_playf( )
• dx_rec( )
• dx_recf( )
• dx_setparm( ), dx_getparm( )
• dx_RxIottData( )
• dx_TxIottData( )
• dx_TxRxIottData( )

Setting Speed and Volume:

• dx_adjsv( )
• dx_setsvcond( )

Setting Order and Location for Voice Data:

• DX_IOTT structure

Retrieving and Handling Play Termination Events:

• Event Management functions Voice Software Reference: Standard Runtime Library

Click here to contact Dialogic Customer Engineering