Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjmedia / include / pjmedia / endpoint.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_MEDIAMGR_H__
21 #define __PJMEDIA_MEDIAMGR_H__
22
23
24 /**
25  * @file endpoint.h
26  * @brief Media endpoint.
27  */
28 /**
29  * @defgroup PJMED_ENDPT The Endpoint
30  * @{
31  *
32  * The media endpoint acts as placeholder for endpoint capabilities. Each 
33  * media endpoint will have a codec manager to manage list of codecs installed
34  * in the endpoint and a sound device factory.
35  *
36  * A reference to media endpoint instance is required when application wants
37  * to create a media session (#pjmedia_session_create()).
38  */
39
40 #include <pjmedia/codec.h>
41 #include <pjmedia/sdp.h>
42 #include <pjmedia/transport.h>
43
44
45 PJ_BEGIN_DECL
46
47 /**
48  * This enumeration describes various flags that can be set or retrieved in
49  * the media endpoint, by using pjmedia_endpt_set_flag() and
50  * pjmedia_endpt_get_flag() respectively.
51  */
52 typedef enum pjmedia_endpt_flag
53 {
54     /**
55      * This flag controls whether telephony-event should be offered in SDP.
56      * Value is boolean.
57      */
58     PJMEDIA_ENDPT_HAS_TELEPHONE_EVENT_FLAG
59
60 } pjmedia_endpt_flag;
61
62
63 /**
64  * Type of callback to register to pjmedia_endpt_atexit().
65  */
66 typedef void (*pjmedia_endpt_exit_callback)(pjmedia_endpt *endpt);
67
68
69 /**
70  * Create an instance of media endpoint.
71  *
72  * @param pf            Pool factory, which will be used by the media endpoint
73  *                      throughout its lifetime.
74  * @param ioqueue       Optional ioqueue instance to be registered to the 
75  *                      endpoint. The ioqueue instance is used to poll all RTP
76  *                      and RTCP sockets. If this argument is NULL, the 
77  *                      endpoint will create an internal ioqueue instance.
78  * @param worker_cnt    Specify the number of worker threads to be created
79  *                      to poll the ioqueue.
80  * @param p_endpt       Pointer to receive the endpoint instance.
81  *
82  * @return              PJ_SUCCESS on success.
83  */
84 PJ_DECL(pj_status_t) pjmedia_endpt_create( pj_pool_factory *pf,
85                                            pj_ioqueue_t *ioqueue,
86                                            unsigned worker_cnt,
87                                            pjmedia_endpt **p_endpt);
88
89 /**
90  * Destroy media endpoint instance.
91  *
92  * @param endpt         Media endpoint instance.
93  *
94  * @return              PJ_SUCCESS on success.
95  */
96 PJ_DECL(pj_status_t) pjmedia_endpt_destroy(pjmedia_endpt *endpt);
97
98 /**
99  * Change the value of a flag.
100  *
101  * @param endpt         Media endpoint.
102  * @param flag          The flag.
103  * @param value         Pointer to the value to be set.
104  *
105  * @reurn               PJ_SUCCESS on success.
106  */
107 PJ_DECL(pj_status_t) pjmedia_endpt_set_flag(pjmedia_endpt *endpt,
108                                             pjmedia_endpt_flag flag,
109                                             const void *value);
110
111 /**
112  *  Retrieve the value of a flag.
113  *
114  *  @param endpt        Media endpoint.
115  *  @param flag         The flag.
116  *  @param value        Pointer to store the result.
117  *
118  *  @return             PJ_SUCCESS on success.
119  */
120 PJ_DECL(pj_status_t) pjmedia_endpt_get_flag(pjmedia_endpt *endpt,
121                                             pjmedia_endpt_flag flag,
122                                             void *value);
123
124 /**
125  * Get the ioqueue instance of the media endpoint.
126  *
127  * @param endpt         The media endpoint instance.
128  *
129  * @return              The ioqueue instance of the media endpoint.
130  */
131 PJ_DECL(pj_ioqueue_t*) pjmedia_endpt_get_ioqueue(pjmedia_endpt *endpt);
132
133
134 /**
135  * Get the number of worker threads on the media endpoint
136  *
137  * @param endpt         The media endpoint instance.
138  * @return              The number of worker threads on the media endpoint
139  */
140 PJ_DECL(unsigned) pjmedia_endpt_get_thread_count(pjmedia_endpt *endpt);
141
142 /**
143  * Get a reference to one of the worker threads of the media endpoint 
144  *
145  * @param endpt         The media endpoint instance.
146  * @param index         The index of the thread: 0<= index < thread_cnt
147  *
148  * @return              pj_thread_t or NULL
149  */
150 PJ_DECL(pj_thread_t*) pjmedia_endpt_get_thread(pjmedia_endpt *endpt, 
151                                                unsigned index);
152
153
154 /**
155  * Request the media endpoint to create pool.
156  *
157  * @param endpt         The media endpoint instance.
158  * @param name          Name to be assigned to the pool.
159  * @param initial       Initial pool size, in bytes.
160  * @param increment     Increment size, in bytes.
161  *
162  * @return              Memory pool.
163  */
164 PJ_DECL(pj_pool_t*) pjmedia_endpt_create_pool( pjmedia_endpt *endpt,
165                                                const char *name,
166                                                pj_size_t initial,
167                                                pj_size_t increment);
168
169 /**
170  * Get the codec manager instance of the media endpoint.
171  *
172  * @param endpt         The media endpoint instance.
173  *
174  * @return              The instance of codec manager belonging to
175  *                      this media endpoint.
176  */
177 PJ_DECL(pjmedia_codec_mgr*) pjmedia_endpt_get_codec_mgr(pjmedia_endpt *endpt);
178
179
180 /**
181  * Create a SDP session description that describes the endpoint
182  * capability.
183  *
184  * @param endpt         The media endpoint.
185  * @param pool          Pool to use to create the SDP descriptor.
186  * @param stream_cnt    Number of elements in the sock_info array. This
187  *                      also denotes the maximum number of streams (i.e.
188  *                      the "m=" lines) that will be created in the SDP.
189  *                      By convention, if this value is greater than one,
190  *                      the first media will be audio and the remaining
191  *                      media is video.
192  * @param sock_info     Array of socket transport information. One 
193  *                      transport is needed for each media stream, and
194  *                      each transport consists of an RTP and RTCP socket
195  *                      pair.
196  * @param p_sdp         Pointer to receive SDP session descriptor.
197  *
198  * @return              PJ_SUCCESS on success.
199  */
200 PJ_DECL(pj_status_t) pjmedia_endpt_create_sdp( pjmedia_endpt *endpt,
201                                                pj_pool_t *pool,
202                                                unsigned stream_cnt,
203                                                const pjmedia_sock_info sock_info[],
204                                                pjmedia_sdp_session **p_sdp );
205
206 /**
207  * Create a "blank" SDP session description. The SDP will contain basic SDP
208  * fields such as origin, time, and name, but without any media lines.
209  *
210  * @param endpt         The media endpoint.
211  * @param pool          Pool to allocate memory from.
212  * @param sess_name     Optional SDP session name, or NULL to use default
213  *                      value.
214  * @param origin        Address to put in the origin field.
215  * @param p_sdp         Pointer to receive the created SDP session.
216  *
217  * @return              PJ_SUCCESS on success, or the appropriate error code.
218  */
219 PJ_DECL(pj_status_t) pjmedia_endpt_create_base_sdp(pjmedia_endpt *endpt,
220                                                    pj_pool_t *pool,
221                                                    const pj_str_t *sess_name,
222                                                    const pj_sockaddr *origin,
223                                                    pjmedia_sdp_session **p_sdp);
224
225 /**
226  * Create SDP media line for audio media.
227  *
228  * @param endpt         The media endpoint.
229  * @param pool          Pool to allocate memory from.
230  * @param si            Socket information.
231  * @param options       Option flags, must be zero for now.
232  * @param p_m           Pointer to receive the created SDP media.
233  *
234  * @return              PJ_SUCCESS on success, or the appropriate error code.
235  */
236 PJ_DECL(pj_status_t) pjmedia_endpt_create_audio_sdp(pjmedia_endpt *endpt,
237                                                     pj_pool_t *pool,
238                                                     const pjmedia_sock_info*si,
239                                                     unsigned options,
240                                                     pjmedia_sdp_media **p_m);
241
242 /**
243  * Create SDP media line for video media.
244  *
245  * @param endpt         The media endpoint.
246  * @param pool          Pool to allocate memory from.
247  * @param si            Socket information.
248  * @param options       Option flags, must be zero for now.
249  * @param p_m           Pointer to receive the created SDP media.
250  *
251  * @return              PJ_SUCCESS on success, or the appropriate error code.
252  */
253 PJ_DECL(pj_status_t) pjmedia_endpt_create_video_sdp(pjmedia_endpt *endpt,
254                                                     pj_pool_t *pool,
255                                                     const pjmedia_sock_info*si,
256                                                     unsigned options,
257                                                     pjmedia_sdp_media **p_m);
258
259 /**
260  * Dump media endpoint capabilities.
261  *
262  * @param endpt         The media endpoint.
263  *
264  * @return              PJ_SUCCESS on success.
265  */
266 PJ_DECL(pj_status_t) pjmedia_endpt_dump(pjmedia_endpt *endpt);
267
268
269 /**
270  * Register cleanup function to be called by media endpoint when 
271  * #pjmedia_endpt_destroy() is called. Note that application should not
272  * use or access any endpoint resource (such as pool, ioqueue) from within
273  * the callback as such resource may have been released when the callback
274  * function is invoked.
275  *
276  * @param endpt         The media endpoint.
277  * @param func          The function to be registered.
278  *
279  * @return              PJ_SUCCESS on success.
280  */
281 PJ_DECL(pj_status_t) pjmedia_endpt_atexit(pjmedia_endpt *endpt,
282                                           pjmedia_endpt_exit_callback func);
283
284
285
286 PJ_END_DECL
287
288
289 /**
290  * @}
291  */
292
293
294
295 #endif  /* __PJMEDIA_MEDIAMGR_H__ */