lm_LearnTone( )

Description | Cautions | Errors | Example | See Also

Name:	long lm_LearnTone(cd, lm_parmp, tn_amplp, dflagp, tn_rangep, tn_tonep, tn_infop, mode)
Inputs:	int cd	channel device handle
	LM_PARM *lm_parmp	pointer to the LM_PARM structure
	TN_AMP *tn_amplp	pointer to the TN_AMP structure
	short *dflagp	pointer to single/dual tone flag
	TN_DESC *tn_rangep	pointer to the TN_DESC structure specifying an optional learning range
	TN_DESC *tn_tonep	pointer to the TN_DESC structure specifying the tone description
	TN_INFOLIST *tn_infolistp	pointer to the TN_INFOLIST structure
	int mode	synchronous
Outputs:	none
Returns:	0 if success -1 if failure
Includes:	srllib.h dxxxlib.h lmodelib.h
Mode:	synchronous
Category:	learn mode
Platform:	Springware

Description

The lm_LearnTone( ) function initiates learn mode to characterize a tone that occurs on the specified channel and to obtain the complete tone description for use with global tone detection or call progress analysis. For more information on global tone detection and call progress analysis, see the Voice Software Reference -- Features Guide.

Parameter	Description
cd	Specifies the channel device handle.
lm_parmp	Points to the LM_PARM data structure which specifies parameters used to characterize the tone. For more information, see the LM_PARM structure in Chapter 6.  Data Structure Reference.
tn_amplp	Points to the TN_AMP data structure. This specifies tone amplitude boundaries that restrict the learning to a specified amplitude range. For example, you can set the amplitude range lower to learn a poor quality tone, although noise may interfere with the results, or you can set the amplitude range higher to detect a high-quality tone. For more information, see TN_AMP structure in Chapter 6.  Data Structure Reference.
dflagp	Specifies the single/dual tone flag, which indicates whether the tone is a single tone or dual tone. This flag must be set manually. When you set this flag manually, make sure you take the voice board dual-tone resolution into account.
	0	If unknown or new tone
	1	single tone (or a dual tone that falls below the dual-tone resolution)
	2	dual tone
tn_rangep	Points to the TN_DESC data structure specifying optional tone learning boundaries to restrict learning to the specified range. For more information, see TN_DESC structure in Chapter 6.  Data Structure Reference. If you set tn_rangep to NULL, this feature is disabled.
tn_tonep	Points to the TN_DESC data structure specifying the tone description. This parameter serves two different purposes: (1) it specifies an existing tone description as optional input to the lm_LearnTone( ) function, and learn mode incorporates this input into the final tone description, and (2) it provides the final tone description that is returned by lm_LearnTone( ). See Requirements section for more information on using this parameter.
tn_infolistp	Points to the TN_INFOLIST structure which contains an array of tone information (TN_INFO data structure). This structure provides the actual frequency and on/off times for each frame (sample) of a detected tone. This information is used primarily for debugging.
	If you set tn_infolistp to NULL, this feature is disabled, and the data is not available for your analysis.
	If you want to analyze the data on which learn mode bases the final tone description, you must allocate an array of memory for saving the tone information of each sample. The required memory is equal to the number of lm_frames (stored in LM_PARM structure) + OFFSET (defined in lmodelib.h) multiplied by the size of the TN_INFO structure. OFFSET allows the library to store tone information for extra frames. The tn_infolistp parameter is also used to learn disconnect tones with more than one on time and more than one off time.
mode	You must set the mode to EV_SYNC for synchronous operation.

Requirements

• Before executing the lm_LearnTone( ) function to learn a new tone, you must set tn_tonep to zeros and also set the dflagp location to indicate a flag value for a single or dual tone. You can use lm_clrdesc( ) to set tn_tonep to zeros (this function clears the LM_DESC structure).
• Before executing the lm_LearnTone( ) function to learn an existing tone, you must specify in tn_tonep the complete tone description to be adjusted and also set the dflagp location to specify a flag value for a single or dual tone.
• If you set the tn_rangep fields to restrict learning to a specified frequency or cadence range, you must set the lm_cadflag field in LM_PARM structure to indicate a cadence or continuous tone.
• The tone to be learned must either be a continuous tone with a minimum duration of one second or a cadence tone with a minimum of five tone-on/off transitions (although 10 transitions will characterize the tone with more accuracy).

  NOTE:

  If you execute this function and 10 seconds elapse without a tone being present for the minimum duration as previously described, the function returns -1 to indicate failure and last error is set EDX_TIMEOUT. Last error can be retrieved using ATDV_LASTERR( ).

 See the Voice Software Reference -- Features Guide for details on global tone detection.
 
