Learn Mode and Tone Set File API Software Reference

Learn Mode and Tone Set File API Software Reference
Dialogic® Learn Mode and
Tone Set File API
Software Reference
Copyright © 2003-2009 Dialogic Corporation
05-2069-002
Copyright © 2003-2009 Dialogic Corporation. All Rights Reserved. You may not reproduce this document in whole
or in part without permission in writing from Dialogic Corporation at the address provided below.
All contents of this document are furnished for informational use only and are subject to change without notice and
do not represent a commitment on the part of Dialogic Corporation or its subsidiaries (“Dialogic”). Reasonable
effort is made to ensure the accuracy of the information contained in the document. However, Dialogic does not
warrant the accuracy of this information and cannot accept responsibility for errors, inaccuracies or omissions that
may be contained in this document.
INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH DIALOGIC® PRODUCTS. NO
LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY
RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN A SIGNED AGREEMENT
BETWEEN YOU AND DIALOGIC, DIALOGIC ASSUMES NO LIABILITY WHATSOEVER, AND DIALOGIC
DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF DIALOGIC
PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR
PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY INTELLECTUAL PROPERTY RIGHT OF A
THIRD PARTY.
Dialogic products are not intended for use in medical, life saving, life sustaining, critical control or safety systems,
or in nuclear facility applications.
Due to differing national regulations and approval requirements, certain Dialogic products may be suitable for use
only in specific countries, and thus may not function properly in other countries. You are responsible for ensuring
that your use of such products occurs only in the countries where such use is suitable. For information on specific
products, contact Dialogic Corporation at the address indicated below or on the web at www.dialogic.com.
It is possible that the use or implementation of any one of the concepts, applications, or ideas described in this
document, in marketing collateral produced by or on web pages maintained by Dialogic may infringe one or more
patents or other intellectual property rights owned by third parties. Dialogic does not provide any intellectual
property licenses with the sale of Dialogic products other than a license to use such product in accordance with
intellectual property owned or validly licensed by Dialogic and no such licenses are provided except pursuant to a
signed agreement with Dialogic. More detailed information about such intellectual property is available from
Dialogic’s legal department at 9800 Cavendish Blvd., 5th Floor, Montreal, Quebec, Canada H4M 2V9. Dialogic
encourages all users of its products to procure all necessary intellectual property licenses required to
implement any concepts or applications and does not condone or encourage any intellectual property
infringement and disclaims any responsibility related thereto. These intellectual property licenses may differ
from country to country and it is the responsibility of those who develop the concepts or applications to be
aware of and comply with different national license requirements.
Dialogic, Dialogic Pro, Brooktrout, Diva, Cantata, SnowShore, Eicon, Eicon Networks, NMS Communications,
NMS (stylized), Eiconcard, SIPcontrol, Diva ISDN, TruFax, Exnet, EXS, SwitchKit, N20, Making Innovation
Thrive, Connecting to Growth, Video is the New Voice, Fusion, Vision, PacketMedia, NaturalAccess,
NaturalCallControl, NaturalConference, NaturalFax and Shiva, among others as well as related logos, are either
registered trademarks or trademarks of Dialogic Corporation or its subsidiaries. Dialogic's trademarks may be used
publicly only with permission from Dialogic. Such permission may only be granted by Dialogic’s legal department
at 9800 Cavendish Blvd., 5th Floor, Montreal, Quebec, Canada H4M 2V9. Any authorized use of Dialogic's
trademarks will be subject to full respect of the trademark guidelines published by Dialogic from time to time and
any use of Dialogic’s trademarks requires proper acknowledgement.
Windows is a registered trademark of Microsoft Corporation in the United States and/or other countries. Other
names of actual companies and product mentioned herein are the trademarks of their respective owners.
Publication Date: February 2009
Document Number: 05-2069-002
2
Table of Contents
Revision History ................................................................................................... 7
About This Publication ........................................................................................ 9
Purpose................................................................................................................... 9
Applicability........................................................................................................... 9
Intended Audience ................................................................................................. 9
How This Guide Is Organized ............................................................................. 10
Related Information ............................................................................................. 10
1. Product Description ...................................................................................... 13
1.1. Introduction to Dialogic® Learn Mode and Tone Set File API Libraries..... 13
1.2. Features of Dialogic® Learn Mode and Tone Set File API Libraries........... 14
2. Function Summary by Category ................................................................. 15
2.1. Overview...................................................................................................... 15
2.2. Learn Mode Functions ................................................................................. 15
2.3. Tone Set File Functions ............................................................................... 15
2.3.1. I/O Functions....................................................................................... 16
2.3.2. Tone Set Handling Functions .............................................................. 16
2.3.3. Tone Set Consolidation Functions ...................................................... 17
3. Application Development Guidelines .......................................................... 19
3.1. Mode of Operation ....................................................................................... 19
3.2. Learn Mode Requirements and Limitations................................................. 19
3.3. Hints for Using Learn Mode ........................................................................ 20
3.4. Understanding Tone Sets and Tone Set Files .............................................. 21
3.5. Creating Tone Sets and Tone Set Files ........................................................ 22
3.6. Tone Set Files and pbxsetting.txt ................................................................. 24
3.6.1. Rules for Using pbxsetting.txt............................................................. 25
3.6.2. Examples of pbxsetting.txt .................................................................. 25
4. Building Applications ................................................................................... 27
4.1. Include Files................................................................................................. 27
4.2. Required Libraries........................................................................................ 27
5. Function Reference ....................................................................................... 29
lm_clramp( ) - clears the tone amplitude structure............................................... 30
lm_clrdesc( ) - clears the tone description structure............................................. 32
lm_clrparm( ) - clears the learn mode parameters structure................................. 34
lm_LearnTone( ) - initiates learn mode................................................................ 36
tsf_ActivateFile( ) - activates the tone set file...................................................... 43
3
Dialogic® Learn Mode and Tone Set File API Software Reference
tsf_AddToneSet( ) - adds a tone set entry............................................................ 46
tsf_ClearConsolidationOptions( ) - clears consolidation structure ...................... 49
tsf_ClearDefaultToneSetToConsolidate( ) - clears the default tone information. 52
tsf_CloseFile( ) - closes an open tone set file....................................................... 55
tsf_ConsolidateToneSets( ) - consolidates tone sets ............................................ 57
tsf_DeleteToneSet( ) - deletes a tone set entry..................................................... 60
tsf_DuplicateToneSet( ) - duplicates a tone set entry........................................... 62
tsf_GetConsolidatedToneSet( ) - returns consolidated tone information............. 65
tsf_GetConsolidatedToneSetKeys( ) - returns keys of tone sets consolidated..... 68
tsf_GetDefaultToneSetInConsolidation( ) - returns info on default tone set ....... 71
tsf_GetFileInformation( ) - gets updated information about a tone set file.......... 74
tsf_GetNumberOfToneSets( ) - returns the number of tone sets.......................... 77
tsf_GetNumberOfToneSetsConsolidated( ) - returns number of consolidated .... 79
tsf_GetToneSet( ) - returns tone information....................................................... 81
tsf_GetToneSetKeys( ) - returns the keys of the tone sets ................................... 84
tsf_GetToneSetName( ) - returns the tone set name ............................................ 87
tsf_ModifyToneSet( ) - modifies a tone set ......................................................... 89
tsf_OpenFile( ) - opens the tone set file ............................................................... 92
tsf_SaveFile( ) - saves tone set data ..................................................................... 94
tsf_SetDefaultToneSetToConsolidate( ) - adds default tone set information ...... 96
6. Error Codes ................................................................................................... 99
6.1. Learn Mode Error Codes.............................................................................. 99
6.2. Tone Set File Error Codes.......................................................................... 100
7. Data Structure Reference ........................................................................... 103
7.1. Data Structures Overview .......................................................................... 103
7.2. LM_PARM: Learn Mode Parameters ........................................................ 103
7.3. TN_AMP: Tone Amplitude ....................................................................... 108
7.4. TN_DESC: Tone Description .................................................................... 110
7.5. TN_DUR: Tone Duration .......................................................................... 111
7.6. TN_FREQ: Tone Frequency ...................................................................... 113
7.7. TN_INFO: Tone Information..................................................................... 115
7.8. TN_INFOLIST: Tone Information List ..................................................... 116
7.9. TONE_INFO.............................................................................................. 117
7.10. TONESET_ID.......................................................................................... 118
7.11. TONESETINFO....................................................................................... 118
7.12. TSF_CONSOLIDATIONOPTIONS ....................................................... 119
7.13. TSF_FILE_INFO ..................................................................................... 119
Glossary ............................................................................................................ 121
Index.................................................................................................................. 127
4
List of Tables
Table 1. LM_PARM Structure.......................................................................... 104
Table 2. TN_AMP Structure ............................................................................. 109
Table 3. TN_DESC Structure ........................................................................... 110
Table 4. TN_DUR Structure ............................................................................. 112
Table 5. TN_FREQ Structure ........................................................................... 114
Table 6. TN_INFO Structure ............................................................................ 116
Table 7. TN_INFOLIST Structure.................................................................... 117
Table 8. TONE_INFO Structure ....................................................................... 117
Table 9. TONESET_ID Structure ..................................................................... 118
Table 10. TONESETINFO Structure................................................................ 119
Table 11. TSF_CONSOLIDATIONOPTIONS Structure................................. 119
Table 12. TSF_FILE_INFO Structure .............................................................. 120
5
Dialogic® Learn Mode and Tone Set File API Software Reference
6
Revision History
This revision history summarizes the changes made in each published version of
this document.
Document No.
Publication
Date
Description of Revisions
05-2069-002
February 2009
Made global changes to reflect Dialogic
brand.
Added support for Dialogic® Host
Media Processing (HMP) Software.
05-2069-001
November 2003
Initial version of document.
7
Dialogic® Learn Mode and Tone Set File API Software Reference
8
About This Publication
Purpose
This document provides a reference to the Dialogic® Learn Mode and Tone Set
File (TSF) API library functions and data structures. It also discusses
programming guidelines for these APIs. The Learn Mode and TSF APIs are
supported on Dialogic® Springware Boards and Dialogic® DM3 Boards for use in
the Linux and Windows® operating systems.
Applicability
This document is applicable to Dialogic® Host Media Processing (HMP)
Software and to Dialogic® System Release Software for Linux and Windows®
operating systems.
Check the Release Guide and Release Update for your software release to
determine whether this document is supported, and for information on supported
hardware.
Intended Audience
This document is intended for the following audience:
•
Distributors
•
System Integrators
•
Toolkit Developers
•
Independent Software Vendors (ISVs)
•
Value Added Resellers (VARs)
•
Original Equipment Manufacturers (OEMs)
•
End Users
9
Dialogic® Learn Mode and Tone Set File API Software Reference
How This Guide Is Organized
The information in this guide is organized as follows:
Chapter 1 provides an overview of the Dialogic® Learn Mode and Tone Set File
software.
Chapter 2 summarizes the Dialogic® Learn Mode and Tone Set File API library
functions.
Chapter 3 provides programming guidelines for developing an application to
learn tones and create tone set files.
Chapter 4 discusses compiling and linking requirements such as include files and
library files.
Chapter 5 provides an alphabetical reference to the Dialogic® Learn Mode and
Tone Set File API library functions.
Chapter 6 describes error codes that may be returned by the API library
functions.
Chapter 7 provides an alphabetical reference to the data structures used by the
API library functions.
A Glossary and Index are provided at the end of this guide for reference.
Related Information
Refer to the following documents and websites for more information:
•
Release Guide and Release Update for your Dialogic® HMP Software or
Dialogic® System Release Software
•
http://www.dialogic.com/manuals/ (for Dialogic® product documentation)
•
http://www.dialogic.com/support/ (for Dialogic technical support)
•
http://www.dialogic.com/ (for Dialogic® product information)
10
About This Publication
For definitions of domestic and international line status tones, see the following
publications, respectively:
•
Bellcore LATA Switching Systems Generic Requirements (LSSGR):
Signaling, Section 6, Issue 2, Revision 1, December 1988 (TR-TSY-000506)
•
International Telegraph and Telephone Consultative Committee (CCITT),
Blue Book Volume II, Fascicle II.2: Telephone Network and ISDN –
Operation, Numbering, Routing and Mobile Service, Recommendations
E.100–E.333, Study Group II, November 1988 (ISBN 92-61-03261-3).
Additional country-specific line status tones are defined by the NET 4
contributions.
11
Dialogic® Learn Mode and Tone Set File API Software Reference
12
1. Product Description
1.1. Introduction to Dialogic® Learn Mode and Tone Set
File API Libraries
Integrating an interactive voice response (IVR), voicemail, or auto attendant
system with one or more PBX or key system switches presents a challenge. The
challenge occurs because each switch does not always produce standard
telephone company call progress tones such as busy, dial tone, or ringback. In
such cases, a computer telephony system may be unable to recognize the state of
a call and unable to perform functions such as transferring or disconnecting a call.
To handle this situation, the standard call progress tone detection algorithms
within a telecom board must know these custom frequencies and cadences. The
Dialogic® Learn Mode API and Tone Set File API are designed to address the
PBX integration process. These APIs can make it quicker and easier to integrate
Dialogic® Boards with virtually any telephone switch or Public Switched
Telephone Network (PSTN), and can eliminate the need to manually define and
test the frequency and cadence characteristics of call progress tones.
The Dialogic® PBX Expert utility is available for learning tones. This utility uses
the Learn Mode API and the Tone Set File API to accomplish PBX tone learning
and tone set file management. The Learn Mode and Tone Set File API libraries
provide the flexibility to integrate tone learning capability directly in computer
telephony applications. The PBX Expert utility is provided with the Dialogic®
Host Media Processing (HMP) Software and Dialogic® System Release Software.
By saving a set of tone characteristics (dial tone, busy, ringback, reorder, and
disconnect) for each unique switch, the Tone Set File API enables a Dialogic®
Board to detect their call progress tones, allowing the board to recognize the state
of a call and perform appropriate functions. Additionally, it is possible to edit and
implement tone characteristics without recompiling application-level software.
The Tone Set File API can also be used to combine up to 10 sets of tone
characteristics into a single, consolidated tone set. That means the Dialogic®
Board can recognize call progress tones from up to 10 unique sources using this
consolidated tone set file.
13
Dialogic® Learn Mode and Tone Set File API Software Reference
The Learn Mode software works together with the Dialogic® Voice library global
tone detection feature to learn tones and capture tone descriptions. For more
information on global tone detection, see the Dialogic® Voice API Programming
Guide.
The Learn Mode and Tone Set File API libraries supply functions that interface
with the Dialogic® voice driver. These libraries are supported on specific boards
and run on Linux and Windows® operating systems. See the Release Guide and
Release Update accompanying the Dialogic® HMP Software or Dialogic® System
Release Software for information on hardware support.
1.2. Features of Dialogic® Learn Mode and Tone Set File
API Libraries
Features of the Dialogic® Learn Mode and Tone Set File API libraries include the
following:
•
ability to characterize a call progress tone from a PBX, key system, or PSTN
and store that information
•
ability to change default tone definitions that are provided by the Dialogic®
Voice library
•
ability to create a new tone definition and add it to the tone template for use
with call progress analysis
•
ability to store an unlimited number of tone sets on your system (subject to
storage constraints)
•
ability to combine up to 10 sets of tone characteristics into a single,
consolidated tone set
•
ability to support up to 10 sets of tone characteristics (that is, for up to 10
different PBX or key systems)
14
2. Function Summary by Category
2.1. Overview
This chapter describes the categories in which the Dialogic® Learn Mode and
Tone Set File API functions can be grouped.
2.2. Learn Mode Functions
Use Learn Mode functions to initiate and operate learn mode to obtain a tone
description.
The following Learn Mode functions are available:
Function Name
Definition
lm_clramp( )
• clears the tone amplitude structure
(TN_AMP) for the lm_LearnTone( )
function
lm_clrdesc( )
• clears the tone description structure
(TN_DESC) for the lm_LearnTone( )
function. The associated tone frequency
structure (TN_FREQ) and tone duration
structure (TN_DUR) are also cleared.
lm_clrparm( )
• clears the learn mode parameters structure
(LM_PARM) for the lm_LearnTone( )
function
lm_LearnTone( )
• 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
2.3. Tone Set File Functions
Use Tone Set File functions to manage tone set data and tone set files.
15
Dialogic® Learn Mode and Tone Set File API Software Reference
The tone set file functions can be categorized as follows:
•
I/O functions
•
tone set handling functions
•
tone set consolidation functions
2.3.1. I/O Functions
The following functions are used in file handling:
Function Name
Definition
tsf_ActivateFile( )
• activates the tone set file
tsf_CloseFile( )
• closes an open tone set file
tsf_GetFileInformation( )
• retrieves updated information about
a tone set file after tsf_OpenFile( )
is called
tsf_OpenFile( )
• opens the tone set file specified
tsf_SaveFile( )
• saves tone set data to a tone set file
2.3.2. Tone Set Handling Functions
The following functions are used in handling tone sets:
Function Name
Definition
tsf_AddToneSet( )
• adds a tone set entry to the tone set
file
tsf_DeleteToneSet( )
• deletes a tone set entry from the
tone set file
tsf_DuplicateToneSet( )
• duplicates a tone set in the tone set
file
tsf_GetNumberOfToneSets( )
• convenience function that returns
the number of tone sets in the open
tone set file
tsf_GetToneSet( )
• returns tone set information
16
2. Function Summary by Category
Function Name
Definition
tsf_GetToneSetKeys( )
• convenience function that returns
the keys (identifiers) of the tone sets
in the tone set file
tsf_GetToneSetName( )
• returns the tone set ID or tone set
name (typically the PBX or key
system manufacturer name and
model number)
tsf_ModifyToneSet( )
• changes the parameters of a tone set
2.3.3. Tone Set Consolidation Functions
The following functions are used in consolidating tone sets:
Function Name
Definition
tsf_ClearConsolidationOptions( )
• clears the consolidation options
structure
tsf_ClearDefaultToneSetToConsolidate( )
• clears the default tone information
for consolidation and sets all values
to 0
tsf_ConsolidateToneSets( )
• consolidates the tone sets marked
for consolidation
tsf_GetConsolidatedToneSet( )
• returns tone set information of the
consolidated tone set
tsf_GetConsolidatedToneSetKeys( )
• returns keys of tone sets
consolidated in an array
tsf_GetDefaultToneSetInConsolidation( )
• returns default tone set values
included in consolidation
tsf_GetNumberOfToneSetsConsolidated( )
• returns number of tone sets
included in consolidation
tsf_SetDefaultToneSetToConsolidate( )
• sets values of the default tone set to
be included in the consolidation
process
17
Dialogic® Learn Mode and Tone Set File API Software Reference
18
3. Application Development
Guidelines
3.1. Mode of Operation
The Dialogic® Learn Mode and Tone Set File API library functions operate in
synchronous (blocking) mode. Synchronous functions perform an action on a
device and do not return control to the calling process until the action is
completed.
3.2. Learn Mode Requirements and Limitations
The following requirements apply to learn mode:
•
The tone to be learned must be either a continuous tone or a repeating tone.
•
To learn a continuous tone, the tone must occur continuously for a minimum
duration of one second without any other tone being present. (If another tone
is present, you may be able to exclude it from being learned by restricting the
lm_LearnTone( ) learning parameters specified in tn_rangep.) The duration
of the tone is configurable in the LM_PARM structure.
•
To learn a tone having a cadence, several repetitions of the tone must occur
without any other tone being present. The cadence must contain at least five
tone-on/tone-off transitions, although 10 transitions will characterize the tone
with more accuracy.
The following limitations apply to learn mode:
•
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.
•
Since learn mode can characterize either a tone that has several cadence
repetitions or a tone that is continuous, it is invalid to use learn mode to
characterize the following:
•
A sequence of different tones, such as a SIT tri-tone sequence or a PBX
warble tone (use call progress analysis to detect SIT tones)
19
Dialogic® Learn Mode and Tone Set File API Software Reference
•
Short duration, single instance tones that do not repeat, such as a “bong”
tone (unless the duration is long enough to qualify as a continuous tone)
In these cases, to characterize a tone that occurs in a single instance or is one
in a sequence, you must simulate the repetitions by recording the tone and
then playing the recorded tone repeatedly. (The simulation will be more
robust if you concatenate multiple recordings of the tone.)
•
Learn mode can accurately characterize almost all tones having a complex
cadence. In the laboratory, it is possible to create a situation where the initial
definition of a complex cadence overlaps with another similar tone
description. In this unusual case, adjusting the tone description can correct
the problem. Note that such a conflict is extremely rare.
3.3. Hints for Using Learn Mode
The following hints are provided to help in using learn mode:
•
If your final tone description is being falsely triggered by noise or voice, you
can:
•
Change the qualification ID (by setting the lm_qualid field in the
LM_PARM structure) for more immunity to noise and less sensitivity to
the tone. See Section 7.2. LM_PARM: Learn Mode Parameters for
more information on how to set this value.
•
Increase the repetition count if the tone has a simple cadence. (If you
increase the repetition count and then fail to detect the tone, your tone
description may be for a complex-cadence tone; in this case, you must
set the repetition count to 1.)
•
To learn a particular tone, you may need to change the learning parameters.
For example, when learning a cadence tone that contains a limited number of
repetitions, you can reduce the number of learning samples or cadence
repetitions specified in the lm_frames field in the LM_PARM structure.
Another example is when learning a short continuous tone, you can reduce
the continuous tone minimum on-time specified in the lm_cnt_min field in
the LM_PARM structure.
•
If you get an EDX_TNINFO error, which means there is not enough tone
information to do the learning, try increasing the number of frames in the
lm_frames field in the LM_PARM structure. If you get an
EDX_TNINVALID error, which means an invalid tone was detected, try
20
3. Application Development Guidelines
lowering the lm_qualid field in the LM_PARM structure. Learn mode
requires that at least 5 frames/samples be used.
•
The Learn Mode library uses 4 seconds as the default duration for learning
continuous tones (rather than the minimum of 1 second). There are two
reasons why the default duration for learning a continuous tone is 4 seconds:
one is for learning the tone and the other is for using the final tone
description for detection.
A 4-second minimum duration is needed for learn mode to determine
whether the tone is cadence or continuous (rarely does a cadence tone have a
4-second tone-on duration). To learn a continuous tone in less than 4
seconds, you can set the lm_cadflag field in the LM_PARM structure to 2 to
specify a continuous tone, and then set the lm_cnt_min field to a value under
400 (10 ms units).
A 4-second minimum duration may also be needed when using the final tone
description for the continuous tone for detection. To prevent the continuous
tone final tone description from detecting a cadence tone that has the same
frequency range, the tone-on duration for the continuous tone must be greater
than the tone-on duration for the cadence tone. A 4-second minimum
duration helps prevent a detection overlap with a cadence tone. In this case,
you may want to set a short minimum on-time to learn the frequency of the
continuous tone, and then increase the on-time when you build the tone for
detection. The continuous tone on-time must be greater than any cadence
tone on-time of the same frequency.
3.4. Understanding Tone Sets and Tone Set Files
A tone set file is a binary file consisting of the following parts:
•
tone sets. Each tone set contains tone information for up to 10 different call
progress tones. These tones include three dial tones (local dial tone,
international dial tone, extra dial tone), two ringback tones, two busy tones, a
disconnect tone, and two fax tones. Each tone set is typically associated with
a specific PBX or key system.
•
a consolidated tone set within the tone set file. Up to 10 tone sets can be
selected for consolidation. Note that a tone set file can contain more than 10
tone sets; however, only 10 tone sets can be selected for consolidation at a
time. Consolidation lets you combine several PBX tone set definitions and
compute a single tone set, which can detect the tones of all PBXs associated
with the consolidation.
21
Dialogic® Learn Mode and Tone Set File API Software Reference
•
a binary flag that indicates whether the tone set file contains a valid
consolidated tone set
You can have only one active tone set file per system and one consolidated tone
set per tone set file.
3.5. Creating Tone Sets and Tone Set Files
The Dialogic® Learn Mode API and Tone Set File API are designed to make it
easier to manage the unique call progress tones produced by PBXs, key systems,
and PSTNs. The tone sets and tone set file contain information on these unique
call progress tones. These new call progress tone definitions can in turn be used
by the call progress analysis feature in a computer telephony application.
Call progress analysis is a feature of the Dialogic® Voice API library that uses a
combination of frequency and cadence detection to identify call progress tones to
determine the status of a call. For detailed information on call progress analysis,
see the Dialogic® Voice API Programming Guide.
Applications can learn tone characteristics using the functions from the Learn
Mode API library. Information on several different tones forms one tone set.
Tone sets can be written to a tone set file using the Tone Set File API. It is an
application’s responsibility to consolidate different tone sets and save the
consolidated tone sets using the Tone Set File API functions. To activate the
consolidated tone sets on a board, use Voice API library functions. The process
for this last step differs depending on the board type (Dialogic® DM3 Board or
Dialogic® Springware Board) and the operating system (Linux or Windows®.)
For example, let’s say you already have a tone set file containing five PBX tone
sets, and you want to add another tone set for a new switch, for which there is no
tone set definition. Use the following guidelines to manage unique call progress
tones produced by PBXs, key systems, and PSTNs:
NOTE: Not all function calls and data structures required for an application are
mentioned here. These guidelines help provide the general flow of the
application.
1.
Open the tone set file containing existing tone sets using tsf_OpenFile( ).
2.
Learn the new tone characteristics using the Learn Mode API.
22
3. Application Development Guidelines
3.
Add the learned tones to your tone set file using tsf_AddToneSet( ) (creating
a new tone set).
4.
Add additional tone sets as required using tsf_AddToneSet( ).
5.
Perform file operations on your tone set file, as necessary, such as modifying,
deleting, and duplicating a tone set.
6.
Decide which tone sets to include in the consolidated tone set.
7.
As a precaution, before consolidating a tone set, clear the old default tone set
using tsf_ClearDefaultToneSetToConsolidate( ).
8.
(Optional) Set the new default tone set using
tsf_SetDefaultToneSetToConsolidate( ).
9.
As a precaution, clear the consolidation options structure using
tsf_ClearConsolidationOptions( ).
10. Consolidate specified tone sets in the tone set file using
tsf_ConsolidateToneSets( ). Even if only one tone set will be activated, you
must call this function. The consolidated tone set can be used to replace the
Voice API library’s default tone set definitions.
11. Save the tone set data using tsf_SaveFile( ).
12. To activate the new tone set file for use with call progress analysis, call
tsf_ActivateFile( ).
13. Close the tone set file using tsf_CloseFile( ).
14. On Dialogic® DM3 Boards, choose one of the following ways to enable and
load the new tones on the board:
•
Stop the board and restart it from the Dialogic® Configuration Manager
(DCM).
OR
•
Retrieve the new tone information from the tone set file by calling
tsf_GetConsolidatedToneSet( ). Then use the information for each tone
to change the default tone definition on the board by calling
dx_querytone( ), dx_deletetone( ), and dx_createtone( ).
15. On Dialogic® Springware Boards, close the channels and re-open them using
dx_open( ). Opening a channel device with dx_open( ) after activating a
tone set file (via tsf_ActivateFile( )) will enable the use of the consolidated
tone set (and its tone definitions) from the tone set file. Then use
23
Dialogic® Learn Mode and Tone Set File API Software Reference
dx_initcallp( ) to initialize enhanced call progress analysis and send the new
tone definitions to the board.
On Springware Boards running Linux, this function reads the consolidated
tone set from the tone set file according to settings in the pbxsetting.txt file.
For more information, see Section 3.6. Tone Set Files and pbxsetting.txt.
On Springware Boards running Windows®, this function reads the
consolidated tone set from the tone set file according to settings in DCM.
The tsf_ActivateFile( ) function updates the TSFFileSupport and
TSFFileName fields in DCM.
16. To perform call progress analysis on Springware Boards, use the Voice API
library. For more information on the dx_ Voice API functions, see the
Dialogic® Voice API Library Reference. On DM3 Boards, use the Dialogic®
Global Call API library. For more information, see the Dialogic® Global Call
API Library Reference and the Global Call Technology Guide for the
protocol you are using.
3.6. Tone Set Files and pbxsetting.txt
The pbxsetting.txt file is used on the Linux operating system only. The
pbxsetting.txt file is located in the directory /usr/dialogic/cfg.
The purpose of the pbxsetting.txt file is:
•
To indicate whether a tone set file is supported (DLGCTSFSUPPORT)
•
If the tone set file is supported, to provide its location and name
(DLGCTSFFILEPATH)
•
To indicate whether disconnect supervision is enabled
(DLGCDISCONNECTTONE)
There should only be three lines in the pbxsetting.txt file. The values
DLGCTSFSUPPORT, DLGCTSFFILEPATH, and DLGCDISCONNECTTONE
comprise the file. These three values should be the first three lines of the file, as
all other lines after the first three lines are ignored. No commenting is supported
in the first three lines.
24
3. Application Development Guidelines
3.6.1. Rules for Using pbxsetting.txt
If DLGCTSFSUPPORT = YES, then a tone set file is used to configure call
progress analysis on the system. If TSF is enabled, then DLGCTSFFILEPATH
must contain the path and name of the tone set file.
If DLGCTSFSUPPORT = NO, then TSF is not used to configure call progress
analysis, and the value of DLGCTSFFILEPATH is ignored.
If DLGCDISCONNECTTONE = YES, then disconnect tone supervision is
enabled.
If DLGCDISCONNECTTONE = NO, then disconnect tone supervision is
disabled.
3.6.2. Examples of pbxsetting.txt
This section provides examples of settings in pbxsetting.txt.
Example 1
DLGCTSFSUPPORT = YES
DLGCTSFFILEPATH = /usr/dialogic/cfg/sample.tsf
DLGCDISCONNECTTONE = YES
The above pbxsetting.txt file example configures a system to use the tone set file
sample.tsf and enables disconnect tone supervision.
Example 2
DLGCTSFSUPPORT = NO
DLGCTSFFILEPATH = /usr/dialogic/cfg/sample.tsf
DLGCDISCONNECTTONE = YES
The above pbxsetting.txt file example configures a system to not enable any tone
set file and enables disconnect tone supervision with the default disconnect tone
definitions. The value of DLGCTSFFILEPATH is ignored. All the default tone
information is used for call progress analysis.
25
Dialogic® Learn Mode and Tone Set File API Software Reference
Example 3
DLGCTSFSUPPORT = YES
DLGCTSFFILEPATH = /usr/dialogic/cfg/sample.tsf
DLGCDISCONNECTTONE = NO
The above pbxsetting.txt file example configures a system to use the tone set file
sample.tsf and disables disconnect tone supervision.
Example 4
DLGCTSFSUPPORT = NO
DLGCTSFFILEPATH = /usr/dialogic/cfg/sample.tsf
DLGCDISCONNECTTONE = NO
The above pbxsetting.txt file example configures a system to not use any tone set
file and disables disconnect tone supervision. Therefore, all default tone
information goes into effect, except the disconnect tone.
26
4. Building Applications
4.1. Include Files
Function prototypes and equates are defined in include files, also known as
header files. Applications that use Dialogic® library functions must contain
statements for include files in this form, where filename represents the include
file name:
#include <filename.h>
The following header files must be included in application code in the order
shown prior to calling Dialogic® library functions:
•
srllib.h – Dialogic® Standard Runtime Library (SRL) header file. This header
file is used for all application development.
•
dxxxlib.h – Dialogic® Voice library header file. Include this header file in
applications that use Voice library functions (typically, those that begin with
dx_).
•
lmodelib.h – Dialogic® Learn Mode library header file. Include this header
file in applications that use Learn Mode library functions (typically, those
that begin with lm_).
•
tsfiolib.h – Dialogic® Tone Set File library header file. Include this header
file in applications that use Tone Set File library functions (typically, those
that begin with tsf_).
NOTE: srllib.h must be included in code before all other Dialogic® header files.
By default, in Linux the header files are located in /usr/inc. By default, in
Windows® the header files are located in \<install directory>\dialogic\inc.
4.2. Required Libraries
Simple C language interfaces in source-code format are provided to each
individual technology DLL (such as standard runtime, voice, learn mode). These
C language interfaces allow an application to perform run-time linking instead of
compile-time linking.
27
Dialogic® Learn Mode and Tone Set File API Software Reference
NOTE: Compile-time linking requires that all functions called in an application
be contained in the DLL that resides on the system.
In Linux, you must link the following library files when compiling an application:
•
libtsfio.so – Dialogic® Tone Set File library file. Specify -ltsfio in makefile.
•
liblmode.so – Dialogic® Learn Mode library file. Specify -llmode in
makefile.
•
libdxxx.so – main Dialogic® Voice library file. Specify -ldxxx in makefile.
•
libsrl.so – Dialogic® Standard Runtime Library file. Specify -lsrl in makefile.
In Windows®, you must link the following library files when compiling an
application:
•
libtsfio.lib – Dialogic® Tone Set File library file
•
liblmode.lib – Dialogic® Learn Mode library file
•
libdxxmt.lib – main Dialogic® Voice library file
•
libsrlmt.lib – Dialogic® Standard Runtime Library file
By default, the library files are located in the directory given by the
INTEL_DIALOGIC_LIB environment variable.
28
5. Function Reference
This chapter provides an alphabetical reference to the functions contained in the
Dialogic® Learn Mode library and Dialogic® Tone Set File library.
The following information is included to describe the functions:
•
Reference header information
•
Description
•
Cautions (when applicable)
•
Errors (when applicable)
•
Example
•
See Also (list of related functions, when applicable)
Additional sections may be included as needed.
29
lm_clramp( )
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
clears the tone amplitude structure
void lm_clramp(tn_amplp)
TN_AMP *tn_amplp
• pointer to the TN_AMP
none
none
srllib.h
dxxxlib.h
lmodelib.h
learn mode
synchronous
DM3, Springware
Description
The lm_clramp( ) function clears the tone amplitude structure (TN_AMP). The
function initializes all fields in the structure to their default value.
Call this function before setting values in the lm_LearnTone( ) function
tn_amplp parameter.
Parameter
Description
tn_amplp
Points to the TN_AMP structure that is to be cleared.
„
Cautions
None.
„
Errors
For a list of error codes, see Section 6.1. Learn Mode Error Codes.
„
Example
For an example, see the lm_LearnTone( ) example code.
30
clears the tone amplitude structure
„
•
•
•
lm_clramp( )
See Also
lm_LearnTone( )
lm_clrdesc( )
lm_clrparm( )
31
lm_clrdesc( )
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
clears the tone description structure
void lm_clrdesc(tn_descp)
TN_DESC *tn_descp
• pointer to the TN_DESC
none
none
srllib.h
dxxxlib.h
lmodelib.h
learn mode
synchronous
DM3, Springware
Description
The lm_clrdesc( ) function clears the tone description structure (TN_DESC),
including the associated tone frequency structure (TN_FREQ) and tone duration
structure (TN_DUR). The function initializes all fields in the structure to their
default value.
Call this function to clear lm_LearnTone( ) function tn_rangep and tn_tonep
parameters.
Parameter
Description
tn_descp
Points to the TN_DESC structure that is to be cleared.
„
Cautions
None.
„
Errors
For a list of error codes, see Section 6.1. Learn Mode Error Codes.
„
Example
For an example, see the lm_LearnTone( ) example code.
32
clears the tone description structure
„
•
•
•
lm_clrdesc( )
See Also
lm_LearnTone( )
lm_clramp( )
lm_clrparm( )
33
lm_clrparm( )
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
clears the learn mode parameters structure
void lm_clrparm(lm_parmp)
LM_PARM *lm_parmp
• pointer to the LM_PARM
none
none
srllib.h
dxxxlib.h
lmodelib.h
learn mode
synchronous
DM3, Springware
Description
The lm_clrparm( ) function clears the learn mode parameters structure
(LM_PARM). The function initializes all fields in the structure to their default
value.
Call this function before setting values in the lm_LearnTone( ) function
lm_parmp parameter.
Parameter
Description
lm_parmp
Points to the LM_PARM structure that is to be cleared.
„
Cautions
None.
„
Errors
For a list of error codes, see Section 6.1. Learn Mode Error Codes.
„
Example
For an example, see the lm_LearnTone( ) example code.
34
clears the learn mode parameters structure
„
•
•
•
lm_clrparm( )
See Also
lm_LearnTone( )
lm_clrdesc( )
lm_clramp( )
35
lm_LearnTone( )
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
initiates learn mode
long lm_LearnTone(cd, lm_parmp, tn_amplp, dflagp,
tn_rangep, tn_tonep, tn_infop, mode)
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
• pointer to the TN_INFOLIST
*tn_infolistp
structure
int mode
• synchronous
none
0 if success
-1 if failure
srllib.h
dxxxlib.h
lmodelib.h
learn mode
synchronous
DM3, 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 Dialogic® Voice API
Programming Guide and Dialogic® Voice API Library Reference.
36
initiates learn mode
lm_LearnTone( )
Parameter
Description
cd
Specifies the handle for the voice channel device.
NOTE: If using the Dialogic® Global Call API for call
control, you must retrieve the voice handle of the line
device and use that handle here.
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 7. Data
Structure Reference.
tn_amplp
Points to the TN_AMP data structure, which 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
the TN_AMP structure in Chapter 7. 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.
tn_rangep
0
If unknown or new tone
1
single tone (or a dual tone that falls below the dual-tone
resolution)
2
dual tone
Points to the TN_DESC data structure specifying optional
tone learning boundaries to restrict learning to the specified
range. For more information, see the TN_DESC structure in
Chapter 7. Data Structure Reference.
If you set tn_rangep to NULL, this feature is disabled.
37
lm_LearnTone( )
initiates learn mode
Parameter
Description
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 the Requirements section below 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
„
•
38
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).
initiates learn mode
lm_LearnTone( )
•
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 the 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 Dialogic® Voice API Programming 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 the lm_cnt_min field of the 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 Dialogic® Voice API Programming 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.
39
lm_LearnTone( )
•
„
initiates learn mode
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
This function returns 0 or a non-negative number to indicate success. This
function returns -1 to indicate failure. For a list of error codes, see Section
6.1. Learn Mode Error Codes.
If a library function fails, call the standard attribute function
ATDV_LASTERR( ) to obtain the error code and ATDV_ERRMSGP( ) to
obtain a descriptive error message. For more information on these functions, see
the Dialogic® Standard Runtime Library API Library Reference.
NOTE: If ATDV_LASTERR( ) returns the EDX_SYSTEM error code, an
operating system error has occurred. Check the global variable errno
contained in errno.h. Use dx_fileerrno( ) to obtain the system error
value.
„
Example
#include
#include
#include
#include
#include
#include
<fcntl.h>
<errno.h>
<stdio.h>
”srllib.h”
“dxxxlib.h”
"lmodelib.h"
#define DEVICE "dxxxB1C1"
#define ERR -1
int lrn_Learn(int lrnDev);
int main()
{
int rc;
int Caller;
/* Prepare the scenario for learning dial tone */
Caller = dx_open(DEVICE,(int)NULL);
if (Caller == ERR)
{
40
initiates learn mode
}
lm_LearnTone( )
/* Error occurred in opening DEVICE */
/* Handle the error here and return */
/* error
*/
return(ERR);
/* Set the device offhook to generate a dial tone */
rc = dx_sethook(Caller, DX_OFFHOOK, EV_SYNC);
if (rc == ERR)
{
/* Error setting off hook */
return(ERR);
}
printf("Beginning Learning...............\n");
/* Learn the dial tone */
rc = lrn_Learn(Caller);
if (rc != ERR)
{
printf("Finished Learning...............\n");
}
else
{
printf("Error Learning...\n");
}
/* reset the channel here */
}
return 0;
int lrn_Learn(int Dev)
{
LM_PARM parm;
TN_AMP amp;
TN_DESC desc;
short flagDual;
int ret = ERR;
/* Empty the data structures */
lm_clrparm(&parm);
lm_clramp(&amp);
lm_clrdesc(&desc);
flagDual = 0; /* Unknown whether Dual/Single tone */
/* 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);
if( ret == ERR )
{
/* Learning failed so process and return error */
return(ERR):
}
/* process tone ( frequency and cadence) information returned in desc structure. */
41
lm_LearnTone( )
}
„
•
•
•
42
return(ret);
See Also
lm_clramp( )
lm_clrdesc( )
lm_clrparm( )
initiates learn mode
activates the tone set file
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
tsf_ActivateFile( )
TSF_RET tsf_ActivateFile(char *filename)
filename
• tone set file name
none
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_ActivateFile( ) function activates the tone set file.
In Linux, this function updates the pbxsetting.txt file, which contains information
about the tone set file. For more information on this file, see Section 3.6. Tone
Set Files and pbxsetting.txt.
In Windows®, this function updates the TSFFileSupport field (Misc tab) and the
TSFFileName field (File tab) in the Dialogic® Configuration Manager (DCM) at
runtime. You can also set these fields manually using DCM before downloading
the board.
Parameter
Description
filename
Specifies the tone set file name.
NOTE: If NULL is passed, the currently opened
tone set file is activated.
„
Cautions
None.
„
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
43
tsf_ActivateFile( )
„
activates the tone set file
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
int main() {
int ret;
TSF_FILE_INFO file_info;
TSF_CONSOLIDATIONOPTIONS conscfg;
TONESETINFO default_info;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding Tone Set entry
*.
*.
*.
*/
/* Consolidate the tone set file */
/* Clear the TSF_CONSOLIDATIONOPTIONS structure first before tsf_ConsolidateToneSets()
*/
tsf_ClearConsolidationOptions (&conscfg);
conscfg.dial_tone_id = TID_DIAL_LCL;
conscfg.exclude_default_defs = FALSE;
information in consolidation process
// so include default tone
/*clear out default tone information from consolidation*/
tsf_ClearDefaultToneSetToConsolidate();
/* Set default tone information in default_info structure variable.
*
*
*
*/
/*set defaults */
tsf_SetDefaultToneSetToConsolidate ( &default_info);
/* Consolidate tone set file */
ret = tsf_ConsolidateToneSets(&conscfg);
if (ret == TSF_SUCCESS) {
printf("OK: tsf_ConsolidateToneSets ()\n");
}
else {
printf("Fail: tsf_ConsolidateToneSets () ret=%d\n", ret);
}
/* Right after the tsf_ConsolidateToneSets (), Save the file */
ret = tsf_SaveFile(NULL, TRUE);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_SaveFile()\n");
}
/* Activate tone set file */
44
activates the tone set file
tsf_ActivateFile( )
ret = tsf_ActivateFile(NULL);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_ActivateFile()\n");
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
„
•
See Also
tsf_ConsolidateToneSet( )
45
tsf_AddToneSet( )
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
adds a tone set entry
TSF_RET tsf_AddToneSet (TSF_KEY *pkey, TONESET_ID
*ptoneset_name, TONESETINFO *ptonesetinfo)
ptonesetinfo
• pointer to TONESETINFO
ptoneset_name
• pointer to tone set ID
information
pkey
• key associated with the newly
added tone set
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_AddToneSet( ) function adds a tone set entry to the tone set file. The
new tone set entry contains information about the tone set in ptoneset_name and
ptonesetinfo.
Parameter
Description
pkey
Specifies a pointer to a local variable of type
TSF_KEY. The function returns the key
associated with the newly added tone set in the
local variable. This key is generated by the
Dialogic® Tone Set File library and is a tone set
identifier. This key is used for subsequent
activities on a tone set such as deleting,
modifying, and so on.
ptoneset_name
Specifies a pointer to the tone set name ID
information. The variable holds the tone set file
entry that contains the tone set name associated
with the key tsf_key. The name usually consists
of the manufacturer of the PBX or key system
and its model number.
46
adds a tone set entry
tsf_AddToneSet( )
Parameter
Description
ptonesetinfo
Specifies a pointer to the structure variable of
type TONESETINFO. This structure contains
tone information for all MAX_TONES tones in
the tone set. This tone set is added to the tone set
file.
MAX_TONES is a define that specifies the
maximum number of tones in a tone set.
For more information on the structure, see
Section 7.11. TONESETINFO.
„
Cautions
You must create or open a tone set file using tsf_OpenFile( ) before adding a
tone set entry.
„
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
#define TSF_FILE “intltsf.tsf”
int main() {
int ret;
TSF_FILE_INFO file_info;
TONESETINFO tonesetinfo;
TONESET_ID toneset_id;
TSF_KEY
return_key;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
47
tsf_AddToneSet( )
adds a tone set entry
/* fill in data structure toneset_id and tone_info with desired value before
tsf_AddToneset()
*/
ret = tsf_AddToneSet(&return_key, &toneset_id, &tonesetinfo);
if (ret == TSF_SUCCESS) {
printf("OK: tsf_AddToneSet() key=%d\n", return_key);
}
else {
printf("Fail: tsf_AddToneSet() ret=%d\n", ret);
}
/* Continue processing such as adding more Toneset and consolidation
*.
*.
*.
*/
ret = tsf_SaveFile(NULL, TRUE);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_SaveFile()\n");
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
„
•
•
•
48
See Also
tsf_DeleteToneSet( )
tsf_ModifyToneSet( )
tsf_DuplicateToneSet( )
clears consolidation structure
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform
„
tsf_ClearConsolidationOptions( )
void tsf_ClearConsolidationOptions
(TSF_CONSOLIDATIONOPTIONS *consolidateops)
consolidateops
• pointer to a
TSF_CONSOLIDATIONOPTIONS structure to be cleared.
clearing of consolidateops
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_ClearConsolidationOptions( ) function clears consolidation structure.
This function clears the TSF_CONSOLIDATIONOPTIONS structure and resets
all consolidation options to the default. This is a convenience function.
It is good practice to call this function before consolidating tone sets using
tsf_ConsolidateToneSets( ).
Parameter
Description
consolidateops
Specifies a pointer to a variable of type
TSF_CONSOLIDATIONOPTIONS, which
configures options for the consolidation process.
For more information on this structure, see
Section
7.12. TSF_CONSOLIDATIONOPTIONS.
„
Cautions
None.
49
tsf_ClearConsolidationOptions( )
„
clears consolidation structure
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
#define TSF_FILE “intltsf.tsf”
int main() {
int ret;
TSF_FILE_INFO file_info;
TSF_CONSOLIDATIONOPTIONS config;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding, deleting entry and mark tone sets for
consolidation
*.
*.
*.
*/
/* Consolidate the Tone set file */
/* Clear the TSF_CONSOLIDATIONOPTIONS structure first before tsf_ConsolidateToneSets()
*/
tsf_ClearConsolidationOptions (&config);
config.dial_tone_id = TID_DIAL_LCL;
config.exclude_default_defs = TRUE;
/* Consolidate Tone set file */
ret = tsf_ConsolidateToneSets(&config);
if (ret == TSF_SUCCESS) {
printf("OK: tsf_ConsolidateToneSets ()\n");
}
else {
printf("Fail: tsf_ConsolidateToneSets () ret=%d\n", ret);
}
/* Right after the tsf_ConsolidateToneSets (), Save the file */
ret = tsf_SaveFile(NULL, 1);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_SaveFile()\n");
}
/* Close file */
ret = tsf_CloseFile();
50
clears consolidation structure
}
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
/* return from main() */
return 0
„
•
tsf_ClearConsolidationOptions( )
See Also
tsf_ConsolidateToneSets( )
51
tsf_ClearDefaultToneSetToConsolidate( ) clears the default tone information
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
void tsf_ClearDefaultToneSetToConsolidate (void)
none
none
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_ClearDefaultToneSetToConsolidate( ) function clears the default tone
information for consolidation.
It is good practice to call this function before consolidating tone sets using
tsf_ConsolidateToneSets( ).
„
Cautions
This function will not have any effect after the consolidation process is
performed; that is, after calling tsf_ConsolidateToneSets( ).
„
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
int main() {
int ret;
TSF_FILE_INFO file_info;
TSF_CONSOLIDATIONOPTIONS conscfg;
TONESETINFO default_info;
52
clears the default tone information tsf_ClearDefaultToneSetToConsolidate( )
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding Tone Set entry
*.
*.
*.
*/
/* Consolidate the Tone set file */
/* Clear the TSF_CONSOLIDATIONOPTIONS structure first before tsf_ConsolidateToneSets()
*/
tsf_ClearConsolidationOptions (&conscfg);
conscfg.dial_tone_id = TID_DIAL_LCL;
conscfg.exclude_default_defs = FALSE;
information in consolidation process
// so include default tone
/*clear out default tone information from consolidation*/
tsf_ClearDefaultToneSetToConsolidate();
/* Set default tone information in default_info structure variable.
*
*
*
*/
/*set defaults */
tsf_SetDefaultToneSetToConsolidate ( &default_info);
/* Consolidate Tone sets */
ret = tsf_ConsolidateToneSets(&conscfg);
if (ret == TSF_SUCCESS) {
printf("OK: tsf_ConsolidateToneSets ()\n");
}
else {
printf("Fail: tsf_ConsolidateToneSets () ret=%d\n", ret);
}
/* Right after the tsf_ConsolidateToneSets (), Save the file */
ret = tsf_SaveFile(NULL, 1);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_SaveFile()\n");
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
53
tsf_ClearDefaultToneSetToConsolidate( ) clears the default tone information
„
•
•
•
54
See Also
tsf_GetDefaultToneSetInConsolidation( )
tsf_SetDefaultToneSetToConsolidate( )
tsf_ConsolidateToneSets( )
closes an open tone set file
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
tsf_CloseFile( )
TSF_RET tsf_CloseFile (void)
none
none
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_CloseFile( ) function closes an open tone set file.
„
Cautions
The tsf_CloseFile( ) function does not save changes to the tone set file. To save
updates, call tsf_SaveFile( ) after opening a file and before closing a file.
„
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
#define TSF_FILE “intltsf.tsf”
int main() {
int ret;
TSF_FILE_INFO file_info;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
55
tsf_CloseFile( )
closes an open tone set file
}
/* Continue processing such as adding, deleting Tone Set entry
*.OR process consolidation
*.
*.
*/
/* Don’t forget to save the file to the name as specified to tsf_OpenFile() */
ret = tsf_SaveFile(NULL, TRUE);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_SaveFile()\n");
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
„
•
•
56
See Also
tsf_OpenFile( )
tsf_SaveFile( )
consolidates tone sets
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
tsf_ConsolidateToneSets( )
TSF_RET
tsf_ConsolidateToneSets(TSF_CONSOLIDATIONOPTIONS
*consolidateops, TSF_KEY *keylist, unsigned int listsize)
consolidateops
• pointer to a
TSF_CONSOLIDATIONOPTIONS
structure specifying some parameters
that govern the consolidation
procedure
keylist
• array of keys of tone sets to
consolidate
listsize
• number of elements in array keylist
none
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_ConsolidateToneSets( ) function consolidates tone sets after reading
them from the tone set file, and writes the results to the tone set file.
Parameter
Description
consolidateops
Specifies a pointer to a
TSF_CONSOLIDATIONOPTIONS structure
specifying parameters that govern the
consolidation process. For more information
on this structure, see Section
7.12. TSF_CONSOLIDATIONOPTIONS.
keylist
Specifies an array of keys of tone sets to
consolidate.
A key is generated for every new tone set
added to the tone set file using
tsf_AddToneSet( ). This key is a tone set
identifier.
57
tsf_ConsolidateToneSets( )
consolidates tone sets
Parameter
Description
listsize
Specifies the number of elements in the array
keylist.
„
Cautions
•
You must create or open a tone set file using tsf_OpenFile( ) before
consolidating tone sets.
•
You must call tsf_SetDefaultToneSetToConsolidate( ) before calling
tsf_ConsolidateToneSets( ). The tsf_SetDefaultToneSetToConsolidate( )
function will not have any effect after the consolidation process is performed.
„
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
int main() {
int ret;
TSF_FILE_INFO file_info;
TSF_CONSOLIDATIONOPTIONS conscfg;
TSF_KEY keylist[2];
unsigned short listsize;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding Tone Set entry
*.
*.
*.
*/
/* Consolidate the tone set file */
58
consolidates tone sets
tsf_ConsolidateToneSets( )
/* Clear the TSF_CONSOLIDATIONOPTIONS structure first before tsf_ConsolidateToneSets()
*/
tsf_ClearConsolidationOptions (&conscfg);
conscfg.dial_tone_id = TID_DIAL_LCL;
conscfg.exclude_default_defs = TRUE;
/* include
keylist[0]
keylist[1]
listsize =
tone sets with key 4 and 7 in consolidation */
= 4;
= 7;
2;
/* Consolidate tone set file */
ret = tsf_ ConsolidateToneSets(&conscfg,keylist,listsize);
if (ret == TSF_SUCCESS) {
printf("OK: tsf_ConsolidateToneSets ()\n");
}
else {
printf("Fail: tsf_ConsolidateToneSets () ret=%d\n", ret);
}
/* Right after the tsf_ConsolidateToneSets (), Save the file */
ret = tsf_SaveFile(NULL, 1);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_SaveFile()\n");
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
„
•
•
See Also
tsf_AddToneSet( )
tsf_OpenFile( )
59
tsf_DeleteToneSet( )
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
deletes a tone set entry
TSF_RET tsf_DeleteToneSet (TSF_KEY tsf_key)
tsf_key
• key associated with the tone
set to be deleted
none
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_DeleteToneSet( ) function deletes a tone set entry from the tone set file.
The tone set to be deleted is referenced by tsf_key.
Parameter
Description
tsf_key
Specifies the key associated with the tone set to
be deleted.
„
Cautions
You must create or open a tone set file using tsf_OpenFile( ) before deleting a
tone set entry.
„
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
#define TSF_FILE “intltsf.tsf”
60
deletes a tone set entry
tsf_DeleteToneSet( )
int main() {
int ret;
TSF_FILE_INFO file_info;
TSF_KEY key_delete;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding entry
*.
*.
*.
*/
ret = tsf_DeleteToneSet(key_delete);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_DeleteToneSet ()\n");
}
else
{
printf(“tsf_DeleteToneSet successfully deleted toneset with key value %d\n”,
key_delete );
}
/* Don’t forget to save the file to the name as specified in tsf_OpenFile() */
ret = tsf_SaveFile(NULL, TRUE);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_SaveFile()\n");
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
/* return from main() */
return 0;
}
„
•
•
•
See Also
tsf_AddToneSet( )
tsf_ModifyToneSet( )
tsf_DuplicateToneSet( )
61
tsf_DuplicateToneSet( )
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
duplicates a tone set entry
TSF_RET tsf_DuplicateToneSet (TSF_KEY tsf_key,
TONESET_ID *ptoneset_name, TSF_KEY *pReturn_key)
tsf_key
• key indicating which tone set
to duplicate
ptoneset_name
• tone set ID information for the
newly created duplicate tone
set entry
pReturn_key
• key associated with the newly
created duplicate tone set
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_DuplicateToneSet( ) function duplicates a tone set entry with the
information specified in tsf_key. This duplicated tone set is written to the tone set
file and can be referenced by the key indicated in pReturn_key.
Parameter
Description
tsf_key
Specifies the key indicating which tone set to
duplicate.
ptoneset_name
Specifies a pointer to a structure variable of type
TONESET_ID. This structure is filled with new
ID information.
pReturn_key
Specifies the key associated with the newly
created duplicate tone set. This is a pointer to a
variable of type TSF_KEY. This key identifies
the new tone set.
„
Cautions
You must create or open a tone set file using tsf_OpenFile( ) before duplicating a
tone set entry.
62
duplicates a tone set entry
„
tsf_DuplicateToneSet( )
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
#define TSF_FILE “intltsf.tsf”
int main() {
int ret;
TSF_FILE_INFO file_info;
TSF_KEY tsf_key, new_tsf_key;
TONESET_ID new_toneset_id;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding, deleting Tone Set entry
*.
*.
*/
/* Fill new_toneset_id structure for new toneset. tsf_key is the key of the tone set to
be copied*/
ret = tsf_DuplicateToneSet (tsf_key, &new_toneset_id, &new_tsf_key );
if (ret == TSF_SUCCESS) {
printf("OK: tsf_ DuplicateToneSet() new key = %d\n", new_tsf_key);
}
else {
printf("Fail: tsf_ DuplicateToneSet()\n");
}
/* Don’t forget to save the file to the name as specified to tsf_OpenFile() */
ret = tsf_SaveFile(NULL, TRUE);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_SaveFile()\n");
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
63
tsf_DuplicateToneSet( )
„
•
64
See Also
tsf_AddToneSet( )
duplicates a tone set entry
returns consolidated tone information
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
tsf_GetConsolidatedToneSet( )
TSF_RET tsf_GetConsolidatedToneSet(TONESETINFO *ptonesetinfo)
• pointer to structure variable of type
TONESETINFO
ptonesetinfo
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_GetConsolidatedToneSet( ) function returns consolidated tone
information for all MAX_TONES tones from the opened tone set file. This
function returns the result of the consolidation process, that is, the consolidated
tone set.
Parameter
Description
ptonesetinfo
Specifies a pointer to the structure variable of type
TONESETINFO. This structure contains tone
information for all MAX_TONES tones in the tone
set. This tone set is added to the tone set file.
MAX_TONES is a define that specifies the maximum
number of tones in a tone set.
For more information on the structure, see Section
7.11. TONESETINFO.
„
Cautions
You must create or open a tone set file using tsf_OpenFile( ) before performing
other actions on this file.
65
tsf_GetConsolidatedToneSet( )
„
returns consolidated tone information
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
int main() {
int ret;
TSF_FILE_INFO file_info;
TSF_CONSOLIDATIONOPTIONS conscfg;
TSF_KEY keylist[2];
unsigned short listsize;
TONESETINFO tonesetinfo;
TN_TMPLT tonetmplt[MAX_TONES];
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding Tone Set entry
*.
*.
*.
*/
/* Consolidate the tone set file */
/* Clear the TSF_CONSOLIDATIONOPTIONS structure first before tsf_ConsolidateToneSets()
*/
tsf_ClearConsolidationOptions (&conscfg);
conscfg.dial_tone_id = TID_DIAL_LCL;
conscfg.exclude_default_defs = TRUE;
/* include
keylist[0]
keylist[1]
listsize =
tone sets with key 4 and 7 in consolidation */
= 4;
= 7;
2;
/* Consolidate tone set file */
ret = tsf_ConsolidateToneSets(&conscfg, keylist,listsize);
if (ret == TSF_SUCCESS) {
printf("OK: tsf_ConsolidateToneSets ()\n");
}
else {
printf("Fail: tsf_ConsolidateToneSets () ret=%d\n", ret);
}
/* Right after the tsf_ConsolidateToneSets (), Save the file */
66
returns consolidated tone information
tsf_GetConsolidatedToneSet( )
ret = tsf_SaveFile(NULL, TRUE);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_SaveFile()\n");
}
tonetmplt
ret = tsf_GetConsolidatedToneSet(&tonesetinfo);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_GetConsolidatedToneSet()\n");
}
else
{
/*process the tone template information for to be downloaded.
*
*
*/
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
„
•
•
•
See Also
tsf_OpenFile( )
tsf_ClearConsolidationOptions( )
tsf_ConsolidateToneSets( )
67
tsf_GetConsolidatedToneSetKeys( )
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
returns keys of tone sets consolidated
TSF_RET tsf_GetConsolidatedToneSetKeys (TSF_KEY
*keylist, unsigned short *sizeoflist)
sizeoflist
• pointer to unsigned short that contains
number of elements in array keylist
keylist
• array of TSF_KEY containing keys of
consolidated tone sets
sizeoflist
• pointer to unsigned short that contains
actual number of consolidated tone
sets
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_GetConsolidatedToneSetKeys( ) function returns keys of tone sets
consolidated in an array of parray. A maximum of 10 tone sets can be
consolidated.
Parameter
Description
keylist
Specifies an array of TSF_KEY that contains
keys of consolidated tone sets in the opened tone
set file upon successful return of the function.
sizeoflist
This is an input/output parameter.
As input parameter, the location pointed to by
this parameter contains the number of elements
in the array keylist.
As output parameter, the location pointed to by
this parameter provides the actual number of
consolidated tone sets in the tone set file.
68
returns keys of tone sets consolidated
„
tsf_GetConsolidatedToneSetKeys( )
Cautions
You must create or open a tone set file using tsf_OpenFile( ) before using this
function.
„
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
int main() {
int ret;
TSF_FILE_INFO file_info;
unsigned short NumToneSets = 5;
TSF_KEY *keylist;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding Tone Set entry
* then apply consolidation process.
*.
*.
*/
ret = tsf_GetNumberOfConsolidatedToneSets(&NumConsToneSets);
if( ret == TSF_SUCCESS )
{
printf(“Number of tone sets in the tsf file is %d\n”,NumConsToneSets);
}
else
{
printf(“tsf_GetNumberOfConsolidatedToneSets() is fail\n”);
}
keylist = new TSF_KEY[NumConsToneSets];
ret = tsf_GetConsolidatedToneSetKeys(keylist,&NumConsToneSets);
if( ret == TSF_SUCCESS )
{
printf(“Number of consolidated tone sets in the tsf file is %d\n”,NumConsToneSets);
/*process keylist here */
}
else
69
tsf_GetConsolidatedToneSetKeys( )
{
}
returns keys of tone sets consolidated
printf(“tsf_tsf_GetConsolidatedToneSetKeys() is fail\n”);
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
„
•
70
See Also
tsf_GetNumberOfToneSetsConsolidated( )
returns info on default tone set
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
tsf_GetDefaultToneSetInConsolidation( )
TSF_RET tsf_GetDefaultToneSetInConsolidation
(TONESETINFO *ptonesetinfo)
none
ptonesetinfo
• pointer to a structure that contains
default tone information of
MAX_TONES tones to add in
consolidation process
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_GetDefaultToneSetInConsolidation( ) function returns info on default
tone set included in the consolidation process.
Use this function to return the results of what was set in
tsf_SetDefaultToneSetToConsolidate( ).
Parameter
Description
ptonesetinfo
Specifies a pointer to the structure variable of
type TONESETINFO. This structure contains
tone information for all MAX_TONES tones in
the tone set.
MAX_TONES is a define that specifies the
maximum number of tones in a tone set.
For more information on the structure, see
Section 7.11. TONESETINFO.
„
Cautions
None.
71
tsf_GetDefaultToneSetInConsolidation( )
„
returns info on default tone set
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
int main() {
int ret;
TSF_FILE_INFO file_info;
TSF_CONSOLIDATIONOPTIONS conscfg;
TONESETINFO default_info;
TONESETINFO get_default_info;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding Tone Set entry
*.
*.
*.
*/
/* Consolidate the tone set file */
/* Clear the TSF_CONSOLIDATIONOPTIONS structure first before tsf_ConsolidateToneSets()
*/
tsf_ClearConsolidationOptions (&conscfg);
conscfg.dial_tone_id = TID_DIAL_LCL;
conscfg.exclude_default_defs = FALSE;
consolidation process
// so include default tone information in
/*clear out default tone information from consolidation*/
tsf_ClearDefaultToneSetToConsolidate();
/* here tsf_GetDefaultToneSetInConsolidation(&get_default_info) API returns all 0 in
get_default_info */
/* Set default tone information in default_info structure variable.
*
*
*
*/
/*set defaults */
tsf_SetDefaultToneSetToConsolidate ( &default_info);
tsf_GetDefaultToneSetInConsolidation(&get_default_info);
/* here get_default_info structure variable have same values in default_info
*/
72
returns info on default tone set
tsf_GetDefaultToneSetInConsolidation( )
/* Consolidate tone set file */
ret = tsf_ConsolidateToneSets(&conscfg);
if (ret == TSF_SUCCESS) {
printf("OK: tsf_ConsolidateToneSets ()\n");
}
else {
printf("Fail: tsf_ConsolidateToneSets () ret=%d\n", ret);
}
/* Right after the tsf_ConsolidateToneSets (), Save the file */
ret = tsf_SaveFile(NULL, TRUE);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_SaveFile()\n");
}
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
/* return from main() */
return 0
„
•
•
•
See Also
tsf_SetDefaultToneSetToConsolidate()
tsf_ClearDefaultToneSetToConsolidate()
tsf_ConsolidateToneSets()
73
tsf_GetFileInformation( )
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
gets updated information about a tone set file
TSF_RET tsf_GetFileInformation (TSF_FILE_INFO
*pfile_info)
none
pfile_info
• pointer to a local
TSF_FILE_INFO structure
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_GetFileInformation( ) function gets updated information about a tone
set file after tsf_OpenFile( ) has been called. The information about the tone set
file is found in the TSF_FILE_INFO structure, which is pointed to by pfile_info.
Information about the tone set file is constantly updated by different operations
on the file, such as adding a tone set, deleting a tone set, and so on. At any point,
you can use this function to get a snapshot of the state of the tone set file.
Depending on previous activity on the file or functions invoked, the results will
vary.
Parameter
Description
pfile_info
Specifies a pointer to a local structure variable of
type TSF_FILE_INFO, which holds the tone set
file information.
„
Cautions
You must create or open a tone set file using tsf_OpenFile( ) before calling
tsf_GetFileInformation( ).
74
gets updated information about a tone set file
„
tsf_GetFileInformation( )
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
#define TSF_FILE “intltsf.tsf”
int main() {
int ret;
TSF_FILE_INFO file_info1, file_info0;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info0, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding Tone Set entry
*.
*.
*.
*/
ret = tsf_GetFileInformation(&file_info1);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_GetFileInformation() ret= %d\n", ret);
}
/* Continue processing
*.
*.
*.
*/
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
75
tsf_GetFileInformation( )
„
•
76
See Also
tsf_OpenFile( )
gets updated information about a tone set file
returns the number of tone sets
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
tsf_GetNumberOfToneSets( )
TSF_RET tsf_GetNumberOfToneSets(unsigned short
*numoftonesets)
none
numoftonesets
• pointer to a variable of type
unsigned short that holds
number of tone sets in the
opened tone set file
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_GetNumberOfToneSets( ) function returns the number of tone sets in an
opened tone set file. This is a convenience function.
Parameter
Description
numoftonesets
Pointer to a variable of type unsigned short that
holds number of tone sets in the opened tone set
file. Successful execution of the function
provides the number of tone sets in current
opened tone set file.
„
Cautions
You must create or open a tone set file using tsf_OpenFile( ) before using this
function.
„
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
77
tsf_GetNumberOfToneSets( )
„
returns the number of tone sets
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
int main() {
int ret;
TSF_FILE_INFO file_info;
unsigned short NumToneSets;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding Tone Set entry
*.
*.
*.
*/
ret = tsf_GetNumberOfToneSets(&NumToneSets);
if( ret == TSF_SUCCESS )
{
printf(“Number of tone sets in the tsf file is %d\n”,NumToneSets);
}
else
{
printf(“tsf_GetNumberOfToneSets() failed\n”);
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
„
•
78
See Also
tsf_GetToneSetKeys()
returns number of consolidated
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
tsf_GetNumberOfToneSetsConsolidated( )
TSF_RET tsf_GetNumberOfToneSetsConsolidated(unsigned
short *numoftonesets)
none
numoftonesets
• pointer to a variable of type
unsigned short that holds
number of consolidated tone
sets in the opened tone set file
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_GetNumberOfToneSetsConsolidated( ) function returns number of
consolidated tone sets in an opened tone set file.
Parameter
Description
numoftonesets
Successful execution of the function provides the
number of consolidated tone sets in the current
opened tone set file.
„
Cautions
You must create or open a tone set file using tsf_OpenFile( ) before using this
function.
„
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
79
tsf_GetNumberOfToneSetsConsolidated( )
„
returns number of consolidated
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
int main() {
int ret;
TSF_FILE_INFO file_info;
unsigned short NumToneSets;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding Tone Set entry
* Consolidate tone sets
*
*
*/
ret = tsf_GetNumberOfToneSetsConsolidated(&NumToneSets);
if( ret == TSF_SUCCESS )
{
printf(“Number of consolidated tone sets in the tsf file is %d\n”,NumToneSets);
}
else
{
printf(“tsf_GetNumberOfToneSetsConsolidated() failed\n”);
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
„
•
80
See Also
tsf_GetToneSetKeys()
returns tone information
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
tsf_GetToneSet( )
TSF_RET tsf_GetToneSet (TSF_KEY tsf_key,
TONESETINFO *ptonesetinfo)
tsf_key
• key of tone set
ptonesetinfo
• tone information for all
MAX_TONES
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_GetToneSet( ) function returns tone information for a specific tone set,
specified in tsf_key.
Parameter
Description
tsf_key
Specifies the key or identifier of the tone set.
ptonesetinfo
Specifies a pointer to the structure variable of
type TONESETINFO. This structure contains
tone information for all MAX_TONES tones in
the tone set. This tone set is added to the tone set
file.
MAX_TONES is a define that specifies the
maximum number of tones in a tone set.
For more information on the structure, see
Section 7.11. TONESETINFO.
„
Cautions
You must create or open a tone set file using tsf_OpenFile( ) before calling
tsf_GetToneSet( ).
81
tsf_GetToneSet( )
„
returns tone information
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
#define TSF_FILE “intltsf.tsf”
int main() {
int ret;
TSF_FILE_INFO file_info;
TSF_KEY tsf_key;
TONESETINFO toninfoset;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding, deleting tone set entry
*.
*.
*.
*/
/* find tone set ID of the tone set with key tsf_key */
ret = tsf_GetToneSet (tsf_key, &toninfoset);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_GetToneSet ()\n");
}
else
{
printf(“OK: tsf_GetToneSet\n”);
/* process here information received in tonesetinfo.toneinfo[MAX_TONES]
*
*
*/
}
/* Continue processing
*
*
*/
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
82
returns tone information
tsf_GetToneSet( )
/* return from main() */
return 0;
}
„
•
See Also
tsf_OpenFile( )
83
tsf_GetToneSetKeys( )
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
returns the keys of the tone sets
TSF_RET tsf_GetToneSetKeys (TSF_KEY *keylist, unsigned
short *sizeoflist)
sizeoflist
• pointer to unsigned short that
contains number of elements in
array keylist
keylist
• array of TSF_KEY
sizeoflist
• pointer to unsigned short that
contains actual number of tone
sets
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_GetToneSetKeys( ) function returns the keys of the tone sets in an
opened tone set file. This is a convenience function.
Parameter
Description
keylist
Specifies an array of TSF_KEY that contains the
keys of the tone sets in the opened tone set file
upon successful return of the function.
sizeoflist
This is an input/output parameter.
As input parameter, the location pointed to by
this parameter contains the number of elements
in the array keylist.
As output parameter, the location pointed to by
this parameter provides the actual number of
tone sets in the tone set file.
„
Cautions
You must create or open a tone set file using tsf_OpenFile( ) before using this
function.
84
returns the keys of the tone sets
„
tsf_GetToneSetKeys( )
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
int main() {
int ret;
TSF_FILE_INFO file_info;
unsigned short NumToneSets = 5;
TSF_KEY *keylist;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding Tone Set entry
*.
*.
*.
*/
ret = tsf_GetNumberOfToneSets(&NumToneSets);
if( ret == TSF_SUCCESS )
{
printf(“Number of tone sets in the tsf file is %d\n”,NumToneSets);
}
else
{
printf(“tsf_GetNumberOfToneSets() failed\n”);
}
keylist = new TSF_KEY[NumToneSets];
ret = tsf_GetToneSetKeys(keylist,&NumToneSets);
if( ret == TSF_SUCCESS )
{
printf(“Number of tone sets in the tsf file is %d\n”,NumToneSets);
/*process keylist here */
}
else
{
printf(“tsf_GetToneSetKeys() failed\n”);
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
85
tsf_GetToneSetKeys( )
}
/* return from main() */
return 0
„
•
86
See Also
tsf_GetNumberOfToneSets()
returns the keys of the tone sets
returns the tone set name
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
tsf_GetToneSetName( )
TSF_RET tsf_GetToneSetName (TSF_KEY tsf_key,
TONESET_ID *ptoneset_name)
tsf_key
• key of tone set
ptoneset_name
• tone set name of the TSF entry
at toneset_offset in tone set file
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_GetToneSetName( ) function returns the tone set name of the tone set
associated with tsf_key.
Parameter
Description
tsf_key
Specifies the key or identifier of the tone set.
ptoneset_name
Specifies a pointer to the tone set ID
information.
„
Cautions
You must create or open a tone set file using tsf_OpenFile( ) before calling
tsf_GetToneSetName( ).
„
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
87
tsf_GetToneSetName( )
„
returns the tone set name
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
#define TSF_FILE “intltsf.tsf”
int main() {
int ret;
TSF_FILE_INFO file_info;
TSF_KEY tsf_key;
TONESET_ID tonset_name;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding, deleting tone set entry
*.
*.
*.
*/
/* find tone set name of the tone set with key tsf_key */
ret = tsf_GetToneSetName(tsf_key, &tonset_name);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_GetToneSetName ()\n");
}
else
{
printf(“OK: tsf_GetToneSetKeys\n”);
printf(“Name of tone set is %s\n”, tonset_name.toneset_name);
printf(“Model of tone set is %s\n”, tonset_name.toneset_model);
}
/* Continue processing
*
*
*/
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
/* return from main() */
return 0;
}
„
•
88
See Also
tsf_DeleteToneSet( )
modifies a tone set
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
tsf_ModifyToneSet( )
TSF_RET tsf_ModifyToneSet (TSF_KEY tsf_key,
TONESET_ID *ptoneset_name, TONESETINFO
*ptonesetinfo)
tsf_key
• a key indicating which tone set
to modify
ptoneset_name
• tone set ID information to be
written for this tone set
ptonesetinfo
• tone information to be written
for this tone set
none
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_ModifyToneSet( ) function modifies a tone set with the information
specified in ptonesetinfo. If either the ID information or tone information is to
remain unchanged, NULL may be specified for the appropriate argument;
however, at least one of the pointers must be non-NULL.
Parameter
Description
tsf_key
Specifies the key indicating which tone set to
modify.
ptoneset_name
Specifies a pointer to the tone set ID information
to be written for a particular tone set.
ptonesetinfo
Specifies the information to be written for a
particular tone set.
„
Cautions
You must create or open a tone set file using tsf_OpenFile( ) before modifying a
tone set entry.
89
tsf_ModifyToneSet( )
„
modifies a tone set
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
#define TSF_FILE “intltsf.tsf”
int main() {
int ret;
TSF_FILE_INFO file_info;
TONESETINFO new_tonesetinfo;
TONESET_ID new_toneset_id;
TSF_KEY
my_key;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding Tone Set entry
*.
*.
*.
*/
/* Before calling tsf_ModifyToneSet(), make a new_toneset_id and new_tone_info you
desire. Modify tone set with key 1 here.
*/
my_key = 1;
ret = tsf_ModifyToneSet(my_key, &new_toneset_id, &new_tonesetinfo);
if (ret == TSF_SUCCESS) {
printf("OK: tsf_ModifyToneSet()\n");
}
else {
printf("Fail: tsf_ModifyToneSet() ret=%d\n",ret);
}
/* Continue processing such as consolidation
*.
*.
*.
*/
/* Save the file */
ret = tsf_SaveFile(NULL, TRUE);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_SaveFile()\n");
}
90
modifies a tone set
tsf_ModifyToneSet( )
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
„
•
•
See Also
tsf_DuplicateToneSet( )
tsf_AddToneSet( )
91
tsf_OpenFile( )
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
opens the tone set file
TSF_RET tsf_OpenFile (char * filename, TSF_FILE_INFO
*pfile_info, unsigned short rfu)
filename
• name of the tone set file to be
opened
rfu
• always 0
pfile_info
• pointer to a local
TSF_FILE_INFO structure
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_OpenFile( ) function opens the tone set file specified in the filename
parameter. If the file does not exist, this function creates a new one using the
name specified in the filename parameter. Initial information about the file is
copied into the TSF_FILE_INFO structure pointed to by pfile_info.
Parameter
Description
filename
Specifies the name of the tone set file to be
opened or created.
rfu
Reserved for future use. Always = 0
pfile_info
Specifies a pointer to a local TSF_FILE_INFO
structure. For more information about this
structure, see Section 7.13. TSF_FILE_INFO.
„
Cautions
•
Only one tone set file can remain open at any point in time.
•
Calling tsf_OpenFile( ) before closing an existing open tone set file results
in failure. There must be a tsf_CloseFile( ) function call for each
tsf_OpenFile( ) function call.
92
opens the tone set file
„
tsf_OpenFile( )
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
#define TSF_FILE “intltsf.tsf”
int main() {
int ret;
TSF_FILE_INFO file_info;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as ToneSet entry and consolidation
*.
*.
*.Save changes
*/
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
„
•
•
See Also
tsf_GetFileInformation( )
tsf_CloseFile( )
93
tsf_SaveFile( )
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
saves tone set data
TSF_RET tsf_SaveFile (char *filename, unsigned short flag)
filename
• alternate file name with which
to save a tone set file
flag
• Boolean expression indicating
if an existing tone set file may
be overwritten
none
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_SaveFile( ) function saves tone set data to a tone set file. If NULL is
specified in filename, then the file is saved with the file name specified when the
file was originally opened with tsf_OpenFile( ). If a file name is specified in
filename, then that file name is used.
You should always call this function after consolidating tone sets using
tsf_ConsolidateToneSets( ) in order to save the results of the consolidation.
Parameter
Description
filename
Specifies an alternate file name with which to
save a tone set file.
Specify NULL to save the file using the same
name with which it was opened.
flag
„
Specifies a Boolean expression indicating if an
existing tone set file may be overwritten. Values
are TRUE or FALSE.
Cautions
The tone set file must be open before it can be saved.
94
saves tone set data
„
tsf_SaveFile( )
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
#define TSF_FILE “intltsf.tsf”
int main() {
int ret;
TSF_FILE_INFO file_info;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding, deleting Tone Set entry
*.OR process consolidation
*.
*.
*/
/* Don’t forget to save the file to the name as specified to tsf_OpenFile() after
adding or modifying the file */
ret = tsf_SaveFile(NULL, TRUE);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_SaveFile()\n");
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
„
•
•
See Also
tsf_OpenFile( )
tsf_CloseFile( )
95
tsf_SetDefaultToneSetToConsolidate( )
Name:
Inputs:
Outputs:
Returns:
Includes:
Category:
Mode:
Dialogic®
Platform:
„
adds default tone set information
TSF_RET
tsf_SetDefaultToneSetToConsolidate(TONESETINFO
*ptonesetinfo)
ptonesetinfo
• pointer to a structure that
contains default tone
information of MAX_TONES
tones to add in consolidation
process
none
error code
tsfiolib.h
TSF
synchronous
DM3, Springware
Description
The tsf_SetDefaultToneSetToConsolidate( ) function adds default tone set
information to the consolidation process.
Parameter
Description
ptonesetinfo
Specifies a pointer to a structure variable of type
TONESETINFO that contains default tone
information for MAX_TONES tones.
„
Cautions
•
If you want to add default tone set information to the consolidation process,
you must call tsf_SetDefaultToneSetToConsolidate( ) before calling
tsf_ConsolidateToneSets( ). The tsf_SetDefaultToneSetToConsolidate( )
function will not have any effect after the consolidation process is performed.
•
This function must be called according to the exclude_default_defs field
setting in the TSF_CONSOLIDATIONOPTIONS structure:
•
96
If exclude_default_defs is set to TRUE, then you must call this function
before tsf_ConsolidateToneSets( ) to set default tone information for
consolidation. Otherwise, the consolidation fails with error code
TSF_CONSOLIDATION_DEFAULTS_NOT_SET.
adds default tone set information
•
„
tsf_SetDefaultToneSetToConsolidate( )
If exclude_default_defs is set to FALSE, then you can take one of two
actions: (1) you must not call this function to set default tone
information for consolidation, or (2) you must clear default information
using tsf_ClearDefaultToneSetToConsolidate( ) after calling the
function. Otherwise, the consolidation fails with error code
TSF_CONSOLIDATION_DEFAULTS_NOT_REQUESTED.
Errors
This function returns TSF_SUCCESS to indicate success. This function returns
an error code in case of error. For a description of error codes, see Section
6.2. Tone Set File Error Codes.
„
Example
#include
#include
#include
#include
<stdio.h>
"srllib.h"
"lmodelib.h"
"tsfiolib.h"
int main() {
int ret;
TSF_FILE_INFO file_info;
TSF_CONSOLIDATIONOPTIONS conscfg;
TONESETINFO default_info;
/* tsf_OpenFile() */
ret = tsf_OpenFile(TSF_FILE, &file_info, 0);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_OpenFile() : retvalue = %d\n", ret);
exit(1);
}
/* Continue processing such as adding Tone Set entry
*.
*.
*.
*/
/* Consolidate the tone set file */
/* Clear the TSF_CONSOLIDATIONOPTIONS structure first before tsf_ConsolidateToneSets()
*/
tsf_ClearConsolidationOptions (&conscfg);
conscfg.dial_tone_id = TID_DIAL_LCL;
conscfg.exclude_default_defs = FALSE;
information in consolidation process
// so include default tone
/*clear out default tone information from consolidation*/
tsf_ClearDefaultToneSetToConsolidate();
/* Set default tone information in default_info structure variable.
*
97
tsf_SetDefaultToneSetToConsolidate( )
adds default tone set information
*
*
*/
/*set defaults */
tsf_SetDefaultToneSetToConsolidate ( &default_info);
/* Consolidate tone set file */
ret = tsf_ConsolidateToneSets(&conscfg);
if (ret == TSF_SUCCESS) {
printf("OK: tsf_ConsolidateToneSets ()\n");
}
else {
printf("Fail: tsf_ConsolidateToneSets () ret=%d\n", ret);
}
/* Right after the tsf_ConsolidateToneSets (), Save the file */
ret = tsf_SaveFile(NULL, TRUE);
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_SaveFile()\n");
}
/* Close file */
ret = tsf_CloseFile();
if (ret != TSF_SUCCESS) {
printf("Fail: tsf_CloseFile()\n");
}
}
/* return from main() */
return 0
„
•
•
•
98
See Also
tsf_GetDefaultToneSetInConsolidation()
tsf_ClearDefaultToneSetToConsolidate()
tsf_ConsolidateToneSets()
6. Error Codes
6.1. Learn Mode Error Codes
Learn mode error codes can be found in lmodelib.h and include the following:
Name
Description
EDX_CADFLAG
Invalid continuous/cadence flag (lm_cadflag) in
LM_PARM structure
EDX_CONTIM
Invalid continuous tone minimum on-time (lm_cnt_min)
in LM_PARM structure
EDX_FRAMES
Invalid number of frames (lm_frames) in LM_PARM
structure
EDX_FREQTOL
Invalid learn mode frequency tolerance (lm_frq_tol) in
LM_PARM structure
EDX_LMDURTOL
Invalid learn mode duration tolerance (lm_dur_tol) in
LM_PARM structure
EDX_LMMETHOD
Invalid frequency/tolerance learning method
(lm_method) in LM_PARM structure
EDX_LMPARM
Invalid parameters in LM_PARM structure
EDX_LMQUALID
Invalid learn mode qualification template ID (lm_qualid)
in LM_PARM structure
EDX_TNAMP
Invalid tone amplitude in TN_AMP structure
EDX_TNDFLAG
Invalid dual/single tone flag (dflagp)
EDX_TNINFO
Not enough tone information to do the learning (requires
5 frames/samples)
EDX_TNINVALID
Invalid tone detected
EDX_TNPARM
Invalid tone template parameter
99
Dialogic® Learn Mode and Tone Set File API Software Reference
6.2. Tone Set File Error Codes
Tone set file error codes can be found in tsfiolib.h and include the following:
Name
Description
TSF_ACTIVATION_FAIL
The tsf_ActivateFile( ) function failed.
Can only activate file after file has been
consolidated.
TSF_CONSOLIDATION_BLANK
_ENTRY
A tone set to be consolidated contains
no tone set data. A tone set entry has
zeros defined for freq1 and freq2 tone
definitions.
TSF_CONSOLIDATION_CAD
_CONT_MIX
Tones of the same category (e.g.,
ringback or busy) in different tone sets
have a mix of continuous and cadenced
tone definitions. For instance, TonesetA
has a continuous tone defined for
ringback and TonesetB has a cadenced
tone defined for ringback. If this is true,
TonesetA and TonesetB cannot both be
marked for consolidation.
TSF_CONSOLIDATION_
DEFAULTS_NOT_REQUESTED
Default tone information is set but not
requested to include in compilation.
TSF_CONSOLIDATION_
DEFAULTS_NOT_SET
Default tone information request to be
included in consolidation process but
default tone information not set.
TSF_CONSOLIDATION_FREQ_
TOO_WIDE
Deviation of the frequency component
of a tone set is greater than the value
defined in COMP_MAX_FREQ_DEV.
The maximum range allowed is 420
(i.e., a deviation of 420/2 = 210).
TSF_CONSOLIDATION_GENERAL
When the error doesn’t fit any of the
other descriptions, this error is
generated.
100
6. Error Codes
Name
Description
TSF_CONSOLIDATION_INVALID_
DTONE
A dial tone definition in the list of PBXs
is not valid. It contains a cadence
definition. This excludes debounce (0
off-time and negative on-time
deviation).
TSF_CONSOLIDATION_NO_
DATA
A consolidation was requested and there
are no entries in the build list.
TSF_CONSOLIDATION_OVERLAP
The consolidation of the tone sets
resulted in a conflict between the
ringback and busy templates.
TSF_CONSOLIDATION_QUAL_
TEMP
Across a given template definition for
the set of PBXs, there are both single
and dual tone definitions for the same
tone.
TSF_CONSOLIDATION_SINGLE_
DUAL
Tones of the same category (e.g.,
ringback or busy) in different tone sets
have a mix of single and dual tone
definitions. For instance, TonesetA has
a single frequency tone defined for
ringback and TonesetB has a dual
frequency tone defined for ringback. If
this is true, TonesetA and TonesetB
cannot both be consolidated.
TSF_CONSOLIDATION_SUCCESS
Successful consolidation. Tone set file is
written to the disk.
TSF_CONSOLIDATION_TOO_
MANY
Too many tone sets were chosen for
consolidation. Only 10 tone sets may be
consolidated.
TSF_FAILURE
Tone set file operation failed.
TSF_FILE_EXISTS
File name selected for the save
operation already exists.
TSF_FILE_NOT_CLOSED
The file has not been closed, so an open
function cannot be performed.
101
Dialogic® Learn Mode and Tone Set File API Software Reference
Name
Description
TSF_FILE_NOT_CONSOLIDATED
The file does not have a consolidated
tone set.
TSF_FILE_NOT_OPENED
The file has not been opened, so no
activity can occur.
TSF_INVALID_FILENAME
File name used is not a valid one.
TSF_INVALID_FILETYPE
Invalid file type.
TSF_INVALID_KEY
Key passed is invalid.
TSF_INVALID_PARAMETER
Invalid parameter or null argument
passed.
TSF_IS_DELETED
The tone set is deleted.
TSF_MISSING_ARG
Missing argument.
TSF_NO_MEM
The system has no remaining memory.
TSF_READONLY
The file is read-only.
TSF_SUCCESS
Tone set file operation successful.
102
7. Data Structure Reference
7.1. Data Structures Overview
This chapter provides an alphabetical reference to the data structures used by the
Dialogic® Learn Mode API library and Tone Set File API library functions.
The following data structures, defined in dxxxlib.h, are used by Learn Mode API
library functions:
•
LM_PARM – learn mode parameters structure
•
TN_AMP – tone amplitude structure
•
TN_DESC – tone description structure
•
TN_DUR – tone duration structure
•
TN_FREQ – tone frequency structure
•
TN_INFO – tone information structure
•
TN_INFOLIST – tone information list structure
The following data structures, defined in tsfiolib.h, are used by Tone Set File API
library functions:
•
TONE_INFO – tone information structure
•
TONESET_ID – tone set identification structure
•
TONESETINFO – tone set information structure
•
TSF_CONSOLIDATIONOPTIONS – consolidation options structure
•
TSF_FILE_INFO – tone set file information structure
7.2. LM_PARM: Learn Mode Parameters
The LM_PARM structure is declared as follows:
typedef struct {
unsigned short int lm_cadflag;
unsigned short int lm_cnt_min;
/* cadence/continuous tone flag
*/
/* min on-time for continuous tone */
103
Dialogic® Learn Mode and Tone Set File API Software Reference
unsigned short int lm_frames;
unsigned short int lm_qualid;
unsigned short int lm_method;
float
lm_frq_tol;
float
lm_dur_tol;
} LM_PARM;
/*
/*
/*
/*
/*
number of tone on/off samples
qualification ID used
method for freq/dur tolerances
frequency parm for tolerance
duration parm for tolerance
*/
*/
*/
*/
*/
The learn mode parameters structure (LM_PARM) specifies the parameters and
options for learning a tone and is used for input to the lm_LearnTone( )
function. These options include the continuous tone minimum on-time, the
number of learning samples, the qualification ID (which controls the immunity to
noise), and the methods and values for calculating the frequency and cadence
range for the final tone description.
NOTE: Set any field to 0 to use the default value.
Use the lm_clrparm( ) function to clear the fields of an LM_PARM structure.
Table 1. LM_PARM Structure
Field
Description
lm_cadflag
Length: 2 (unsigned short int)
Default: 0
Continuous or cadence mode. Specifies whether the tone
to be learned is continuous or has a cadence. If you set the
tn_rangep parameter of the lm_LearnTone( ) function to
restrict learning to a specified range, you must set the
lm_cadflag field to indicate a cadence or continuous tone.
104
0
To learn a tone when you don't know whether
the tone is continuous or cadence.
1
To learn a tone having a cadence.
2
To learn a continuous tone.
7. Data Structure Reference
Field
Description
lm_cnt_min
Length: 2 (unsigned short int)
Units: 10 ms. Range: 1 – 1000
Default: 400 (4 seconds)
Continuous tone minimum on-time. Specifies in 10 ms
units the tone-on duration for the tone to qualify as a
continuous tone. After the tone qualifies, sampling is
performed for the number of frames (samples) specified in
lm_frames.
Set this field to 0 to use the default value (400).
lm_frames
Length: 2 (unsigned short int)
Default: 10
Range: 5 – 127
Number of learning samples. For a cadence tone, this
specifies the number of tone-on/tone-off transitions for
learning the cadence. For a continuous tone, this specifies
the number of samples taken after the tone qualifies as a
continuous tone (see lm_cnt_min) and on which the final
frequency range is based. It is recommended that you set
lm_frames to a minimum of 30 if you are using
lm_method LM_STATISTICAL.
Set this field to 0 to use the default value (10).
lm_qualid
Length: 2 (unsigned short int)
Default: QT_LMDEF (sets to QT_LMMID)
Qualification ID. Specifies the qualification template ID
used for learning. The qualification ID specified here is
also output in the tn_qualid field of the final tone
description in the TN_DESC structure. Increase the
qualification ID for more immunity to noise and less
sensitivity to the tone.
QT_LMDEF
Sets the qualification ID to the
default (middle).
QT_LMLOW
Low qualification (poor line
quality).
QT_LMMID
Middle qualification (medium
line quality).
105
Dialogic® Learn Mode and Tone Set File API Software Reference
Field
Description
QT_LMHIGH
lm_method
High qualification (high line
quality).
Length: 2 (unsigned short int)
Default: DEF_METHOD (sets to LM_RATIO)
User-selectable tolerance method. Indicates the method
used to calculate the frequency range and cadence range
needed to detect the tone.
lm_frq_tol
DEF_METHOD
Sets to the default method,
LM_RATIO.
LM_ABSOLUTE
Absolute tolerance (constant
value) takes the samples with the
highest and lowest values and
then adds and subtracts the
constant value specified in
lm_frq_tol or lm_dur_tol.
LM_RATIO
Ratio tolerance (percentage) takes
the samples with the highest and
lowest values and then adds and
subtracts the percentage specified
in lm_frq_tol or lm_dur_tol.
LM_STATISTICAL
Statistical tolerance method based
on calculating the mean and
variance of the samples;
lm_frq_tol and lm_dur_tol
specify the percentage of extreme
samples to exclude; places less
weight on a “bad” sample
(aberration or extreme deviation);
preferable method when the tone
data is poor. For good results with
this method, set lm_frames to a
minimum of 30.
Length: 4 (float)
Frequency tolerance. Specifies a value used in calculating
the frequency tolerance. The default, range, and units
depend upon the tolerance lm_method selected:
106
7. Data Structure Reference
Field
Description
LM_ABSOLUTE
Units: Hz
Range: 0 – 300
Default: 30 Hz
Specifies in Hz a constant value
to add to and subtract from the
samples with the highest and
lowest values to obtain the
frequency detection range.
LM_RATIO
Units: Percentage
Range: 0 – 1
Default: 0.06
Specifies a percentage to add to
and subtract from the samples
with the highest and lowest
values to obtain the frequency
detection range.
LM_STATISTICAL
Units: Percentage
Range: 0 – 0.2
Default: 0.03
Specifies the percentage of
extreme samples to exclude from
the normal distribution.
lm_dur_tol
Length: 4 (float)
Duration tolerance. Specifies a value used in calculating
the tolerance for the tone cadence (tone-on/tone-off
durations). The default, range, and units depend upon the
tolerance lm_method selected:
LM_ABSOLUTE
Units: 10 ms
Range: 0 – 100
Default: 3.0
Specifies in units of 10 ms a
constant value to add to and
subtract from the samples with
the highest and lowest values to
obtain the cadence detection
range.
107
Dialogic® Learn Mode and Tone Set File API Software Reference
Field
Description
LM_RATIO
Units: Percentage
Range: 0 – 1
Default: 0.08
Specifies a percentage to add to
and subtract from the samples
with the highest and lowest
values to obtain the cadence
detection range.
LM_STATISTICAL
Units: Percentage
Range: 0 – 0.2
Default: 0.03
Specifies the percentage of
extreme samples to exclude from
the normal distribution.
7.3. TN_AMP: Tone Amplitude
The TN_AMP structure is declared as follows:
typedef struct {
short int tn_fq1_minamp;
short int tn_fq1_maxamp;
short int tn_fq2_minamp;
short int tn_fq2_maxamp;
} TN_AMP;
/*
/*
/*
/*
1st
1st
2nd
2nd
tone
tone
tone
tone
min.
max.
min.
max.
amplitude
amplitude
amplitude
amplitude
(dB)
(dB)
(dB)
(dB)
*/
*/
*/
*/
The TN_AMP structure specifies tone amplitude boundaries. It is used by learn
mode for input to the lm_LearnTone( ) function to 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.
When setting the amplitude range for a dual tone, it is typical to use the same
amplitude range for both frequencies.
NOTE: Set any field to 0 to use the default value.
Use the lm_clramp( ) function to clear the fields of a TN_AMP structure.
108
7. Data Structure Reference
Table 2. TN_AMP Structure
Field
Description
tn_fq1_minamp
Length: 2 (short int)
Default: -42
Range: -42 dBm to 0 dBm
Units: dBm
First frequency minimum amplitude. Specifies
in dBm the minimum amplitude of the tone
with the lower frequency.
The value 0 sets the amplitude to the default
(-42).
tn_fq1_maxamp
Length: 2 (short int)
Default: 0
Range: -42 dBm to 0 dBm
Units: dBm
First frequency maximum amplitude. Specifies
in dBm the maximum amplitude of the tone
with the lower frequency.
The value 0 sets the amplitude to the default
(0).
tn_fq2_minamp
Length: 2 (short int)
Default: -42
Range: -42 dBm to 0 dBm
Units: dBm
Second frequency minimum amplitude.
Specifies in dBm the minimum amplitude of
the tone with the higher frequency.
The value 0 sets the amplitude to the default
(-42).
tn_fq2_maxamp
Length: 2 (short int)
Default: 0
Range: -42 dBm to 0 dBm
Units: dBm
Second frequency maximum amplitude.
Specifies in dBm the maximum amplitude of
the tone with the higher frequency.
109
Dialogic® Learn Mode and Tone Set File API Software Reference
Field
Description
The value 0 sets the amplitude to the default
(0).
7.4. TN_DESC: Tone Description
The TN_DESC structure is declared as follows:
typedef struct {
TN_FREQ
tn_freq;
TN_DUR
tn_dur;
unsigned short int tn_qualid;
} TN_DESC;
/* input/output frequency structure */
/* input/output duration structure */
/* output qualification ID
*/
The TN_DESC structure specifies the characteristics of a tone.
The TN_DESC structure is used in two different parameters of the
lm_LearnTone( ) function, and serves the following purposes:
•
tn_rangep (input): Specifies optional tone learning boundaries as input to
the lm_LearnTone( ) function, restricting learning to the specified range.
•
tn_tonep (input): Specifies an existing tone description as optional input to
the lm_LearnTone( ) function, and which learn mode incorporates in the
final tone description.
•
tn_tonep (output): Provides the final tone description that is returned by
lm_LearnTone( ).
NOTE: Set any field to 0 to use the default value.
Use the lm_clrdesc( ) function to clear the fields of a TN_DESC structure,
including the fields in the TN_FREQ and TN_DUR structures.
Table 3. TN_DESC Structure
Field
Description
tn_freq
Frequency parameters. Specifies the
frequency information in the TN_FREQ data
structure. See TN_FREQ data structure.
110
7. Data Structure Reference
Field
Description
tn_dur
Cadence parameters. Specifies the cadence
information in the TN_DUR data structure.
See TN_DUR data structure.
tn_qualid
Length: 2 (unsigned short int)
Default: QT_LMMID
Output qualification ID. Returns in tn_tonep
the qualification ID associated with the tone
description. This ID matches the input
qualification ID specified in LM_PARM
lm_qualid. Before creating the tone for global
tone detection or call progress analysis, you
must use the dx_selqual( ) function to select
the qualification ID that is returned here. This
field is not used for TN_DESC tn_tonep
input or TN_DESC tn_rangep input.
QT_LMLOW: Low qualification (poor line
quality).
QT_LMMID: Middle qualification (medium
line quality).
QT_LMHIGH: High qualification (high line
quality).
7.5. TN_DUR: Tone Duration
The TN_DUR structure is declared as follows:
typedef struct {
short int tn_on;
short int tn_ondev;
short int tn_off;
short int tn_offdev;
} TN_DUR;
/*
/*
/*
/*
Cadence on-time (10msec)
on-time deviation (10msec)
Cadence off-time (10msec)
off-time deviation (10msec)
*/
*/
*/
*/
The TN_DUR structure specifies cadence information for a tone and is a member
of the TN_DESC structure.
The TN_DESC structure is used in two different parameters of the
lm_LearnTone( ) function, and serves the following purposes:
111
Dialogic® Learn Mode and Tone Set File API Software Reference
•
tn_rangep (input): Specifies optional tone learning boundaries as input to
the lm_LearnTone( ) function, restricting learning to the specified range.
•
tn_tonep (input): Specifies an existing tone description as optional input to
the lm_LearnTone( ) function, and which learn mode incorporates in the
final tone description.
•
tn_tonep (output): Provides the final tone description that is returned by
lm_LearnTone( ).
Use the lm_clrdesc( ) function to clear the fields of a TN_DESC structure,
including the fields in the TN_FREQ and TN_DUR structures.
Table 4. TN_DUR Structure
Field
Description
tn_on
Length: 2 (short int)
Units: 10 ms
Range: 0 – 1000
Tone-on time. Specifies the tone-on duration
in 10 ms units for the tone cadence.
tn_ondev
Length: 2 (short int)
Units: 10 ms
Range: -1000 – 1000
Tone-on time deviation. Specifies the
deviation of the tone-on duration in 10 ms
units for the tone cadence. This deviation is
subtracted from and added to tn_on to define
the minimum and maximum on-time for the
cadence.
tn_off
Length: 2 (short int)
Units: 10 ms
Range: 0 – 1000
Tone-off time. Specifies the tone-off duration
in 10 ms units for the tone cadence.
112
7. Data Structure Reference
Field
Description
tn_offdev
Length: 2 (short int)
Units: 10 ms
Range: -1000 – 1000
Tone-off time deviation. Specifies the
deviation of the tone-off duration in 10 ms
units for the tone cadence. This deviation is
subtracted from and added to tn_off to define
the minimum and maximum off-time for the
cadence.
7.6. TN_FREQ: Tone Frequency
The TN_FREQ structure is declared as follows:
typedef struct {
unsigned short
unsigned short
unsigned short
unsigned short
} TN_FREQ;
int
int
int
int
tn_freq1;
tn_fq1dev;
tn_freq2;
tn_fq2dev;
/*
/*
/*
/*
1st
1st
2nd
2nd
tone
tone
tone
tone
frequency
deviation
frequency
deviation
*/
*/
*/
*/
The TN_FREQ structure specifies frequency information for a tone and is a
member of the TN_DESC structure.
The TN_DESC structure is used in two different parameters of the
lm_LearnTone( ) function, and serves the following purposes:
•
tn_rangep (input): Specifies optional tone learning boundaries as input to
the lm_LearnTone( ) function, restricting learning to the specified range.
•
tn_tonep (input): Specifies an existing tone description as optional input to
the lm_LearnTone( ) function, and which learn mode incorporates in the
final tone description.
•
tn_tonep (output): Provides the final tone description that is returned by
lm_LearnTone( ).
Use the lm_clrdesc( ) function to clear the fields of a TN_DESC structure,
including the fields in the TN_FREQ and TN_DUR structures.
113
Dialogic® Learn Mode and Tone Set File API Software Reference
Table 5. TN_FREQ Structure
Field
Description
tn_freq1
Length: 2 (unsigned short int)
Units: Hz
Range: 300 Hz – 3000 Hz
Tone 1 frequency: Specifies the frequency of the first
tone in Hz. This information serves different purposes
depending upon where the TN_DESC structure is
specified:
For tn_tonep existing tone input: Set this field to a
non-zero value to adjust an existing tone description
with the lm_LearnTone( ) function; you must specify
in tn_tonep the complete tone description to be
adjusted (also, make sure to set the dflagp location to
specify a flag value for a single or dual tone).
For tn_tonep new tone input: Set this field to zero to
learn a new tone with the lm_LearnTone( ) function;
you must set the dflagp location to specify a flag value
for a single or dual tone.
For tn_tonep output: When lm_LearnTone( ) is
complete, this field returns frequency information for
the final tone description.
For tn_rangep input: Set this field to a non-zero value
to restrict the learning range; you must set the
lm_cadflag field in the LM_PARM structure to
indicate cadence or continuous if you do this.
tn_fq1dev
Length: 2 (unsigned short int)
Units: Hz
Tone 1 frequency deviation: Specifies the frequency
deviation of the first tone in Hz. This deviation is
subtracted from and added to tn_freq1 to define the
tone detection range.
114
7. Data Structure Reference
Field
Description
tn_freq2
Length: 2 (unsigned short int)
Units: Hz
Range: 300 Hz – 3000 Hz
Tone 2 frequency: Specifies the frequency of the
second tone in Hz.
0: Indicates there is no second tone (signal is a single
tone).
tn_fq2dev
Length: 2 (unsigned short int)
Units: Hz
Tone 2 frequency deviation: Specifies the frequency
deviation of the second tone in Hz. This deviation is
subtracted from and added to tn_freq2 to define the
tone detection range.
7.7. TN_INFO: Tone Information
The TN_INFO structure is declared as follows:
typedef struct {
unsigned short
unsigned short
unsigned short
unsigned short
unsigned short
} TN_INFO;
int
int
int
int
int
tn_freq1;
tn_freq2;
tn_on;
tn_off;
tn_rep_cnt;
/*
/*
/*
/*
/*
1st tone frequency in Hz */
2nd tone frequency in Hz */
cadence on-time (10 ms units) */
cadence off-time (10 ms units) */
actual rep count */
The TN_INFO structure description is provided here for reference purposes. This
structure is included in the TN_INFOLIST structure.
The tone information structure (TN_INFO) reports the data on which learn mode
bases the final tone description. It provides the actual frequency and actual on/off
times for each frame (sample) of a detected tone. This information is used
primarily for debugging. If the final tone description does not detect a tone as
desired, you can analyze this data to obtain an accurate picture of the tone.
115
Dialogic® Learn Mode and Tone Set File API Software Reference
Table 6. TN_INFO Structure
Parameter
Description
tn_freq1
Length: 2 (unsigned short int)
Units: Hz
Frequency 1: Returns the frequency in Hz of the first
tone in the tone sample.
tn_freq2
Length: 2 (unsigned short int)
Units: Hz
Frequency 2: Returns the frequency in Hz of the
second tone in the tone sample.
tn_on
Length: 2 (unsigned short int)
Units: 10 ms
On-time: Returns the tone-on time in 10 ms units for
the tone sample.
tn_off
Length: 2 (unsigned short int)
Units: 10 ms
Off-time: Returns the tone-off time in 10 ms units for
the tone sample.
tn_rep_cnt
Length: 2 (unsigned short int)
Default: 0
Tone-on/off repetition count: Not used for learn mode
tone information (always 0).
7.8. TN_INFOLIST: Tone Information List
The TN_INFOLIST structure is declared as follows:
typedef struct {
TN_INFO *tn_infop;
unsigned short size;
} TN_INFOLIST;
The TN_INFOLIST structure reports the data for each frame (sample) of a
detected tone. This data or tone information is used to determine the final tone
definition. This structure is useful for debugging purposes.
116
7. Data Structure Reference
Table 7. TN_INFOLIST Structure
Field
Description
tn_infop
This field is a pointer to an array of type TN_INFO.
size
This field is the size of the array of TN_INFO passed as
tn_infop. You must allocate sufficient memory for the
array. Suggested size of the array is the number of
lm_frames (stored in LM_PARM structure) + OFFSET
(defined in lmodelib.h) or higher.
See the TN_INFO and LM_PARM data structure
descriptions for more information.
7.9. TONE_INFO
The TONE_INFO structure is declared as follows:
typedef struct {
unsigned short tone_id;
TN_DESC
tn_desc;
TN_AMP
tn_amp
} TONE_INFO;
/* tone ID */
/* tone description structure */
/* tone amplitude structure */
The TONE_INFO structure contains tone template information such as frequency
and cadence for a particular tone.
Table 8. TONE_INFO Structure
Field
Description
tone_id
Specifies the tone ID. Possible values are:
TID_DIAL_LCL
TID_DIAL_INTL
TID_DIAL_XTRA
TID_BUSY1
TID_RNGBK1
TID_BUSY2
TID_RNGBK2
TID_DISCONNECT
TID_FAX1
117
Dialogic® Learn Mode and Tone Set File API Software Reference
Field
Description
TID_FAX2
tn_desc
Specifies tone characteristics in the TN_DESC data
structure. See the TN_DESC data structure for more
information.
tn_amp
Specifies tone amplitude boundaries in the TN_AMP
data structure. See the TN_AMP data structure for more
information.
7.10. TONESET_ID
The TONESET_ID structure is declared as follows:
typedef struct {
unsigned char toneset_name [TONESET_STRING_SIZE];
unsigned char toneset_model [TONESET_STRING_SIZE];
unsigned short isConsolidated;
} TONESET_ID;
/* manufacturer’s name */
/* model name */
/* included in build flag */
The TONESET_ID structure stores the name, model, and build state of a tone set.
Build state indicates whether the tone set is included in the consolidation.
Table 9. TONESET_ID Structure
Field
Description
toneset_name
Contains the manufacturer name of the phone switch.
toneset_model
Contains the model name of the phone switch.
isConsolidated
Indicates whether the tone set is included in the
consolidation of the tones. Possible values are True (1)
or False (0).
7.11. TONESETINFO
The TONESETINFO structure is declared as follows:
typedef struct {
TONE_INFO toneinfo[MAX_TONES];
} TONESETINFO;
/* tone info for all MAX_TONE tones */
The TONESETINFO structure stores tone information for all tones in a tone set.
118
7. Data Structure Reference
Table 10. TONESETINFO Structure
Field
Description
toneinfo
Specifies tone information for all tones in the
TONE_INFO structure (MAX_TONES define sets the
maximum number of tones in a tone set).
7.12. TSF_CONSOLIDATIONOPTIONS
The TSF_CONSOLIDATIONOPTIONS structure is declared as follows:
typedef struct {
int dial_tone_id;
int exclude_default_defs;
} TSF_CONSOLIDATIONOPTIONS;
/* Use the macros TRUE/FALSE */
The TSF_CONSOLIDATIONOPTIONS structure is used to set options for the
consolidation process.
Table 11. TSF_CONSOLIDATIONOPTIONS Structure
Field
Description
dial_tone_id
Specifies the dial tone ID. Possible values are:
TID_DIAL_LCL
TID_DIAL_INTL
TID_DIAL_XTRA
exclude_default_defs
Indicates whether the default tone definitions are
excluded from the consolidation or not. Possible
values are True (1) and False (0).
7.13. TSF_FILE_INFO
The TSF_FILE_INFO structure is declared as follows:
typedef struct {
unsigned short
unsigned short
unsigned short
unsigned short
unsigned short
unsigned short
unsigned short
consolidateflag;
tonesetcount;
maxtones;
dnldtscount;
gtdtscount;
tonesetsize;
dnldsize;
/* TRUE/FALSE - If file contains data
/* Total # of TONESET entries
/* Total # of TONE_INFO entries per ts
/* Total # of DNLD_TSET entries
/* Provisional
/* Size of TONESET structure
/* Size of Download Toneset structure
*/
*/
*/
*/
*/
*/
*/
119
Dialogic® Learn Mode and Tone Set File API Software Reference
unsigned short gtdtssize;
/* Provisional
*/
unsigned short tonesetsinconsolidation; /* Total # of tonesets in build */
unsigned char
tid_dt;
/* Tone ID in build for dial tone
*/
} TSF_FILE_INFO;
The TSF_FILE_INFO structure contains runtime information about an opened
tone set file.
Table 12. TSF_FILE_INFO Structure
Field
Description
consolidateflag
Indicates whether the file contains any consolidated
tone set information. The only valid information is
True = 1 or False = 0.
tonesetcount
Contains the total number of tone set entries.
maxtones
Contains the total number of entries per tone set.
dnldtscount
Contains the total number of consolidated tone sets.
gtdtscount
This field is currently not used and defaults to 0.
tonesetsize
Contains the size of the tone set structure.
dnldsize
Contains the size of the consolidated tone set
structure.
gtdtssize
This field is currently not used and defaults to 0.
tonesetsinconsolidation
Contains the total number of tone sets in the
consolidated build.
tid_dt
Contains the tone set ID in the consolidated build for
the default dial tone.
120
Glossary
analog: 1. A method of telephony transmission in which the signals from
the source (for example, speech in a human conversation) are
converted into an electrical signal that varies continuously over a range
of amplitude values analogous to the original signals. 2. Not digital
signaling. 3. Used to refer to applications that use loop start signaling.
answer supervision: A telephone system feature that returns a
momentary drop in loop current when a connection has been
established. When call progress analysis detects a transient loop current
drop, it returns a connect event.
ASCIIZ string: A null-terminated string of ASCII characters.
asynchronous function: A function that allows program execution to
continue without waiting for a task to complete. To implement an
asynchronous function, an application-defined event handler must be
enabled to trap and process the completed event.
bit mask: A pattern that selects or ignores specific bits in a bit-mapped
control or status field.
bitmap: An entity of data (byte or word) in which individual bits contain
independent control or status information.
board device: A board-level object that can be manipulated by a physical
library. Board devices can be real physical devices, such as a Dialogic®
D/4x Voice Board, or emulated devices.
bps (bits per second): Serial digital stream data rate.
buffer: A block of memory or temporary storage device that holds data
until it can be processed. It is used to compensate for the difference in
the rate of the flow of information (or time occurrence of events) when
transmitting data from one device to another.
bus: An electronic path that allows communication between multiple
points or devices in a system.
busy device: A device that is stopped, being configured, has a
multitasking or non-multitasking or I/O function active on it.
121
Dialogic® Learn Mode and Tone Set File API Software Reference
cadence: A pattern of tones and silence intervals generated by a given
audio signal. Once established, it can be classified as a single ring, a
double ring, or a busy signal by comparing the periods of sound and
silence to establish parameters.
cadence detection: A firmware or voice driver feature that analyzes the
audio signal on the line to detect a repeating pattern of sound and
silence.
call progress analysis: The process used to automatically determine
what happens after an outgoing call is dialed.
CCITT: International Telephone and Telegraph Consultative Committee, a
part of the ICU (International Telecommunications Union) responsible
for formulating telecommunications standards.
channel: 1. When used in reference to a Dialogic® Board that is analog,
an audio path, or the activity happening on that audio path (for
example, when you say the channel goes off-hook). 2. When used in
reference to a Dialogic® Board that is digital, a data path, or the activity
happening on that data path. 3. When used in reference to a bus, an
electrical circuit carrying control information and data.
channel device: A channel-level object that can be manipulated by a
physical library, such as an individual telephone line connection. A
channel is also a subdevice of a board. See subdevice.
CO: Central Office. The telephone company facility where subscriber
lines are linked, through switches, to other subscriber lines (including
local and long distance lines).
configuration file: An unformatted ASCII file that stores device
initialization information for an application.
data structure: C programming term for a data element consisting of
fields, where each field may have a different type definition and length.
The elements of a data structure usually share a common purpose or
functionality, rather than being similar in size, type, etc.
device: A computer peripheral or component that is controlled through a
software device driver. A Dialogic® Voice and/or Network Interface
Board is considered a physical board containing one or more logical
board devices, and each channel on the board is a channel device.
122
Glossary
device channel: A Dialogic voice data path that processes one incoming
or outgoing call at a time (equivalent to the terminal equipment
terminating a phone line).
device driver: Software that acts as an interface between an application
and hardware devices.
device handle: Numerical reference to a device, obtained when a device
is opened using xx_open( ), where xx is the prefix defining the device
to be opened. The device handle is used for all operations on that
device.
device name: Literal reference to a device, used to gain access to the
device via an xx_open( ) function, where xx is the prefix defining the
device to be opened.
digital: Information represented as binary code.
digitize: The process of converting an analog waveform into a digital data
set.
downloaded code: Program instructions and routines that 1. run at the
board level and were previously resident on the board in EPROM and
2. are now loaded during board initialization to a reserved section of
shared RAM.
driver: A software module that provides a defined interface between a
program and the hardware.
DSP: 1. Digital signal processor. A microprocessor with an architecture
that is optimized particularly to perform mathematical algorithms that
manipulate digital signals. 2. Digital signal processing.
DTMF: Dual Tone Multi Frequency. Refers to a method of encoding digits
over analog telephone lines.
dynamic link library (DLL): A file in the Dialogic® HMP Software or
Dialogic® System Release Software that contains the Dialogic library
functions. Compare library.
emulated device: A virtual device whose software interface mimics the
interface of a particular physical device, such as a Dialogic® D/4x
Voice Board that is emulated by a Dialogic® D/240SC Voice Board.
On a functional level, a D/240SC Voice Board is perceived by an
application as six emulated D/4x Voice Boards. See physical device.
123
Dialogic® Learn Mode and Tone Set File API Software Reference
EPROM: Electrically Programmable Read Only Memory.
event: An unsolicited or asynchronous communication from a hardware
device to an operating system, application, or driver. Events are
generally attention-getting messages, allowing a process to know when
a task is complete or when an external event occurs.
firmware: A set of program instructions that are resident (usually in
EPROM) on an expansion board.
frequency detection: A voice driver feature that detects the tri-tone
Special Information Tone (SIT) sequences and other single-frequency
tones from 300Hz to 2100Hz.
global tone detection: A feature that allows the creation and detection of
user-defined tone descriptions on a channel by channel basis.
hook state: A general term for the current line status of the channel:
either on-hook or off-hook. A telephone station is said to be on-hook
when the conductor loop between the station and the switch is open
and no current is flowing. When the loop is closed and current is
flowing, the station is off-hook. These terms are derived from the
position of the old fashioned telephone set receiver in relation to the
mounting hook provided for it.
hook switch: The name given to the circuitry that controls the on-hook
and off-hook state of the voice telephone interface.
I/O: Input/Output.
idle channel: A channel that has no functions active on it.
idle device: A device that has no functions active on it. See busy device.
interrupt request level: A signal sent to the central processing unit (CPU)
to temporarily suspend normal processing and transfer control to an
interrupt handling routine. Interrupts may be generated by conditions
such as completion of an I/O process, detection of hardware failure,
power failures, etc.
IRQ: See interrupt request level.
library: A file in the Dialogic® HMP Software or Dialogic® System
Release Software that contains links to the DLL.
124
Glossary
loop: The physical circuit between the telephone switch and a voice
processing board.
loop current: The current that flows through the circuit from the
telephone switch when the voice device is off-hook.
loop current detection: A voice driver feature that returns a connect after
detecting a loop current drop.
loop start: In an analog environment, an electrical circuit consisting of
two wires (or leads) called tip and ring, which are the two conductors
of a telephone cable pair. The CO provides a voltage (called "talk
battery" or just "battery") to power the line. When the circuit is
complete, this voltage produces a current called loop current. The
circuit provides a method of starting (seizing) a telephone line or trunk
by sending a supervisory signal (going off-hook) to the CO.
MF: Multifrequency. An in-band signaling transmission scheme similar to
DTMF but used mainly within the Central Office (see CO).
off-hook: The state of a telephone station when the conductor loop
between the station and the switch is closed and current is flowing.
physical device: A device that is an actual piece of hardware, such as a
Dialogic® D/xx Voice Board; not an emulated device. See emulated
device.
pointer: A memory address to either a function or data.
polling: The process of repeatedly checking the status of a resource to
determine when state changes occur.
resolution: Granularity of measurement.
resource: Functionality (e.g., voice-store-and-forward) that can be
assigned to call. Resources are shared when functionality is selectively
assigned to a call (usually via an SCbus or CT Bus time slot) and may
be shared among multiple calls. Resources are dedicated when
functionality is fixed to the one call.
ring detect: The act of sensing that an incoming call is present by
determining that the telephone switch is providing a ringing signal to
the voice device.
route: Assign a resource to a time slot.
125
Dialogic® Learn Mode and Tone Set File API Software Reference
sampling rate: Frequency with which a digitizer takes measurements of
the analog voice signal.
shared resource: See resource.
signaling: The transmission of electrical signals on the telephone
network. The Dialogic® Voice Software supports the following
signaling methods: DTMF, MF, R2 MF, Socotel, global tone detection
and generation, and dial pulse detection and generation.
SIT: Special Information Tone. Detection of a SIT sequence indicates an
operator intercept or other problem in completing the call. See also
frequency detection.
string: A data element consisting of a collection of contiguous ASCII
characters.
subdevice: Any device that is a direct child of another device. Since
subdevice describes a relationship between devices, a subdevice can be
a device that is a direct child of another subdevice (as a channel is a
child of a board).
time slot: In a digital telephony environment, a normally continuous and
individual communication (for example, someone speaking on a
telephone) is (1) digitized, (2) broken up into pieces consisting of a
fixed number of bits, (3) combined with pieces of other individual
communications in a regularly repeating, timed sequence
(multiplexed), and (4) transmitted serially over a single telephone line.
The process happens at such a fast rate that, once the pieces are sorted
out and put back together again at the receiving end, the speech is
normal and continuous. Each individual pieced-together
communication is called a time slot.
126
Index
A
DLGCTSFSUPPORT, 24
API library function reference, 29
dxxxlib.h, 27, 103
application development requirements,
19
E
EDX_CADFLAG, 99
B
EDX_CONTIM, 99
blocking functions
description, 15, 19
EDX_FRAMES, 99
EDX_FREQTOL, 99
C
cadenced tone, 19, 21
call progress analysis, 22
call progress tones, 13, 22
channel requirements, 19
clearing structures
TN_AMP, 30
TN_DESC, 32
TSF_CONSOLIDATIONOPTIONS
, 49
EDX_LMDURTOL, 99
EDX_LMMETHOD, 99
EDX_LMPARM, 99
EDX_LMQUALID, 99
EDX_TNAMP, 99
EDX_TNDFLAG, 99
EDX_TNINFO, 99
EDX_TNINVALID, 99
compiling, 27
EDX_TNPARM, 99
consolidated tone set, 13, 57
definition, 21
error codes
learn mode, 99
tone set file, 100
consolidation options structure
description, 119
F
continuous tone, 19, 21
function reference, 29
D
functions
summary, 15
data structures
list, 103
G
DLGCDISCONNECTTONE, 24
global tone detection, 14
DLGCTSFFILEPATH, 24
127
Dialogic® Learn Mode and Tone Set File API Software Reference
header files, 27
LM_PARM
clearing, 34
description, 104
I
lmodelib.h, 27
include files, 27
P
L
PBX Expert utility, 13
learn mode
application requirements and
limitations, 19
hints for using, 20
initiating, 36
pbxsetting.txt, 24
DLGCDISCONNECTTONE value,
24
DLGCTSFFILEPATH value, 24
DLGCTSFSUPPORT value, 24
rules, 25
learn mode parameters structure
clearing, 34
description, 104
S
H
libdxxmt.lib, 28
libdxxx.so, 28
liblmode.lib, 28
liblmode.so, 28
library files, 27
library functions
summary, 15
libsrl.so, 28
libsrlmt.lib, 28
libtsfio.lib, 28
libtsfio.so, 28
linking
library files, 27
lm_clramp( ), 30
lm_clrdesc( ), 32
lm_clrparm( ), 34
lm_LearnTone( ), 36
SIT tones, 20
srllib.h, 27
synchronous functions, 15, 19
T
TN_AMP
clearing, 30
description, 108
TN_DESC
clearing, 32
description, 110
TN_DUR
clearing, 32, 34
description, 111
TN_FREQ
clearing, 32, 34
description, 113
TN_INFO
description, 115
TN_INFOLIST
description, 116
tone
128
Index
characteristics, 19
characterizing, 36
tone amplitude structure
clearing, 30
description, 108
TSF. See tone set file
tsf_ActivateFile( ), 43
tsf_AddToneSet( ), 46
tsf_ClearConsolidationOptions( ), 49
tone description structure
clearing, 32
description, 110
tsf_ClearDefaultToneSetToConsolidate(
), 52
tone duration structure
description, 111
tsf_ConsolidateToneSets( ), 57
tone frequency structure
description, 113
TSF_CONSOLIDATIONOPTIONS
structure
description, 119
tone information list structure
description, 116
tsf_DeleteToneSet( ), 60
tone information structure
description, 115, 117
tone set
definition, 21
tone set file
definition, 21
tone set file information structure
description, 120
tone set identification structure
description, 118
tsf_CloseFile( ), 55
tsf_DuplicateToneSet( ), 62
TSF_FILE_INFO structure
description, 120
tsf_GetConsolidatedToneSet( ), 65
tsf_GetConsolidatedToneSetKeys( ), 68
tsf_GetDefaultToneSetInConsolidation(
), 71
tsf_GetFileInformation( ), 74
tsf_GetNumberOfToneSets( ), 77
tone set information structure
description, 118
tsf_GetNumberOfToneSetsConsolidated
( ), 79
tone sets
consolidating, 57
tsf_GetToneSet( ), 81
TONE_INFO structure
description, 117
tsf_GetToneSetName( ), 87
TONESET_ID structure
description, 118
TONESETINFO structure
description, 118
tri-tone sequence, 19
tsf_GetToneSetKeys( ), 84
tsf_ModifyToneSet( ), 89
tsf_OpenFile( ), 92
tsf_SaveFile( ), 94
tsf_SetDefaultToneSetToConsolidate( ),
96
129
Dialogic® Learn Mode and Tone Set File API Software Reference
tsfiolib.h, 27, 103
130
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising