← Back to branch summary

~ubuntu-branches/ubuntu/trusty/sflphone/trusty

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/pjmedia/include/pjmedia/tonegen.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (4.3.4 sid)
  • Revision ID: package-import@ubuntu.com-20140128182336-jrsv0k9u6cawc068
Tags: 1.3.0-1
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/pjmedia/include/pjmedia/tonegen.h
 
1
/* $Id: tonegen.h 3553 2011-05-05 06:14:19Z nanang $ */
 
2
/* 
 
3
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
 
4
 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
 
5
 *
 
6
 * This program is free software; you can redistribute it and/or modify
 
7
 * it under the terms of the GNU General Public License as published by
 
8
 * the Free Software Foundation; either version 2 of the License, or
 
9
 * (at your option) any later version.
 
10
 *
 
11
 * This program is distributed in the hope that it will be useful,
 
12
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 
13
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
14
 * GNU General Public License for more details.
 
15
 *
 
16
 * You should have received a copy of the GNU General Public License
 
17
 * along with this program; if not, write to the Free Software
 
18
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 
19
 */
 
20
#ifndef __PJMEDIA_TONEGEN_PORT_H__
 
21
#define __PJMEDIA_TONEGEN_PORT_H__
 
22
 
 
23
/**
 
24
 * @file tonegen.h
 
25
 * @brief Tone (sine, MF, DTMF) generator media port.
 
26
 */
 
27
#include <pjmedia/port.h>
 
28
 
 
29
 
 
30
/**
 
31
 * @defgroup PJMEDIA_MF_DTMF_TONE_GENERATOR Multi-frequency tone generator
 
32
 * @ingroup PJMEDIA_PORT
 
33
 * @brief Multi-frequency tone generator
 
34
 * @{
 
35
 *
 
36
 * This page describes tone generator media port. A tone generator can be
 
37
 * used to generate a single frequency sine wave or dual frequency tones
 
38
 * such as DTMF.
 
39
 *
 
40
 * The tone generator media port provides two functions to generate tones.
 
41
 * The function #pjmedia_tonegen_play() can be used to generate arbitrary
 
42
 * single or dual frequency tone, and #pjmedia_tonegen_play_digits() is
 
43
 * used to play digits such as DTMF. Each tone specified in the playback
 
44
 * function has individual on and off signal duration that must be
 
45
 * specified by application.
 
46
 *
 
47
 * In order to play digits such as DTMF, the tone generator is equipped
 
48
 * with digit map, which contain information about the frequencies of
 
49
 * the digits. The default digit map is DTMF (0-9,a-d,*,#), but application
 
50
 * may specifiy different digit map to the tone generator by calling
 
51
 * #pjmedia_tonegen_set_digit_map() function.
 
52
 */
 
53
 
 
54
PJ_BEGIN_DECL
 
55
 
 
56
 
 
57
/**
 
58
 * This structure describes individual MF digits to be played
 
59
 * with #pjmedia_tonegen_play().
 
60
 */
 
61
typedef struct pjmedia_tone_desc
 
62
{
 
63
    short   freq1;          /**< First frequency.                           */
 
64
    short   freq2;          /**< Optional second frequency.                 */
 
65
    short   on_msec;        /**< Playback ON duration, in miliseconds.      */
 
66
    short   off_msec;       /**< Playback OFF duration, ini miliseconds.    */
 
67
    short   volume;         /**< Volume (1-32767), or 0 for default, which
 
68
                                 PJMEDIA_TONEGEN_VOLUME will be used.       */
 
69
    short   flags;          /**< Currently internal flags, must be 0        */
 
70
} pjmedia_tone_desc;
 
71
 
 
72
 
 
73
 
 
74
/**
 
75
 * This structure describes individual MF digits to be played
 
76
 * with #pjmedia_tonegen_play_digits().
 
77
 */
 
78
typedef struct pjmedia_tone_digit
 
79
{
 
80
    char    digit;          /**< The ASCI identification for the digit.     */
 
81
    short   on_msec;        /**< Playback ON duration, in miliseconds.      */
 
82
    short   off_msec;       /**< Playback OFF duration, ini miliseconds.    */
 
83
    short   volume;         /**< Volume (1-32767), or 0 for default, which
 
84
                                 PJMEDIA_TONEGEN_VOLUME will be used.       */
 
85
} pjmedia_tone_digit;
 
86
 
 
87
 
 
88
/**
 
89
 * This structure describes the digit map which is used by the tone generator
 
90
 * to produce tones from an ASCII digits.
 
91
 * Digit map used by a particular tone generator can be retrieved/set with
 
92
 * #pjmedia_tonegen_get_digit_map() and #pjmedia_tonegen_set_digit_map().
 
93
 */
 
