← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to sflphone-common/libs/pjproject/pjmedia/include/pjmedia/clock.h

  • Committer: Package Import Robot
  • Author(s): Francois Marier
  • Date: 2011-11-25 13:24:12 UTC
  • mfrom: (4.1.10 sid)
  • Revision ID: package-import@ubuntu.com-20111125132412-dc4qvhyosk74cd42
Tags: 1.0.1-4
http://bugs.debian.org/649726
Don't assume that arch:all packages will get built (closes: #649726)

Show diffs side-by-side

added added

removed removed

Lines of Context:
sflphone-common/libs/pjproject/pjmedia/include/pjmedia/clock.h
1
 
/* $Id: clock.h 2394 2008-12-23 17:27:53Z bennylp $ */
2
 
/* 
3
 
 * Copyright (C) 2008-2009 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
 
 *  Additional permission under GNU GPL version 3 section 7:
21
 
 *
22
 
 *  If you modify this program, or any covered work, by linking or
23
 
 *  combining it with the OpenSSL project's OpenSSL library (or a
24
 
 *  modified version of that library), containing parts covered by the
25
 
 *  terms of the OpenSSL or SSLeay licenses, Teluu Inc. (http://www.teluu.com)
26
 
 *  grants you additional permission to convey the resulting work.
27
 
 *  Corresponding Source for a non-source form of such a combination
28
 
 *  shall include the source code for the parts of OpenSSL used as well
29
 
 *  as that of the covered work.
30
 
 */
31
 
#ifndef __PJMEDIA_CLOCK_H__
32
 
#define __PJMEDIA_CLOCK_H__
33
 
 
34
 
/**
35
 
 * @file clock.h
36
 
 * @brief Media clock.
37
 
 */
38
 
#include <pjmedia/types.h>
39
 
 
40
 
 
41
 
/**
42
 
 * @defgroup PJMEDIA_PORT_CLOCK Clock/Timing
43
 
 * @ingroup PJMEDIA_PORT
44
 
 * @brief Various types of classes that provide timing.
45
 
 * @{
46
 
 
47
 
 The media clock/timing extends the media port concept that is explained 
48
 
 in @ref PJMEDIA_PORT. When clock is present in the ports 
49
 
 interconnection, media will flow automatically (and with correct timing too!)
50
 
 from one media port to another.
51
 
 
52
 
 There are few objects in PJMEDIA that are able to provide clock/timing
53
 
 to media ports interconnection:
54
 
 
55
 
 - @ref PJMED_SND_PORT\n
56
 
   The sound device makes a good candidate as the clock source, and
57
 
   PJMEDIA @ref PJMED_SND is designed so that it is able to invoke
58
 
   operations according to timing driven by the sound hardware clock
59
 
   (this may sound complicated, but actually it just means that
60
 
   the sound device abstraction provides callbacks to be called when
61
 
   it has/wants media frames).\n
62
 
   See @ref PJMED_SND_PORT for more details.
63
 
 
64
 
 - @ref PJMEDIA_MASTER_PORT\n
65
 
   The master port uses @ref PJMEDIA_CLOCK as the clock source. By using
66
 
   @ref PJMEDIA_MASTER_PORT, it is possible to interconnect passive
67
 
   media ports and let the frames flow automatically in timely manner.\n
68
 
   Please see @ref PJMEDIA_MASTER_PORT for more details.
69
 
 
70
 
 @}
71
 
 */
72
 
 
73
 
 
74
 
/**
75
 
 * @addtogroup PJMEDIA_CLOCK Clock Generator
76
 
 * @ingroup PJMEDIA_PORT_CLOCK
77
 
 * @brief Interface for generating clock.
78
 
 * @{
79
 
 * 
80
 
 * The clock generator provides the application with media timing,
81
 
 * and it is used by the @ref PJMEDIA_MASTER_PORT for its sound clock.
82
 
 *
83
 
 * The clock generator may be configured to run <b>asynchronously</b> 
84
 
 * (the default behavior) or <b>synchronously</b>. When it is run 
85
 
 * asynchronously, it will call the application's callback every time
86
 
 * the clock <b>tick</b> expires. When it is run synchronously, 
87
 
 * application must continuously polls the clock generator to synchronize
88
 
 * the timing.
89
 
 */
90
 
 
91
 
PJ_BEGIN_DECL
92
 
 
93
 
 
94
 
/**
95
 
 * Opaque declaration for media clock.
96
 
 */
97
 
typedef struct pjmedia_clock pjmedia_clock;
98
 
 
99
 
 
100
 
/**
101
 
 * Options when creating the clock.
102
 
 */
103
 
