← Back to branch summary

~ubuntu-branches/ubuntu/vivid/sflphone/vivid

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/master_port.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2013-06-30 11:40:56 UTC
  • mfrom: (4.1.18 saucy-proposed)
  • Revision ID: package-import@ubuntu.com-20130630114056-0np50jkyqo6vnmii
Tags: 1.2.3-2
* changeset_r92d62cfc54732bbbcfff2b1d36c096b120b981a5.diff 
  - fixes automatic endian detection 
* Update Vcs: fixes vcs-field-not-canonical

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/master_port.h
 
1
/* $Id: master_port.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_MASTER_PORT_H__
 
21
#define __PJMEDIA_MASTER_PORT_H__
 
22
 
 
23
 
 
24
/**
 
25
 * @file master_port.h
 
26
 * @brief Master port.
 
27
 */
 
28
#include <pjmedia/port.h>
 
29
 
 
30
/**
 
31
 * @defgroup PJMEDIA_MASTER_PORT Master Port
 
32
 * @ingroup PJMEDIA_PORT_CLOCK
 
33
 * @brief Thread based media clock provider
 
34
 * @{
 
35
 *
 
36
 * A master port has two media ports connected to it, and by convention
 
37
 * thay are called downstream and upstream ports. The media stream flowing to
 
38
 * the downstream port is called encoding or send direction, and media stream
 
39
 * flowing to the upstream port is called decoding or receive direction
 
40
 * (imagine the downstream as stream to remote endpoint, and upstream as
 
41
 * local media port; media flowing to remote endpoint (downstream) will need
 
42
 * to be encoded before it is transmitted to remote endpoint).
 
43
 *
 
44
 * A master port internally has an instance of @ref PJMEDIA_CLOCK, which
 
45
 * provides the essensial timing for the master port. The @ref PJMEDIA_CLOCK
 
46
 * runs asynchronously, and whenever a clock <b>tick</b> expires, a callback
 
47
 * will be called, and the master port performs the following tasks:
 
48
 *  - it calls <b><tt>get_frame()</tt></b> from the downstream port,
 
49
 *    when give the frame to the upstream port by calling <b><tt>put_frame
 
50
 *    </tt></b> to the upstream port, and
 
51
 *  - performs the same task, but on the reverse direction (i.e. get the stream
 
52
 *    from upstream port and give it to the downstream port).
 
53
 *
 
54
 * Because master port enables media stream to flow automatically, it is
 
55
 * said that the master port supplies @ref PJMEDIA_PORT_CLOCK to the
 
56
 * media ports interconnection.
 
57
 *
 
58
 */
 
59
 
 
60
PJ_BEGIN_DECL
 
61
 
 
62
 
 
63
/**
 
64
 * Opaque declaration for master port.
 
65
 */
 
66
typedef struct pjmedia_master_port pjmedia_master_port;
 
67
 
 
68
 
 
69
/**
 
70
 * Create a master port.
 
71
 *
 
72
 * @param pool          Pool to allocate master port from.
 
73
 * @param u_port        Upstream port.
 
74
 * @param d_port        Downstream port.
 
75
 * @param options       Options flags, from bitmask combinations from
 
76
 *                      pjmedia_clock_options.
 
77
 * @param p_m           Pointer to receive the master port instance.
 
78
 *
 
79
 * @return              PJ_SUCCESS on success.
 
80
 */
 
81
PJ_DECL(pj_status_t) pjmedia_master_port_create(pj_pool_t *pool,
 
82
                                                pjmedia_port *u_port,
 
83
                                                pjmedia_port *d_port,
 
84
                                                unsigned options,
 
85
                                                pjmedia_master_port **p_m);
 
86
 
 
87
 
 
88
/**
 
89
 * Start the media flow.
 
90
 *
 
91
 * @param m             The master port.
 
92
 *
 
93
 * @return              PJ_SUCCESS on success.
 
94
 */
 
95
PJ_DECL(pj_status_t) pjmedia_master_port_start(pjmedia_master_port *m);
 
