← Back to branch summary

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

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/clock.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.0.1/pjmedia/include/pjmedia/clock.h
1
 
/* $Id: clock.h 3664 2011-07-19 03:42:28Z 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_CLOCK_H__
21
 
#define __PJMEDIA_CLOCK_H__
22
 
 
23
 
/**
24
 
 * @file clock.h
25
 
 * @brief Media clock.
26
 
 */
27
 
#include <pjmedia/types.h>
28
 
 
29
 
 
30
 
/**
31
 
 * @defgroup PJMEDIA_PORT_CLOCK Clock/Timing
32
 
 * @ingroup PJMEDIA_PORT
33
 
 * @brief Various types of classes that provide timing.
34
 
 * @{
35
 
 
36
 
 The media clock/timing extends the media port concept that is explained
37
 
 in @ref PJMEDIA_PORT. When clock is present in the ports
38
 
 interconnection, media will flow automatically (and with correct timing too!)
39
 
 from one media port to another.
40
 
 
41
 
 There are few objects in PJMEDIA that are able to provide clock/timing
42
 
 to media ports interconnection:
43
 
 
44
 
 - @ref PJMED_SND_PORT\n
45
 
   The sound device makes a good candidate as the clock source, and
46
 
   PJMEDIA @ref PJMED_SND is designed so that it is able to invoke
47
 
   operations according to timing driven by the sound hardware clock
48
 
   (this may sound complicated, but actually it just means that
49
 
   the sound device abstraction provides callbacks to be called when
50
 
   it has/wants media frames).\n
51
 
   See @ref PJMED_SND_PORT for more details.
52
 
 
53
 
 - @ref PJMEDIA_MASTER_PORT\n
54
 
   The master port uses @ref PJMEDIA_CLOCK as the clock source. By using
55
 
   @ref PJMEDIA_MASTER_PORT, it is possible to interconnect passive
56
 
   media ports and let the frames flow automatically in timely manner.\n
57
 
   Please see @ref PJMEDIA_MASTER_PORT for more details.
58
 
 
59
 
 @}
60
 
 */
61
 
 
62
 
 
63
 
/**
64
 
 * @addtogroup PJMEDIA_CLOCK Clock Generator
65
 
 * @ingroup PJMEDIA_PORT_CLOCK
66
 
 * @brief Interface for generating clock.
67
 
 * @{
68
 
 *
69
 
 * The clock generator provides the application with media timing,
70
 
 * and it is used by the @ref PJMEDIA_MASTER_PORT for its sound clock.
71
 
 *
72
 
 * The clock generator may be configured to run <b>asynchronously</b>
73
 
 * (the default behavior) or <b>synchronously</b>. When it is run
74
 
 * asynchronously, it will call the application's callback every time
75
 
 * the clock <b>tick</b> expires. When it is run synchronously,
76
 
 * application must continuously polls the clock generator to synchronize
77
 
 * the timing.
78
 
 */
79
 
 
80
 
PJ_BEGIN_DECL
81
 
 
82
 
/**
83
 
 * Media clock source.
84
 
 */
85
 
typedef struct pjmedia_clock_src
86
 
{
87
 
    pjmedia_type    media_type;     /**< Media type.                */
88
 
    unsigned        clock_rate;     /**< Clock rate.                */
89
 
    unsigned        ptime_usec;     /**< Frame interval (in usec).  */
90
 
    /**
91
 
     * The timestamp field holds an increasing value in samples and its
92
 
     * value is expected to be increased by clock_rate samples per second.
93
 
     */
94
 
    pj_timestamp    timestamp;
95
 
    /**
96
 
     * Timestamp's last update. The last_update field contains a value in
97
 
     * ticks, and it is expected to be increased by pj_get_timestamp_freq()
98
 
     * ticks per second.
99
 
     */
100
 
    pj_timestamp    last_update;
101
 
} pjmedia_clock_src;
102
 
 
103
 
/**
104
 
 * This is an auxiliary function to initialize the media clock source.
105
 
 *
106
 
 * @param clocksrc          The clock source to be initialized.
107
 
 * @param media_type        The media type.
108
 
 * @param clock_rate        The clock rate.
109
 
 * @param ptime_usec        Media frame interval (in usec).
110
 
 *
111
 
 * @return                  PJ_SUCCESS on success.
112
 
 */
113
 
PJ_DECL(pj_status_t) pjmedia_clock_src_init( pjmedia_clock_src *clocksrc,
114
 
                                             pjmedia_type media_type,
115
 
                                             unsigned clock_rate,
116
 
                                             unsigned ptime_usec );
117
 
 
118
 
/**
119
 
 * This function updates the clock source's timestamp. Application should
120
 
 * use this function instead of updating the timestamp directly since this
121
 
 * function will also update the last_update field of the clock source.
122
 
 *
123
 
 * @param clocksrc          The clock source to be updated.
124
 
 * @param timestamp         The new timestamp, can be NULL if the current
125
 
 *                          timestamp does not change (in this case it
126
 
 *                          will only update the last_update field).
127
 
 *
128
 
 * @return                  PJ_SUCCESS on success.
129
 
 */
130
 
PJ_DECL(pj_status_t) pjmedia_clock_src_update( pjmedia_clock_src *clocksrc,
131
 
                                               const pj_timestamp *timestamp );
132
 
 
133
 
/**
134
 
 * This function gets the clock source's current timestamp. Application
135
 
 * should use this function instead of accessing the timestamp directly
136
 
 * since this function will calculate the predicted timestamp for current
137
 
 * time, based on the values of timestamp, last_update, and clock_rate.
138
 
 *
139
 
 * @param clocksrc          The clock source.
140
 
 * @param timestamp         Argument to receive the current timestamp
141
 
 *
142
 
 * @return                  PJ_SUCCESS on success.
143
 
 */
144
 
PJ_DECL(pj_status_t)
145
 
pjmedia_clock_src_get_current_timestamp( const pjmedia_clock_src *clocksrc,
146
 
                                         pj_timestamp *timestamp);
147
 
 
148
 
/**
149
 
 * This function gets the clock source's time in msec.
150
 
 *
151
 
 * @param clocksrc          The clock source.
152
 
 *
153
 
 * @return                  The clock source's time (in msec).
154
 
 */
155
 
PJ_DECL(pj_uint32_t)
156
 
pjmedia_clock_src_get_time_msec( const pjmedia_clock_src *clocksrc );
157
 
 
158
 
 
159
 
/**
160
 
 * Opaque declaration for media clock.
161
 
 */
162
 
typedef struct pjmedia_clock pjmedia_clock;
163
 
 
164
 
 
165
 
/**
166
 
 * Options when creating the clock.
167
 
 */
168
 
enum pjmedia_clock_options
169
 
{
170
 
    /**
171
 
     * Prevents the clock from running asynchronously. In this case,
172
 
     * application must poll the clock continuously by calling
173
 
     * #pjmedia_clock_wait() in order to synchronize timing.
174
 
     */
175
 
    PJMEDIA_CLOCK_NO_ASYNC  = 1,
176
 
 
177
 
    /**
178
 
     * Prevent the clock from setting it's thread to highest priority.
179
 
     */
180
 
    PJMEDIA_CLOCK_NO_HIGHEST_PRIO = 2
181
 
};
182
 
 
183
 
 
184
 
typedef struct pjmedia_clock_param
185
 
{
186
 
    /**
187
 
     * The frame interval, in microseconds.
188
 
     */
189
 
    unsigned usec_interval;
190
 
    /**
191
 
     * The media clock rate, to determine timestamp
192
 
     * increment for each call.
193
 
     */
194
 
    unsigned clock_rate;
195
 
} pjmedia_clock_param;
196
 
 
197
 
/**
198
 
 * Type of media clock callback.
199
 
 *
200
 
 * @param ts                Current timestamp, in samples.
201
 
 * @param user_data         Application data that is passed when
202
 
 *                          the clock was created.
203
 
 */
204
 
typedef void pjmedia_clock_callback(const pj_timestamp *ts,
205
 
                                    void *user_data);
206
 
 
207
 
 
208
 
 
209
 
/**
210
 
 * Create media clock. This creates a media clock object that will run
211
 
 * periodically at an interval that is calculated from the audio parameters.
212
 
 * Once created, application must call #pjmedia_clock_start() to actually
213
 
 * start the clock.
214
 
 *
215
 
 * @see pjmedia_clock_create2()
216
 
 *
217
 
 * @param pool              Pool to allocate memory.
218
 
 * @param clock_rate        Number of samples per second.
219
 
 * @param channel_count     Number of channel.
220
 
 * @param samples_per_frame Number of samples per frame. This argument
221
 
 *                          along with clock_rate and channel_count, specifies
222
 
 *                          the interval of each clock run (or clock ticks).
223
 
 * @param options           Bitmask of pjmedia_clock_options.
224
 
 * @param cb                Callback to be called for each clock tick.
225
 
 * @param user_data         User data, which will be passed to the callback.
226
 
 * @param p_clock           Pointer to receive the clock instance.
227
 
 *
228
 
 * @return                  PJ_SUCCESS on success, or the appropriate error
229
 
 *                          code.
230
 
 */
231
 
PJ_DECL(pj_status_t) pjmedia_clock_create( pj_pool_t *pool,
232
 
                                           unsigned clock_rate,
233
 
                                           unsigned channel_count,
234
 
                                           unsigned samples_per_frame,
235
 
                                           unsigned options,
236
 
                                           pjmedia_clock_callback *cb,
237
 
                                           void *user_data,
238
 
                                           pjmedia_clock **p_clock);
239
 
 
240
 
 
241
 
/**
242
 
 * Create media clock. This creates a media clock object that will run
243
 
 * periodically at the specified interval. Once created, application must
244
 
 * call #pjmedia_clock_start() to actually start the clock.
245
 
 *
246
 
 * @param pool              Pool to allocate memory.
247
 
 * @param param             The clock parameter.
248
 
 * @param options           Bitmask of pjmedia_clock_options.
249
 
 * @param cb                Callback to be called for each clock tick.
250
 
 * @param user_data         User data, which will be passed to the callback.
251
 
 * @param p_clock           Pointer to receive the clock instance.
252
 
 *
253
 
 * @return                  PJ_SUCCESS on success, or the appropriate error
254
 
 *                          code.
255
 
 */
256
 
PJ_DECL(pj_status_t) pjmedia_clock_create2(pj_pool_t *pool,
257
 
                                           const pjmedia_clock_param *param,
258
 
                                           unsigned options,
259
 
                                           pjmedia_clock_callback *cb,
260
 
                                           void *user_data,
261
 
                                           pjmedia_clock **p_clock);
262
 
 
263
 
/**
264
 
 * Start the clock. For clock created with asynchronous flag set to TRUE,
265
 
 * this may start a worker thread for the clock (depending on the
266
 
 * backend clock implementation being used).
267
 
 *
268
 
 * @param clock             The media clock.
269
 
 *
270
 
 * @return                  PJ_SUCCES on success.
271
 
 */
272
 
PJ_DECL(pj_status_t) pjmedia_clock_start(pjmedia_clock *clock);
273
 
 
274
 
 
275
 
/**
276
 
 * Stop the clock.
277
 
 *
278
 
 * @param clock             The media clock.
279
 
 *
280
 
 * @return                  PJ_SUCCES on success.
281
 
 */
282
 
PJ_DECL(pj_status_t) pjmedia_clock_stop(pjmedia_clock *clock);
283
 
 
284
 
 
285
 
/**
286
 
 * Modify the clock's parameter.
287
 
 *
288
 
 * @param clock             The media clock.
289
 
 * @param param             The clock's new parameter.
290
 
 * @return                  PJ_SUCCES on success.
291
 
 */
292
 
PJ_DECL(pj_status_t) pjmedia_clock_modify(pjmedia_clock *clock,
293
 
                                          const pjmedia_clock_param *param);
294
 
 
295
 
 
296
 
/**
297
 
 * Poll the media clock, and execute the callback when the clock tick has
298
 
 * elapsed. This operation is only valid if the clock is created with async
299
 
 * flag set to FALSE.
300
 
 *
301
 
 * @param clock             The media clock.
302
 
 * @param wait              If non-zero, then the function will block until
303
 
 *                          a clock tick elapsed and callback has been called.
304
 
 * @param ts                Optional argument to receive the current
305
 
 *                          timestamp.
306
 
 *
307
 
 * @return                  Non-zero if clock tick has elapsed, or FALSE if
308
 
 *                          the function returns before a clock tick has
309
 
 *                          elapsed.
310
 
 */
311
 
PJ_DECL(pj_bool_t) pjmedia_clock_wait(pjmedia_clock *clock,
312
 
                                      pj_bool_t wait,
313
 
                                      pj_timestamp *ts);
314
 
 
315
 
 
316
 
/**
317
 
 * Destroy the clock.
318
 
 *
319
 
 * @param clock             The media clock.
320
 
 *
321
 
 * @return                  PJ_SUCCES on success.
322
 
 */
323
 
PJ_DECL(pj_status_t) pjmedia_clock_destroy(pjmedia_clock *clock);
324
 
 
325
 
 
326
 
 
327
 
PJ_END_DECL
328
 
 
329
 
/**
330
 
 * @}
331
 
 */
332
 
 
333
 
 
334
 
#endif  /* __PJMEDIA_CLOCK_H__ */