enum pjmedia_clock_options
104
 
{
105
 
    /**
106
 
     * Prevents the clock from running asynchronously. In this case,
107
 
     * application must poll the clock continuously by calling
108
 
     * #pjmedia_clock_wait() in order to synchronize timing.
109
 
     */
110
 
    PJMEDIA_CLOCK_NO_ASYNC  = 1,
111
 
 
112
 
    /**
113
 
     * Prevent the clock from setting it's thread to highest priority.
114
 
     */
115
 
    PJMEDIA_CLOCK_NO_HIGHEST_PRIO = 2
116
 
};
117
 
 
118
 
 
119
 
/**
120
 
 * Type of media clock callback.
121
 
 *
122
 
 * @param ts                Current timestamp, in samples.
123
 
 * @param user_data         Application data that is passed when
124
 
 *                          the clock was created.
125
 
 */
126
 
typedef void pjmedia_clock_callback(const pj_timestamp *ts,
127
 
                                    void *user_data);
128
 
 
129
 
 
130
 
 
131
 
/**
132
 
 * Create media clock.
133
 
 *
134
 
 * @param pool              Pool to allocate memory.
135
 
 * @param clock_rate        Number of samples per second.
136
 
 * @param channel_count     Number of channel.
137
 
 * @param samples_per_frame Number of samples per frame. This argument
138
 
 *                          along with clock_rate and channel_count, specifies 
139
 
 *                          the interval of each clock run (or clock ticks).
140
 
 * @param options           Bitmask of pjmedia_clock_options.
141
 
 * @param cb                Callback to be called for each clock tick.
142
 
 * @param user_data         User data, which will be passed to the callback.
143
 
 * @param p_clock           Pointer to receive the clock instance.
144
 
 *
145
 
 * @return                  PJ_SUCCESS on success, or the appropriate error
146
 
 *                          code.
147
 
 */
148
 
PJ_DECL(pj_status_t) pjmedia_clock_create( pj_pool_t *pool,
149
 
                                           unsigned clock_rate,
150
 
                                           unsigned channel_count,
151
 
                                           unsigned samples_per_frame,
152
 
                                           unsigned options,
153
 
                                           pjmedia_clock_callback *cb,
154
 
                                           void *user_data,
155
 
                                           pjmedia_clock **p_clock);
156
 
 
157
 
/**
158
 
 * Start the clock. For clock created with asynchronous flag set to TRUE,
159
 
 * this may start a worker thread for the clock (depending on the 
160
 
 * backend clock implementation being used).
161
 
 *
162
 
 * @param clock             The media clock.
163
 
 *
164
 
 * @return                  PJ_SUCCES on success.
165
 
 */
166
 
PJ_DECL(pj_status_t) pjmedia_clock_start(pjmedia_clock *clock);
167
 
 
168
 
 
169
 
/**
170
 
 * Stop the clock.
171
 
 *
172
 
 * @param clock             The media clock.
173
 
 *
174
 
 * @return                  PJ_SUCCES on success.
175
 
 */
176
 
PJ_DECL(pj_status_t) pjmedia_clock_stop(pjmedia_clock *clock);
177
 
 
178
 
 
179
 
 
180
 
/**
181
 
 * Poll the media clock, and execute the callback when the clock tick has
182
 
 * elapsed. This operation is only valid if the clock is created with async
183
 
 * flag set to FALSE.
184
 
 *
185
 
 * @param clock             The media clock.
186
 
 * @param wait              If non-zero, then the function will block until
187
 
 *                          a clock tick elapsed and callback has been called.
188
 
 * @param ts                Optional argument to receive the current 
189
 
 *                          timestamp.
190
 
 *
191
 
 * @return                  Non-zero if clock tick has elapsed, or FALSE if
192
 
 *                          the function returns before a clock tick has
193
 
 *                          elapsed.
194
 
 */
195
 
PJ_DECL(pj_bool_t) pjmedia_clock_wait(pjmedia_clock *clock,
196
 
                                      pj_bool_t wait,
197
 
                                      pj_timestamp *ts);
198
 
 
199
 
 
200
 
/**
201
 
 * Destroy the clock.
202
 
 *
203
 
 * @param clock             The media clock.
204
 
 *
205
 
 * @return                  PJ_SUCCES on success.
206
 
 */
207
 
PJ_DECL(pj_status_t) pjmedia_clock_destroy(pjmedia_clock *clock);
208
 
 
209
 
 
210
 
 
211
 
PJ_END_DECL
212
 
 
213
 
/**
214
 
 * @}
215
 
 */
216
 
 
217
 
 
218
 
#endif  /* __PJMEDIA_CLOCK_H__ */
219