94
typedef struct pjmedia_tone_digit_map
 
95
{
 
96
    unsigned count;         /**< Number of digits in the map.           */
 
97
 
 
98
    struct {
 
99
        char    digit;      /**< The ASCI identification for the digit. */
 
100
        short   freq1;      /**< First frequency.                       */
 
101
        short   freq2;      /**< Optional second frequency.             */
 
102
    } digits[16];           /**< Array of digits in the digit map.      */
 
103
} pjmedia_tone_digit_map;
 
104
 
 
105
 
 
106
/**
 
107
 * Tone generator options.
 
108
 */
 
109
enum
 
110
{
 
111
    /**
 
112
     * Play the tones in loop, restarting playing the first tone after
 
113
     * the last tone has been played.
 
114
     */
 
115
    PJMEDIA_TONEGEN_LOOP    = 1,
 
116
 
 
117
    /**
 
118
     * Disable mutex protection to the tone generator.
 
119
     */
 
120
    PJMEDIA_TONEGEN_NO_LOCK = 2
 
121
};
 
122
 
 
123
 
 
124
/**
 
125
 * Create an instance of tone generator with the specified parameters.
 
126
 * When the tone generator is first created, it will be loaded with the
 
127
 * default digit map.
 
128
 *
 
129
 * @param pool              Pool to allocate memory for the port structure.
 
130
 * @param clock_rate        Sampling rate.
 
131
 * @param channel_count     Number of channels. Currently only mono and stereo
 
132
 *                          are supported.
 
133
 * @param samples_per_frame Number of samples per frame.
 
134
 * @param bits_per_sample   Number of bits per sample. This version of PJMEDIA
 
135
 *                          only supports 16bit per sample.
 
136
 * @param options           Option flags. Application may specify 
 
137
 *                          PJMEDIA_TONEGEN_LOOP to play the tone in a loop.
 
138
 * @param p_port            Pointer to receive the port instance.
 
139
 *
 
140
 * @return                  PJ_SUCCESS on success, or the appropriate
 
141
 *                          error code.
 
142
 */
 
143
PJ_DECL(pj_status_t) pjmedia_tonegen_create(pj_pool_t *pool,
 
144
                                            unsigned clock_rate,
 
145
                                            unsigned channel_count,
 
146
                                            unsigned samples_per_frame,
 
147
                                            unsigned bits_per_sample,
 
148
                                            unsigned options,
 
149
                                            pjmedia_port **p_port);
 
150
 
 
151
 
 
152
/**
 
153
 * Create an instance of tone generator with the specified parameters.
 
154
 * When the tone generator is first created, it will be loaded with the
 
155
 * default digit map.
 
156
 *
 
157
 * @param pool              Pool to allocate memory for the port structure.
 
158
 * @param name              Optional name for the tone generator.
 
159
 * @param clock_rate        Sampling rate.
 
160
 * @param channel_count     Number of channels. Currently only mono and stereo
 
161
 *                          are supported.
 
162
 * @param samples_per_frame Number of samples per frame.
 
163
 * @param bits_per_sample   Number of bits per sample. This version of PJMEDIA
 
164
 *                          only supports 16bit per sample.
 
165
 * @param options           Option flags. Application may specify 
 
166
 *                          PJMEDIA_TONEGEN_LOOP to play the tone in a loop.
 
167
 * @param p_port            Pointer to receive the port instance.
 
168
 *
 
169
 * @return                  PJ_SUCCESS on success, or the appropriate
 
170
 *                          error code.
 
171
 */
 
172
PJ_DECL(pj_status_t) pjmedia_tonegen_create2(pj_pool_t *pool,
 
173
                                             const pj_str_t *name,
 
174
                                             unsigned clock_rate,
 
175
                                             unsigned channel_count,
 
176
                                             unsigned samples_per_frame,
 
177
                                             unsigned bits_per_sample,
 
178
                                             unsigned options,
 
179
                                             pjmedia_port **p_port);
 
180
 
 
181
 
 
182
/**
 
183
 * Check if the tone generator is still busy producing some tones.
 
184
 *
 
185
 * @param tonegen           The tone generator instance.
 
186
 *
 
187
 * @return                  Non-zero if busy.
 
188
 */
 
189
PJ_DECL(pj_bool_t) pjmedia_tonegen_is_busy(pjmedia_port *tonegen);
 
