← Back to branch summary

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

« back to all changes in this revision

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

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
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/session.h
1
 
/* $Id: session.h 3841 2011-10-24 09:28:13Z ming $ */
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_SESSION_H__
21
 
#define __PJMEDIA_SESSION_H__
22
 
 
23
 
 
24
 
/**
25
 
 * @file session.h
26
 
 * @brief Media Session.
27
 
 */
28
 
 
29
 
#include <pjmedia/endpoint.h>
30
 
#include <pjmedia/stream.h>
31
 
#include <pjmedia/sdp.h>
32
 
 
33
 
PJ_BEGIN_DECL
34
 
 
35
 
/**
36
 
 * @defgroup PJMEDIA_SESSION Media Sessions
37
 
 * @brief Management of media sessions
38
 
 * @{
39
 
 *
40
 
 * A media session represents multimedia communication between two
41
 
 * parties. A media session represents the multimedia session that
42
 
 * is described by SDP session descriptor. A media session consists
43
 
 * of one or more media streams (pjmedia_stream), where each stream
44
 
 * represents one media line (m= line) in SDP.
45
 
 *
46
 
 * This module provides functions to create and manage multimedia
47
 
 * sessions.
48
 
 *
49
 
 * Application creates the media session by calling #pjmedia_session_create(),
50
 
 * normally after it has completed negotiating both SDP offer and answer.
51
 
 * The session creation function creates the media session (including
52
 
 * media streams) based on the content of local and remote SDP.
53
 
 */
54
 
 
55
 
 
56
 
/**
57
 
 * Session info, retrieved from a session by calling
58
 
 * #pjmedia_session_get_info().
59
 
 */
60
 
struct pjmedia_session_info
61
 
{
62
 
    /** Number of streams. */
63
 
    unsigned            stream_cnt;
64
 
 
65
 
    /** Individual stream info. */
66
 
    pjmedia_stream_info stream_info[PJMEDIA_MAX_SDP_MEDIA];
67
 
};
68
 
 
69
 
 
70
 
/**
71
 
 * Opaque declaration of media session.
72
 
 */
73
 
typedef struct pjmedia_session pjmedia_session;
74
 
 
75
 
 
76
 
/**
77
 
 * @see pjmedia_session_info.
78
 
 */
79
 
typedef struct pjmedia_session_info pjmedia_session_info;
80
 
 
81
 
 
82
 
/**
83
 
 * This function will initialize the session info based on information
84
 
 * in both SDP session descriptors. The remaining information will be
85
 
 * taken from default codec parameters. If socket info array is specified,
86
 
 * the socket will be copied to the session info as well.
87
 
 *
88
 
 * @param pool          Pool to allocate memory.
89
 
 * @param endpt         Pjmedia endpoint.
90
 
 * @param max_streams   Maximum number of stream infos to be created.
91
 
 * @param si            Session info structure to be initialized.
92
 
 * @param local         Local SDP session descriptor.
93
 
 * @param remote        Remote SDP session descriptor.
94
 
 *
95
 
 * @return              PJ_SUCCESS if stream info is successfully initialized.
96
 
 */
97
 
PJ_DECL(pj_status_t)
98
 
pjmedia_session_info_from_sdp( pj_pool_t *pool,
99
 
                               pjmedia_endpt *endpt,
100
 
                               unsigned max_streams,
101
 
                               pjmedia_session_info *si,
102
 
                               const pjmedia_sdp_session *local,
103
 
                               const pjmedia_sdp_session *remote);
104
 
 
105
 
 
106
 
/**
107
 
 * This function will initialize the stream info based on information
108
 
 * in both SDP session descriptors for the specified stream index.
109
 
 * The remaining information will be taken from default codec parameters.
110
 
 * If socket info array is specified, the socket will be copied to the
111
 
 * session info as well.
112
 
 *
113
 
 * @param si            Stream info structure to be initialized.
114
 
 * @param pool          Pool to allocate memory.
115
 
 * @param endpt         PJMEDIA endpoint instance.
116
 
 * @param local         Local SDP session descriptor.
117
 
 * @param remote        Remote SDP session descriptor.
118
 
 * @param stream_idx    Media stream index in the session descriptor.
119
 
 *
120
 
 * @return              PJ_SUCCESS if stream info is successfully initialized.
121
 
 */
122
 
PJ_DECL(pj_status_t)
123
 