The tone description is returned in the TN_DESC structure specified by tn_tonep upon completion of lm_LearnTone( ).

• To learn a disconnect tone with more than one on time and more than one off time, use the TN_INFOLIST structure and find the on time of the longest duration for the tone in the first pass. In the second pass, use lm_parmp parameter, set lm_cnt_min field of LM_PARM structure to 5% less than the on time found in the previous pass, and then call lm_LearnTone( ) again to learn the tone.
• After using the lm_LearnTone( ) function to obtain a complete tone description for the tone, you can use this tone information to change the default tone detection definitions or you can create a new tone and add it to the tone template. For more information, see the global tone detection topic in the Voice Software Reference -- Features Guide.

Cautions

• Before using the lm_LearnTone( ) function, you should clear existing data structure field values using the lm_clramp( ), lm_clrdesc( ), and lm_clrparm( ) functions.
• Learn mode requires that the channel be completely dedicated to its operations while learn mode is active. Simultaneous use of any other signal or tone detection on the channel is not compatible, including DTMF, MF, R2 MF, Socotel, user-defined tone detection, and call progress analysis. However, you can perform these operations on another channel and route the other channel's receive time slot to the time slot of the channel being used for learning.

Errors

For a list of error codes, see Section 5.2.  Learn Mode Error Codes.

Example

/* This example code shows how to "learn" a dial tone. */  
/*  
      The line is set off-hook to generate a dial tone,  
      then lm_LearnTone( ) is called to learn the tone.  
/*  
   
#include <fcntl.h>  
#include <errno.h>  
#include <stdio.h>  
#include "srllib.h"  
#include "dxxxlib.h"  
#include "lmodelib.h"  
#define DEVICE "dxxxB1C1"  
#define ERR  -1  
int lrn_Learn(int lrnDev);  
int main()  
{  
int i,rc;  
int Caller;  
/* learn the dial tone here */  
/* Prepare the scenario for dial tone */  
if ((Caller  = dx_open(DEVICE,(int)NULL)) == ERR)  
{  
//Error occurred in opening DEVICE  
//Handle the error here and return  
//error  
return(ERR);  
}  
if ( dx_sethook(Caller, DX_OFFHOOK, EV_SYNC) == ERR)  
{  
//Error to set off hook  
return(ERR);  
}  
printf("Start learning...............\n");  
if ((rc = lrn_Learn(Caller)) != ERR)  
{  
printf("Finish learning...............\n");  
}  
else  
{  
printf("Error in Learning...\n");  
}  
//reset the channel  
return 0;  
}  
int lrn_Learn(int Dev)  
{  
   LM_PARM parm;  
   TN_AMP amp;  
   TN_DESC desc;  
   short flagDual;  
int ret = -1;  
lm_clrparm(&parm);  
lm_clramp(&amp);  
lm_clrdesc(&desc);  
flagDual = 0;   //Unknown  
//set necessary fields of lm_parm  
parm.lm_frames = 10;  
parm.lm_qualid = QT_LMMID;  
parm.lm_cadflag = 0;  
/* min duration for tone to qualify as continuous */  
parm.lm_cnt_min = 400;    
parm.lm_method = 2;  
ret = lm_LearnTone(Dev, &parm, &amp, &flagDual, NULL, &desc, NULL, EV_SYNC, NULL);  
if( ret == ERR )  
{  
//Learning failed so process and return error  
return(ERR):  
}  
/*process tone ( frequency and cadence) information returned in desc structure. */  
return(ret);  
}

See Also

• lm_clramp( )
• lm_clrdesc( )
• lm_clrparm( )

Click here to contact Telecom Support Resources