96
 
 
97
 
 
98
/**
 
99
 * Stop the media flow.
 
100
 *
 
101
 * @param m             The master port.
 
102
 *
 
103
 * @return              PJ_SUCCESS on success.
 
104
 */
 
105
PJ_DECL(pj_status_t) pjmedia_master_port_stop(pjmedia_master_port *m);
 
106
 
 
107
 
 
108
/**
 
109
 * Poll the master port clock and execute the callback when the clock tick has
 
110
 * elapsed. This operation is only valid if the master port is created with
 
111
 * #PJMEDIA_CLOCK_NO_ASYNC flag.
 
112
 *
 
113
 * @param m                 The master port.
 
114
 * @param wait              If non-zero, then the function will block until
 
115
 *                          a clock tick elapsed and callback has been called.
 
116
 * @param ts                Optional argument to receive the current
 
117
 *                          timestamp.
 
118
 *
 
119
 * @return                  Non-zero if clock tick has elapsed, or FALSE if
 
120
 *                          the function returns before a clock tick has
 
121
 *                          elapsed.
 
122
 */
 
123
PJ_DECL(pj_bool_t) pjmedia_master_port_wait(pjmedia_master_port *m,
 
124
                                            pj_bool_t wait,
 
125
                                            pj_timestamp *ts);
 
126
 
 
127
 
 
128
/**
 
129
 * Change the upstream port. Note that application is responsible to destroy
 
130
 * current upstream port (the one that is going to be replaced with the
 
131
 * new port).
 
132
 *
 
133
 * @param m             The master port.
 
134
 * @param port          Port to be used for upstream port.
 
135
 *
 
136
 * @return              PJ_SUCCESS on success.
 
137
 */
 
138
PJ_DECL(pj_status_t) pjmedia_master_port_set_uport(pjmedia_master_port *m,
 
139
                                                   pjmedia_port *port);
 
140
 
 
141
 
 
142
/**
 
143
 * Get the upstream port.
 
144
 *
 
145
 * @param m             The master port.
 
146
 *
 
147
 * @return              The upstream port.
 
148
 */
 
149
PJ_DECL(pjmedia_port*) pjmedia_master_port_get_uport(pjmedia_master_port*m);
 
150
 
 
151
 
 
152
/**
 
153
 * Change the downstream port. Note that application is responsible to destroy
 
154
 * current downstream port (the one that is going to be replaced with the
 
155
 * new port).
 
156
 *
 
157
 * @param m             The master port.
 
158
 * @param port          Port to be used for downstream port.
 
159
 *
 
160
 * @return              PJ_SUCCESS on success.
 
161
 */
 
162
PJ_DECL(pj_status_t) pjmedia_master_port_set_dport(pjmedia_master_port *m,
 
163
                                                   pjmedia_port *port);
 
164
 
 
165
 
 
166
/**
 
167
 * Get the downstream port.
 
168
 *
 
169
 * @param m             The master port.
 
170
 *
 
171
 * @return              The downstream port.
 
172
 */
 
173
PJ_DECL(pjmedia_port*) pjmedia_master_port_get_dport(pjmedia_master_port*m);
 
174
 
 
175
 
 
176
/**
 
177
 * Destroy the master port, and optionally destroy the upstream and
 
178
 * downstream ports.
 
179
 *
 
180
 * @param m             The master port.
 
181
 * @param destroy_ports If non-zero, the function will destroy both
 
182
 *                      upstream and downstream ports too.
 
183
 *
 
184
 * @return              PJ_SUCCESS on success.
 
185
 */
 
186
PJ_DECL(pj_status_t) pjmedia_master_port_destroy(pjmedia_master_port *m,
 
187
                                                 pj_bool_t destroy_ports);
 
188
 
 
189
 
 
190
 
 
191
PJ_END_DECL
 
192
 
 
193
/**
 
194
 * @}
 
195
 */
 
196
 
 
197
 
 
198
#endif  /* __PJMEDIA_MASTER_PORT_H__ */