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 #include <pjmedia-audiodev/audiodev.h>
44
45
46 PJ_BEGIN_DECL
47
48 /**
49 * This enumeration describes various flags that can be set or retrieved in
50 * the media endpoint, by using pjmedia_endpt_set_flag() and
51 * pjmedia_endpt_get_flag() respectively.
52 */
53 typedef enum pjmedia_endpt_flag
54 {
55 /**
56 * This flag controls whether telephony-event should be offered in SDP.
57 * Value is boolean.
58 */
59 PJMEDIA_ENDPT_HAS_TELEPHONE_EVENT_FLAG
60
61 } pjmedia_endpt_flag;
62
63
64 /**
65 * Type of callback to register to pjmedia_endpt_atexit().
66 */
67 typedef void (*pjmedia_endpt_exit_callback)(pjmedia_endpt *endpt);
68
69
70 /**
71 * Create an instance of media endpoint.
72 *
73 * @param pf Pool factory, which will be used by the media endpoint
74 * throughout its lifetime.
75 * @param ioqueue Optional ioqueue instance to be registered to the
76 * endpoint. The ioqueue instance is used to poll all RTP
77 * and RTCP sockets. If this argument is NULL, the
78 * endpoint will create an internal ioqueue instance.
79 * @param worker_cnt Specify the number of worker threads to be created
80 * to poll the ioqueue.
81 * @param p_endpt Pointer to receive the endpoint instance.
82 *
83 * @return PJ_SUCCESS on success.
84 */
85 PJ_DECL(pj_status_t) pjmedia_endpt_create2(pj_pool_factory *pf,
86 pj_ioqueue_t *ioqueue,
87 unsigned worker_cnt,
88 pjmedia_endpt **p_endpt);
89
90 /**
91 * Create an instance of media endpoint and initialize audio subsystem.
92 *
93 * @param pf Pool factory, which will be used by the media endpoint
94 * throughout its lifetime.
95 * @param ioqueue Optional ioqueue instance to be registered to the
96 * endpoint. The ioqueue instance is used to poll all RTP
97 * and RTCP sockets. If this argument is NULL, the
98 * endpoint will create an internal ioqueue instance.
99 * @param worker_cnt Specify the number of worker threads to be created
100 * to poll the ioqueue.
101 * @param p_endpt Pointer to receive the endpoint instance.
102 *
103 * @return PJ_SUCCESS on success.
104 */
pjmedia_endpt_create(pj_pool_factory * pf,pj_ioqueue_t * ioqueue,unsigned worker_cnt,pjmedia_endpt ** p_endpt)105 PJ_INLINE(pj_status_t) pjmedia_endpt_create(pj_pool_factory *pf,
106 pj_ioqueue_t *ioqueue,
107 unsigned worker_cnt,
108 pjmedia_endpt **p_endpt)
109 {
110 /* This function is inlined to avoid build problem due to circular
111 * dependency, i.e: this function prevents pjmedia's dependency on
112 * pjmedia-audiodev.
113 */
114
115 pj_status_t status;
116
117 /* Sound */
118 status = pjmedia_aud_subsys_init(pf);
119 if (status != PJ_SUCCESS)
120 return status;
121
122 status = pjmedia_endpt_create2(pf, ioqueue, worker_cnt, p_endpt);
123 if (status != PJ_SUCCESS) {
124 pjmedia_aud_subsys_shutdown();
125 }
126
127 return status;
128 }
129
130 /**
131 * Destroy media endpoint instance.
132 *
133 * @param endpt Media endpoint instance.
134 *
135 * @return PJ_SUCCESS on success.
136 */
137 PJ_DECL(pj_status_t) pjmedia_endpt_destroy2(pjmedia_endpt *endpt);
138
139 /**
140 * Destroy media endpoint instance and shutdown audio subsystem.
141 *
142 * @param endpt Media endpoint instance.
143 *
144 * @return PJ_SUCCESS on success.
145 */
pjmedia_endpt_destroy(pjmedia_endpt * endpt)146 PJ_INLINE(pj_status_t) pjmedia_endpt_destroy(pjmedia_endpt *endpt)
147 {
148 /* This function is inlined to avoid build problem due to circular
149 * dependency, i.e: this function prevents pjmedia's dependency on
150 * pjmedia-audiodev.
151 */
152 pj_status_t status = pjmedia_endpt_destroy2(endpt);
153 pjmedia_aud_subsys_shutdown();
154 return status;
155 }
156
157 /**
158 * Change the value of a flag.
159 *
160 * @param endpt Media endpoint.
161 * @param flag The flag.
162 * @param value Pointer to the value to be set.
163 *
164 * @reurn PJ_SUCCESS on success.
165 */
166 PJ_DECL(pj_status_t) pjmedia_endpt_set_flag(pjmedia_endpt *endpt,
167 pjmedia_endpt_flag flag,
168 const void *value);
169
170 /**
171 * Retrieve the value of a flag.
172 *
173 * @param endpt Media endpoint.
174 * @param flag The flag.
175 * @param value Pointer to store the result.
176 *
177 * @return PJ_SUCCESS on success.
178 */
179 PJ_DECL(pj_status_t) pjmedia_endpt_get_flag(pjmedia_endpt *endpt,
180 pjmedia_endpt_flag flag,
181 void *value);
182
183 /**
184 * Get the ioqueue instance of the media endpoint.
185 *
186 * @param endpt The media endpoint instance.
187 *
188 * @return The ioqueue instance of the media endpoint.
189 */
190 PJ_DECL(pj_ioqueue_t*) pjmedia_endpt_get_ioqueue(pjmedia_endpt *endpt);
191
192
193 /**
194 * Get the number of worker threads on the media endpoint
195 *
196 * @param endpt The media endpoint instance.
197 * @return The number of worker threads on the media endpoint
198 */
199 PJ_DECL(unsigned) pjmedia_endpt_get_thread_count(pjmedia_endpt *endpt);
200
201 /**
202 * Get a reference to one of the worker threads of the media endpoint
203 *
204 * @param endpt The media endpoint instance.
205 * @param index The index of the thread: 0<= index < thread_cnt
206 *
207 * @return pj_thread_t or NULL
208 */
209 PJ_DECL(pj_thread_t*) pjmedia_endpt_get_thread(pjmedia_endpt *endpt,
210 unsigned index);
211
212 /**
213 * Stop and destroy the worker threads of the media endpoint
214 *
215 * @param endpt The media endpoint instance.
216 *
217 * @return PJ_SUCCESS on success.
218 */
219 PJ_DECL(pj_status_t) pjmedia_endpt_stop_threads(pjmedia_endpt *endpt);
220
221
222 /**
223 * Request the media endpoint to create pool.
224 *
225 * @param endpt The media endpoint instance.
226 * @param name Name to be assigned to the pool.
227 * @param initial Initial pool size, in bytes.
228 * @param increment Increment size, in bytes.
229 *
230 * @return Memory pool.
231 */
232 PJ_DECL(pj_pool_t*) pjmedia_endpt_create_pool( pjmedia_endpt *endpt,
233 const char *name,
234 pj_size_t initial,
235 pj_size_t increment);
236
237 /**
238 * Get the codec manager instance of the media endpoint.
239 *
240 * @param endpt The media endpoint instance.
241 *
242 * @return The instance of codec manager belonging to
243 * this media endpoint.
244 */
245 PJ_DECL(pjmedia_codec_mgr*) pjmedia_endpt_get_codec_mgr(pjmedia_endpt *endpt);
246
247
248 /**
249 * Create a SDP session description that describes the endpoint
250 * capability.
251 *
252 * @param endpt The media endpoint.
253 * @param pool Pool to use to create the SDP descriptor.
254 * @param stream_cnt Number of elements in the sock_info array. This
255 * also denotes the maximum number of streams (i.e.
256 * the "m=" lines) that will be created in the SDP.
257 * By convention, if this value is greater than one,
258 * the first media will be audio and the remaining
259 * media is video.
260 * @param sock_info Array of socket transport information. One
261 * transport is needed for each media stream, and
262 * each transport consists of an RTP and RTCP socket
263 * pair.
264 * @param p_sdp Pointer to receive SDP session descriptor.
265 *
266 * @return PJ_SUCCESS on success.
267 */
268 PJ_DECL(pj_status_t) pjmedia_endpt_create_sdp( pjmedia_endpt *endpt,
269 pj_pool_t *pool,
270 unsigned stream_cnt,
271 const pjmedia_sock_info sock_info[],
272 pjmedia_sdp_session **p_sdp );
273
274 /**
275 * Create a "blank" SDP session description. The SDP will contain basic SDP
276 * fields such as origin, time, and name, but without any media lines.
277 *
278 * @param endpt The media endpoint.
279 * @param pool Pool to allocate memory from.
280 * @param sess_name Optional SDP session name, or NULL to use default
281 * value.
282 * @param origin Address to put in the origin field.
283 * @param p_sdp Pointer to receive the created SDP session.
284 *
285 * @return PJ_SUCCESS on success, or the appropriate error code.
286 */
287 PJ_DECL(pj_status_t) pjmedia_endpt_create_base_sdp(pjmedia_endpt *endpt,
288 pj_pool_t *pool,
289 const pj_str_t *sess_name,
290 const pj_sockaddr *origin,
291 pjmedia_sdp_session **p_sdp);
292
293 /**
294 * Create SDP media line for audio media.
295 *
296 * @param endpt The media endpoint.
297 * @param pool Pool to allocate memory from.
298 * @param si Socket information.
299 * @param options Option flags, must be zero for now.
300 * @param p_m Pointer to receive the created SDP media.
301 *
302 * @return PJ_SUCCESS on success, or the appropriate error code.
303 */
304 PJ_DECL(pj_status_t) pjmedia_endpt_create_audio_sdp(pjmedia_endpt *endpt,
305 pj_pool_t *pool,
306 const pjmedia_sock_info*si,
307 unsigned options,
308 pjmedia_sdp_media **p_m);
309
310 /**
311 * Create SDP media line for video media.
312 *
313 * @param endpt The media endpoint.
314 * @param pool Pool to allocate memory from.
315 * @param si Socket information.
316 * @param options Option flags, must be zero for now.
317 * @param p_m Pointer to receive the created SDP media.
318 *
319 * @return PJ_SUCCESS on success, or the appropriate error code.
320 */
321 PJ_DECL(pj_status_t) pjmedia_endpt_create_video_sdp(pjmedia_endpt *endpt,
322 pj_pool_t *pool,
323 const pjmedia_sock_info*si,
324 unsigned options,
325 pjmedia_sdp_media **p_m);
326
327 /**
328 * Dump media endpoint capabilities.
329 *
330 * @param endpt The media endpoint.
331 *
332 * @return PJ_SUCCESS on success.
333 */
334 PJ_DECL(pj_status_t) pjmedia_endpt_dump(pjmedia_endpt *endpt);
335
336
337 /**
338 * Register cleanup function to be called by media endpoint when
339 * #pjmedia_endpt_destroy() is called. Note that application should not
340 * use or access any endpoint resource (such as pool, ioqueue) from within
341 * the callback as such resource may have been released when the callback
342 * function is invoked.
343 *
344 * @param endpt The media endpoint.
345 * @param func The function to be registered.
346 *
347 * @return PJ_SUCCESS on success.
348 */
349 PJ_DECL(pj_status_t) pjmedia_endpt_atexit(pjmedia_endpt *endpt,
350 pjmedia_endpt_exit_callback func);
351
352
353
354 PJ_END_DECL
355
356
357 /**
358 * @}
359 */
360
361
362
363 #endif /* __PJMEDIA_MEDIAMGR_H__ */
364