pjmedia_stream_info_from_sdp( pjmedia_stream_info *si,
124
 
                              pj_pool_t *pool,
125
 
                              pjmedia_endpt *endpt,
126
 
                              const pjmedia_sdp_session *local,
127
 
                              const pjmedia_sdp_session *remote,
128
 
                              unsigned stream_idx);
129
 
 
130
 
/**
131
 
 * Create media session based on the local and remote SDP. After the session
132
 
 * has been created, application normally would want to get the media port
133
 
 * interface of each streams, by calling #pjmedia_session_get_port(). The
134
 
 * media port interface exports put_frame() and get_frame() function, used
135
 
 * to transmit and receive media frames from the stream.
136
 
 *
137
 
 * Without application calling put_frame() and get_frame(), there will be
138
 
 * no media frames transmitted or received by the session.
139
 
 *
140
 
 * @param endpt         The PJMEDIA endpoint instance.
141
 
 * @param si            Session info containing stream count and array of
142
 
 *                      stream info. The stream count indicates how many
143
 
 *                      streams to be created in the session.
144
 
 * @param transports    Array of media stream transports, with
145
 
 *                      sufficient number of elements (one for each stream).
146
 
 * @param user_data     Arbitrary user data to be kept in the session.
147
 
 * @param p_session     Pointer to receive the media session.
148
 
 *
149
 
 * @return              PJ_SUCCESS if media session can be created
150
 
 *                      successfully.
151
 
 */
152
 
PJ_DECL(pj_status_t)
153
 
pjmedia_session_create( pjmedia_endpt *endpt,
154
 
                        const pjmedia_session_info *si,
155
 
                        pjmedia_transport *transports[],
156
 
                        void *user_data,
157
 
                        pjmedia_session **p_session );
158
 
 
159
 
 
160
 
/**
161
 
 * Get media session info of the session.
162
 
 *
163
 
 * @param session       The session which info is being queried.
164
 
 * @param info          Pointer to receive session info.
165
 
 *
166
 
 * @return              PJ_SUCCESS on success.
167
 
 */
168
 
PJ_DECL(pj_status_t) pjmedia_session_get_info( pjmedia_session *session,
169
 
                                               pjmedia_session_info *info );
170
 
 
171
 
/**
172
 
 * Get user data of the session.
173
 
 *
174
 
 * @param session       The session being queried.
175
 
 *
176
 
 * @return              User data of the session.
177
 
 */
178
 
PJ_DECL(void*) pjmedia_session_get_user_data( pjmedia_session *session);
179
 
 
180
 
 
181
 
/**
182
 
 * Activate all streams in media session for the specified direction.
183
 
 * Application only needs to call this function if it previously paused
184
 
 * the session.
185
 
 *
186
 
 * @param session       The media session.
187
 
 * @param dir           The direction to activate.
188
 
 *
189
 
 * @return              PJ_SUCCESS if success.
190
 
 */
191
 
PJ_DECL(pj_status_t) pjmedia_session_resume(pjmedia_session *session,
192
 
                                            pjmedia_dir dir);
193
 
 
194
 
 
195
 
/**
196
 
 * Suspend receipt and transmission of all streams in media session
197
 
 * for the specified direction.
198
 
 *
199
 
 * @param session       The media session.
200
 
 * @param dir           The media direction to suspend.
201
 
 *
202
 
 * @return              PJ_SUCCESS if success.
203
 
 */
204
 
PJ_DECL(pj_status_t) pjmedia_session_pause(pjmedia_session *session,
205
 
                                           pjmedia_dir dir);
206
 
 
207
 
/**
208
 
 * Suspend receipt and transmission of individual stream in media session
209
 
 * for the specified direction.
210
 
 *
211
 
 * @param session       The media session.
212
 
 * @param index         The stream index.
213
 
 * @param dir           The media direction to pause.
214
 
 *
215
 
 * @return              PJ_SUCCESS on success.
216
 
 */
217
 
PJ_DECL(pj_status_t) pjmedia_session_pause_stream( pjmedia_session *session,
218
 
                                                   unsigned index,
219
 
                                                   pjmedia_dir dir);
220
 
 
221
 
/**
222
 
 * Activate individual stream in media session for the specified direction.
223
 
 *
224
 
 * @param session       The media session.
225
 
 * @param index         The stream index.
226
 
 * @param dir           The media direction to activate.
227
 
 *
228
 
 * @return              PJ_SUCCESS on success.
229
 
 */
230
 
PJ_DECL(pj_status_t) pjmedia_session_resume_stream(pjmedia_session *session,
231
 
                                                   unsigned index,
232
 
                                                   pjmedia_dir dir);
233
 
 
234
 
/**
235
 
 * Send RTCP SDES for the session.
236
 
 *
237
 
 * @param session       The media session.
238
 
 *
239
 
 * @return              PJ_SUCCESS on success.
240
 
 */
241
 
PJ_DECL(pj_status_t)
242
 
pjmedia_session_send_rtcp_sdes( const pjmedia_session *session );
243
 
 
244
 
/**
245
 
 * Send RTCP BYE for the session.
246
 
 *
247
 
 * @param session       The media session.
248
 
 *
249
 
 * @return              PJ_SUCCESS on success.
250
 
 */
251
 
PJ_DECL(pj_status_t)
252
 
pjmedia_session_send_rtcp_bye( const pjmedia_session *session );
253
 
 
254
 
/**
255
 
 * Enumerate media streams in the session.
256
 
 *
257
 
 * @param session       The media session.
258
 
 * @param count         On input, specifies the number of elements in
259
 
 *                      the array. On output, the number will be filled
260
 
 *                      with number of streams in the session.
261
 
 * @param strm_info     Array of stream info.
262
 
 *
263
 
 * @return              PJ_SUCCESS on success.
264
 
 */
265
 
PJ_DECL(pj_status_t)
266
 
pjmedia_session_enum_streams( const pjmedia_session *session,
267
 
                              unsigned *count,
268
 
                              pjmedia_stream_info strm_info[]);
269
 
 
270
 
 
271
 
/**
272
 
 * Get the media port interface of the specified stream. The media port
273
 
 * interface declares put_frame() and get_frame() function, which is the
274
 
 * only  way for application to transmit and receive media frames from the
275
 
 * stream.
276
 
 *
277
 
 * @param session       The media session.
278
 
 * @param index         Stream index.
279
 
 * @param p_port        Pointer to receive the media port interface for
280
 
 *                      the specified stream.
281
 
 *
282
 
 * @return              PJ_SUCCESS on success.
283
 
 */
284
 
PJ_DECL(pj_status_t) pjmedia_session_get_port( pjmedia_session *session,
285
 
                                               unsigned index,
286
 
                                               pjmedia_port **p_port);
287
 
 
288
 
 
289
 
/**
290
 
 * Get session statistics. The stream statistic shows various
291
 
 * indicators such as packet count, packet lost, jitter, delay, etc.
292
 
 * See also #pjmedia_session_get_stream_stat_jbuf()
293
 
 *
294
 
 * @param session       The media session.
295
 
 * @param index         Stream index.
296
 
 * @param stat          Stream statistic.
297
 
 *
298
 
 * @return              PJ_SUCCESS on success.
299
 
 */
300
 
PJ_DECL(pj_status_t) pjmedia_session_get_stream_stat(pjmedia_session *session,
301
 
                                                     unsigned index,
302
 
                                                     pjmedia_rtcp_stat *stat);
303
 
 
304
 
 
305
 
/**
306
 
 * Reset session statistics.
307
 
 *
308
 
 * @param session       The media session.
309
 
 * @param index         Stream index.
310
 
 *
311
 
 * @return              PJ_SUCCESS on success.
312
 
 */
313
 
PJ_DECL(pj_status_t) pjmedia_session_reset_stream_stat(pjmedia_session *session,
314
 
                                                       unsigned index);
315
 
 
316
 
 
317
 
#if defined(PJMEDIA_HAS_RTCP_XR) && (PJMEDIA_HAS_RTCP_XR != 0)
318
 
/**
319
 
 * Get extended session statistics. The extended statistic shows reports
320
 
 * from RTCP XR, such as per interval statistics summary (packet count,
321
 
 * packet lost, jitter, etc), VoIP metrics (delay, quality, etc)
322
 
 *
323
 
 * @param session       The media session.
324
 
 * @param index         Stream index.
325
 
 * @param stat_xr       Stream extended statistics.
326
 
 *
327
 
 * @return              PJ_SUCCESS on success.
328
 
 */
329
 
