Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjmedia / include / pjmedia / session.h
1 /* $Id$ */
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__ */