← Back to branch summary

~ubuntu-branches/debian/sid/sflphone/sid

« 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: 2013-06-02 18:04:11 UTC
  • mfrom: (1.1.9)
  • Revision ID: package-import@ubuntu.com-20130602180411-3rcpy8c1zdlo8y0s
Tags: 1.2.2-1
* New upstream release
* changeset_rb68857a4b485b7d43f92714cd5792595ff895f82.diff - fix QTest
* pjproject ./configure --disable-sound --disable-video

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__ */