PJ_DECL(pj_status_t) pjmedia_session_get_stream_stat_xr(
330
 
                                             pjmedia_session *session,
331
 
                                             unsigned index,
332
 
                                             pjmedia_rtcp_xr_stat *stat_xr);
333
 
#endif
334
 
 
335
 
 
336
 
/**
337
 
 * Get current jitter buffer state for the specified stream.
338
 
 * See also #pjmedia_session_get_stream_stat()
339
 
 *
340
 
 * @param session       The media session.
341
 
 * @param index         Stream index.
342
 
 * @param state         Jitter buffer state.
343
 
 *
344
 
 * @return              PJ_SUCCESS on success.
345
 
 */
346
 
PJ_DECL(pj_status_t) pjmedia_session_get_stream_stat_jbuf(
347
 
                                            pjmedia_session *session,
348
 
                                            unsigned index,
349
 
                                            pjmedia_jb_state *state);
350
 
 
351
 
/**
352
 
 * Dial DTMF digit to the stream, using RFC 2833 mechanism.
353
 
 *
354
 
 * @param session       The media session.
355
 
 * @param index         The stream index.
356
 
 * @param ascii_digits  String of ASCII digits (i.e. 0-9*##A-B).
357
 
 *
358
 
 * @return              PJ_SUCCESS on success.
359
 
 */
360
 
PJ_DECL(pj_status_t) pjmedia_session_dial_dtmf( pjmedia_session *session,
361
 
                                                unsigned index,
362
 
                                                const pj_str_t *ascii_digits );
363
 
 
364
 
 
365
 
/**
366
 
 * Check if the specified stream has received DTMF digits.
367
 
 *
368
 
 * @param session       The media session.
369
 
 * @param index         The stream index.
370
 
 *
371
 
 * @return              Non-zero (PJ_TRUE) if the stream has DTMF digits.
372
 
 */
373
 
PJ_DECL(pj_status_t) pjmedia_session_check_dtmf( pjmedia_session *session,
374
 
                                                 unsigned index);
375
 
 
376
 
 
377
 
/**
378
 
 * Retrieve DTMF digits from the specified stream.
379
 
 *
380
 
 * @param session       The media session.
381
 
 * @param index         The stream index.
382
 
 * @param ascii_digits  Buffer to receive the digits. The length of this
383
 
 *                      buffer is indicated in the "size" argument.
384
 
 * @param size          On input, contains the maximum digits to be copied
385
 
 *                      to the buffer.
386
 
 *                      On output, it contains the actual digits that has
387
 
 *                      been copied to the buffer.
388
 
 *
389
 
 * @return              PJ_SUCCESS on success.
390
 
 */
391
 
PJ_DECL(pj_status_t) pjmedia_session_get_dtmf( pjmedia_session *session,
392
 
                                               unsigned index,
393
 
                                               char *ascii_digits,
394
 
                                               unsigned *size );
395
 
 
396
 
/**
397
 
 * Set callback to be called upon receiving DTMF digits. If callback is
398
 
 * registered, the stream will not buffer incoming DTMF but rather call
399
 
 * the callback as soon as DTMF digit is received completely.
400
 
 *
401
 
 * @param session       The media session.
402
 
 * @param index         The stream index.
403
 
 * @param cb            Callback to be called upon receiving DTMF digits.
404
 
 *                      The DTMF digits will be given to the callback as
405
 
 *                      ASCII digits.
406
 
 * @param user_data     User data to be returned back when the callback
407
 
 *                      is called.
408
 
 *
409
 
 * @return              PJ_SUCCESS on success.
410
 
 */
411
 
PJ_DECL(pj_status_t)
412
 
pjmedia_session_set_dtmf_callback(pjmedia_session *session,
413
 
                                  unsigned index,
414
 
                                  void (*cb)(pjmedia_stream*,
415
 
                                             void *user_data,
416
 
                                             int digit),
417
 
                                  void *user_data);
418
 
 
419
 
/**
420
 
 * Destroy media session.
421
 
 *
422
 
 * @param session       The media session.
423
 
 *
424
 
 * @return              PJ_SUCCESS if success.
425
 
 */
426
 
PJ_DECL(pj_status_t) pjmedia_session_destroy(pjmedia_session *session);
427
 
 
428
 
 
429
 
 
430
 
/**
431
 
 * @}
432
 
 */
433
 
 
434
 
PJ_END_DECL
435
 
 
436
 
#endif  /* __PJMEDIA_SESSION_H__ */