190
 
 
191
 
 
192
/**
 
193
 * Instruct the tone generator to stop current processing.
 
194
 *
 
195
 * @param tonegen           The tone generator instance.
 
196
 *
 
197
 * @return                  PJ_SUCCESS on success.
 
198
 */
 
199
PJ_DECL(pj_status_t) pjmedia_tonegen_stop(pjmedia_port *tonegen);
 
200
 
 
201
 
 
202
/**
 
203
 * Rewind the playback. This will start the playback to the first
 
204
 * tone in the playback list.
 
205
 *
 
206
 * @param tonegen           The tone generator instance.
 
207
 *
 
208
 * @return                  PJ_SUCCESS on success.
 
209
 */
 
210
PJ_DECL(pj_status_t) pjmedia_tonegen_rewind(pjmedia_port *tonegen);
 
211
 
 
212
 
 
213
/**
 
214
 * Instruct the tone generator to play single or dual frequency tones 
 
215
 * with the specified duration. The new tones will be appended to currently
 
216
 * playing tones, unless #pjmedia_tonegen_stop() is called before calling
 
217
 * this function. The playback will begin as soon as  the first get_frame()
 
218
 * is called to the generator.
 
219
 *
 
220
 * @param tonegen           The tone generator instance.
 
221
 * @param count             The number of tones in the array.
 
222
 * @param tones             Array of tones to be played.
 
223
 * @param options           Option flags. Application may specify 
 
224
 *                          PJMEDIA_TONEGEN_LOOP to play the tone in a loop.
 
225
 *
 
226
 * @return                  PJ_SUCCESS on success, or PJ_ETOOMANY if
 
227
 *                          there are too many digits in the queue.
 
228
 */
 
229
PJ_DECL(pj_status_t) pjmedia_tonegen_play(pjmedia_port *tonegen,
 
230
                                          unsigned count,
 
231
                                          const pjmedia_tone_desc tones[],
 
232
                                          unsigned options);
 
233
 
 
234
/**
 
235
 * Instruct the tone generator to play multiple MF digits with each of
 
236
 * the digits having individual ON/OFF duration. Each of the digit in the
 
237
 * digit array must have the corresponding descriptor in the digit map.
 
238
 * The new tones will be appended to currently playing tones, unless 
 
239
 * #pjmedia_tonegen_stop() is called before calling this function. 
 
240
 * The playback will begin as soon as the first get_frame() is called 
 
241
 * to the generator.
 
242
 *
 
243
 * @param tonegen           The tone generator instance.
 
244
 * @param count             Number of digits in the array.
 
245
 * @param digits            Array of MF digits.
 
246
 * @param options           Option flags. Application may specify 
 
247
 *                          PJMEDIA_TONEGEN_LOOP to play the tone in a loop.
 
248
 *
 
249
 * @return                  PJ_SUCCESS on success, or PJ_ETOOMANY if
 
250
 *                          there are too many digits in the queue, or
 
251
 *                          PJMEDIA_RTP_EINDTMF if invalid digit is
 
252
 *                          specified.
 
253
 */
 
254
PJ_DECL(pj_status_t) pjmedia_tonegen_play_digits(pjmedia_port *tonegen,
 
255
                                                 unsigned count,
 
256
                                                 const pjmedia_tone_digit digits[],
 
257
                                                 unsigned options);
 
258
 
 
259
 
 
260
/**
 
261
 * Get the digit-map currently used by this tone generator.
 
262
 *
 
263
 * @param tonegen           The tone generator instance.
 
264
 * @param m                 On output, it will be filled with the pointer to
 
265
 *                          the digitmap currently used by the tone generator.
 
266
 *
 
267
 * @return                  PJ_SUCCESS on success.
 
268
 */
 
269
PJ_DECL(pj_status_t) pjmedia_tonegen_get_digit_map(pjmedia_port *tonegen,
 
270
                                                   const pjmedia_tone_digit_map **m);
 
271
 
 
272
 
 
273
/**
 
274
 * Set digit map to be used by the tone generator.
 
275
 *
 
276
 * @param tonegen           The tone generator instance.
 
277
 * @param m                 Digitmap to be used by the tone generator.
 
278
 *
 
279
 * @return                  PJ_SUCCESS on success.
 
280
 */
 
281
PJ_DECL(pj_status_t) pjmedia_tonegen_set_digit_map(pjmedia_port *tonegen,
 
282
                                                   pjmedia_tone_digit_map *m);
 
283
 
 
284
 
 
285
PJ_END_DECL
 
286
 
 
287
/**
 
288
 * @}
 
289
 */
 
290
 
 
291
 
 
292
#endif  /* __PJMEDIA_TONEGEN_PORT_H__ */
 
293