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_TRANSPORT_H__
21 #define __PJMEDIA_TRANSPORT_H__
22
23
24 /**
25 * @file transport.h Media Transport Interface
26 * @brief Transport interface.
27 */
28
29 #include <pjmedia/types.h>
30 #include <pjmedia/errno.h>
31 #include <pj/string.h>
32
33 /**
34 * @defgroup PJMEDIA_TRANSPORT Media Transport
35 * @brief Transports.
36 * @{
37 * The media transport (#pjmedia_transport) is the object to send and
38 * receive media packets over the network. The media transport interface
39 * allows the library to be extended to support different types of
40 * transports to send and receive packets.
41 *
42 * The media transport is declared as #pjmedia_transport "class", which
43 * declares "interfaces" to use the class in #pjmedia_transport_op
44 * structure. For the user of the media transport (normally the user of
45 * media transport is media stream, see \ref PJMED_STRM), these transport
46 * "methods" are wrapped with API such as #pjmedia_transport_attach(),
47 * so it should not need to call the function pointer inside
48 * #pjmedia_transport_op directly.
49 *
50 * The connection between \ref PJMED_STRM and media transport is shown in
51 * the diagram below:
52
53 \image html media-transport.PNG
54
55
56 * \section PJMEDIA_TRANSPORT_H_USING Basic Media Transport Usage
57 *
58 * The media transport's life-cycle normally follows the following stages.
59 *
60 * \subsection PJMEDIA_TRANSPORT_H_CREATE Creating the Media Transport
61 *
62 * Application creates the media transport when it needs to establish
63 * media session to remote peer. The media transport is created using
64 * specific function to create that particular transport; for example,
65 * for UDP media transport, it is created with #pjmedia_transport_udp_create()
66 * or #pjmedia_transport_udp_create2() functions. Different media
67 * transports will provide different API to create those transports.
68 *
69 * Alternatively, application may create pool of media transports when
70 * it is first started up. Using this approach probably is better, since
71 * application has to specify the RTP port when sending the initial
72 * session establishment request (e.g. SIP INVITE request), thus if
73 * application only creates the media transport later when media is to be
74 * established (normally when 200/OK is received, or when 18x is received
75 * for early media), there is a possibility that the particular RTP
76 * port might have been occupied by other programs. Also it is more
77 * efficient since sockets don't need to be closed and re-opened between
78 * calls.
79 *
80 *
81 * \subsection PJMEDIA_TRANSPORT_H_ATTACH Attaching and Using the Media Transport.
82 *
83 * Application specifies the media transport instance when creating
84 * the media session (#pjmedia_session_create()). Alternatively, it
85 * may create the media stream directly with #pjmedia_stream_create()
86 * and specify the transport instance in the argument. (Note: media
87 * session is a high-level abstraction for media communications between
88 * two endpoints, and it may contain more than one media streams, for
89 * example, an audio stream and a video stream).
90 *
91 * When stream is created, it will "attach" itself to the media
92 * transport by calling #pjmedia_transport_attach(), which is a thin
93 * wrapper which calls "attach()" method of the media transport's
94 * "virtual function pointer" (#pjmedia_transport_op). Among other things,
95 * the stream specifies two callback functions to the transport: one
96 * callback function will be called by transport when it receives RTP
97 * packet, and another callback for incoming RTCP packet. The
98 * #pjmedia_transport_attach() function also establish the destination
99 * of the outgoing RTP and RTCP packets.
100 *
101 * When the stream needs to send outgoing RTP/RTCP packets, it will
102 * call #pjmedia_transport_send_rtp() and #pjmedia_transport_send_rtcp()
103 * of the media transport API, which is a thin wrapper to call send_rtp()
104 * and send_rtcp() methods in the media transport's "virtual function
105 * pointer" (#pjmedia_transport_op).
106 *
107 * When the stream is destroyed, it will "detach" itself from
108 * the media transport by calling #pjmedia_transport_detach(), which is
109 * a thin wrapper which calls "detach()" method of the media transport's
110 * "virtual function pointer" (#pjmedia_transport_op). After the transport
111 * is detached from its user (the stream), it will no longer report
112 * incoming RTP/RTCP packets to the stream, and it will refuse to send
113 * outgoing packets since the destination has been cleared.
114 *
115 *
116 * \subsection PJMEDIA_TRANSPORT_H_REUSE Reusing the Media Transport.
117 *
118 * After transport has been detached, application may re-attach the
119 * transport to another stream if it wants to. Detaching and re-attaching
120 * media transport may be preferable than closing and re-opening the
121 * transport, since it is more efficient (sockets don't need to be
122 * closed and re-opened). However it is up to the application to choose
123 * which method is most suitable for its uses.
124 *
125 *
126 * \subsection PJMEDIA_TRANSPORT_H_DESTROY Destroying the Media Transport.
127 *
128 * Finally if application no longer needs the media transport, it will
129 * call #pjmedia_transport_close() function, which is thin wrapper which
130 * calls "destroy()" method of the media transport's "virtual function
131 * pointer" (#pjmedia_transport_op). This function releases
132 * all resources used by the transport, such as sockets and memory.
133 *
134 *
135 * \section offer_answer Interaction with SDP Offer/Answer
136
137 For basic UDP transport, the \ref PJMEDIA_TRANSPORT_H_USING above is
138 sufficient to use the media transport. However, more complex media
139 transports such as \ref PJMEDIA_TRANSPORT_SRTP and \ref
140 PJMEDIA_TRANSPORT_ICE requires closer interactions with SDP offer and
141 answer negotiation.
142
143 The media transports can interact with the SDP offer/answer via
144 these APIs:
145 - #pjmedia_transport_media_create(), to initialize the media transport
146 for new media session,
147 - #pjmedia_transport_encode_sdp(), to encode SDP offer or answer,
148 - #pjmedia_transport_media_start(), to activate the settings that
149 have been negotiated by SDP offer answer, and
150 - #pjmedia_transport_media_stop(), to deinitialize the media transport
151 and reset the transport to its idle state.
152
153 The usage of these API in the context of SDP offer answer will be
154 described below.
155
156 \subsection media_create Initializing Transport for New Session
157
158 Application must call #pjmedia_transport_media_create() before using
159 the transport for a new session.
160
161 \subsection creat_oa Creating SDP Offer and Answer
162
163 The #pjmedia_transport_encode_sdp() is used to put additional information
164 from the transport to the local SDP, before the SDP is sent and negotiated
165 with remote SDP.
166
167 When creating an offer, call #pjmedia_transport_encode_sdp() with
168 local SDP (and NULL as \a rem_sdp). The media transport will add the
169 relevant attributes in the local SDP. Application then gives the local
170 SDP to the invite session to be sent to remote agent.
171
172 When creating an answer, also call #pjmedia_transport_encode_sdp(),
173 but this time specify both local and remote SDP to the function. The
174 media transport will once again modify the local SDP and add relevant
175 attributes to the local SDP, if the appropriate attributes related to
176 the transport functionality are present in remote offer. The remote
177 SDP does not contain the relevant attributes, then the specific transport
178 functionality will not be activated for the session.
179
180 The #pjmedia_transport_encode_sdp() should also be called when application
181 sends subsequent SDP offer or answer. The media transport will encode
182 the appropriate attributes based on the state of the session.
183
184 \subsection media_start Offer/Answer Completion
185
186 Once both local and remote SDP have been negotiated by the
187 \ref PJMEDIA_SDP_NEG (normally this is part of PJSIP invite session),
188 application should give both local and remote SDP to
189 #pjmedia_transport_media_start() so that the settings are activated
190 for the session. This function should be called for both initial and
191 subsequent SDP negotiation.
192
193 \subsection media_stop Stopping Transport
194
195 Once session is stop application must call #pjmedia_transport_media_stop()
196 to deactivate the transport feature. Application may reuse the transport
197 for subsequent media session by repeating the #pjmedia_transport_media_create(),
198 #pjmedia_transport_encode_sdp(), #pjmedia_transport_media_start(), and
199 #pjmedia_transport_media_stop() above.
200
201 * \section PJMEDIA_TRANSPORT_H_IMPL Implementing Media Transport
202 *
203 * To implement a new type of media transport, one needs to "subclass" the
204 * media transport "class" (#pjmedia_transport) by providing the "methods"
205 * in the media transport "interface" (#pjmedia_transport_op), and provides
206 * a function to create this new type of transport (similar to
207 * #pjmedia_transport_udp_create() function).
208 *
209 * The media transport is expected to run indepently, that is there should
210 * be no polling like function to poll the transport for incoming RTP/RTCP
211 * packets. This normally can be done by registering the media sockets to
212 * the media endpoint's IOQueue, which allows the transport to be notified
213 * when incoming packet has arrived.
214 *
215 * Alternatively, media transport may utilize thread(s) internally to wait
216 * for incoming packets. The thread then will call the appropriate RTP or
217 * RTCP callback provided by its user (stream) whenever packet is received.
218 * If the transport's user is a stream, then the callbacks provided by the
219 * stream will be thread-safe, so the transport may call these callbacks
220 * without having to serialize the access with some mutex protection. But
221 * the media transport may still have to protect its internal data with
222 * mutex protection, since it may be called by application's thread (for
223 * example, to send RTP/RTCP packets).
224 *
225 */
226
227
228 #include <pjmedia/sdp.h>
229
230 PJ_BEGIN_DECL
231
232
233 /**
234 * Forward declaration for media transport.
235 */
236 typedef struct pjmedia_transport pjmedia_transport;
237
238 /**
239 * Forward declaration for media transport info.
240 */
241 typedef struct pjmedia_transport_info pjmedia_transport_info;
242
243 /**
244 * Forward declaration for media transport attach param.
245 */
246 typedef struct pjmedia_transport_attach_param pjmedia_transport_attach_param;
247
248 /**
249 * This enumeration specifies the general behaviour of media processing
250 */
251 typedef enum pjmedia_tranport_media_option
252 {
253 /**
254 * When this flag is specified, the transport will not perform media
255 * transport validation, this is useful when transport is stacked with
256 * other transport, for example when transport UDP is stacked under
257 * transport SRTP, media transport validation only need to be done by
258 * transport SRTP.
259 */
260 PJMEDIA_TPMED_NO_TRANSPORT_CHECKING = 1,
261
262 /**
263 * When this flag is specified, the transport will allow multiplexing
264 * RTP and RTCP, i.e. if the remote agrees, RTCP will be sent using
265 * the same socket for RTP.
266 */
267 PJMEDIA_TPMED_RTCP_MUX = 2
268
269 } pjmedia_tranport_media_option;
270
271
272 /**
273 * Media socket info is used to describe the underlying sockets
274 * to be used as media transport.
275 */
276 typedef struct pjmedia_sock_info
277 {
278 /** The RTP socket handle */
279 pj_sock_t rtp_sock;
280
281 /** Address to be advertised as the local address for the RTP
282 * socket, which does not need to be equal as the bound
283 * address (for example, this address can be the address resolved
284 * with STUN).
285 */
286 pj_sockaddr rtp_addr_name;
287
288 /** The RTCP socket handle. */
289 pj_sock_t rtcp_sock;
290
291 /** Address to be advertised as the local address for the RTCP
292 * socket, which does not need to be equal as the bound
293 * address (for example, this address can be the address resolved
294 * with STUN).
295 */
296 pj_sockaddr rtcp_addr_name;
297
298 } pjmedia_sock_info;
299
300
301 /**
302 * This structure describes the operations for the stream transport.
303 */
304 struct pjmedia_transport_op
305 {
306 /**
307 * Get media socket info from the specified transport.
308 *
309 * Application should call #pjmedia_transport_get_info() instead
310 */
311 pj_status_t (*get_info)(pjmedia_transport *tp,
312 pjmedia_transport_info *info);
313
314 /**
315 * This function is called by the stream when the transport is about
316 * to be used by the stream for the first time, and it tells the transport
317 * about remote RTP address to send the packet and some callbacks to be
318 * called for incoming packets. This function exists for backwards
319 * compatibility. Transports should implement attach2 instead.
320 *
321 * Application should call #pjmedia_transport_attach() instead of
322 * calling this function directly.
323 */
324 pj_status_t (*attach)(pjmedia_transport *tp,
325 void *user_data,
326 const pj_sockaddr_t *rem_addr,
327 const pj_sockaddr_t *rem_rtcp,
328 unsigned addr_len,
329 void (*rtp_cb)(void *user_data,
330 void *pkt,
331 pj_ssize_t size),
332 void (*rtcp_cb)(void *user_data,
333 void *pkt,
334 pj_ssize_t size));
335
336 /**
337 * This function is called by the stream when the stream no longer
338 * needs the transport (normally when the stream is about to be closed).
339 * After the transport is detached, it will ignore incoming
340 * RTP/RTCP packets, and will refuse to send outgoing RTP/RTCP packets.
341 * Application may re-attach the media transport to another transport
342 * user (e.g. stream) after the transport has been detached.
343 *
344 * Application should call #pjmedia_transport_detach() instead of
345 * calling this function directly.
346 */
347 void (*detach)(pjmedia_transport *tp,
348 void *user_data);
349
350 /**
351 * This function is called by the stream to send RTP packet using the
352 * transport.
353 *
354 * Application should call #pjmedia_transport_send_rtp() instead of
355 * calling this function directly.
356 */
357 pj_status_t (*send_rtp)(pjmedia_transport *tp,
358 const void *pkt,
359 pj_size_t size);
360
361 /**
362 * This function is called by the stream to send RTCP packet using the
363 * transport.
364 *
365 * Application should call #pjmedia_transport_send_rtcp() instead of
366 * calling this function directly.
367 */
368 pj_status_t (*send_rtcp)(pjmedia_transport *tp,
369 const void *pkt,
370 pj_size_t size);
371
372 /**
373 * This function is called by the stream to send RTCP packet using the
374 * transport with destination address other than default specified in
375 * #pjmedia_transport_attach().
376 *
377 * Application should call #pjmedia_transport_send_rtcp2() instead of
378 * calling this function directly.
379 */
380 pj_status_t (*send_rtcp2)(pjmedia_transport *tp,
381 const pj_sockaddr_t *addr,
382 unsigned addr_len,
383 const void *pkt,
384 pj_size_t size);
385
386 /**
387 * Prepare the transport for a new media session.
388 *
389 * Application should call #pjmedia_transport_media_create() instead of
390 * calling this function directly.
391 */
392 pj_status_t (*media_create)(pjmedia_transport *tp,
393 pj_pool_t *sdp_pool,
394 unsigned options,
395 const pjmedia_sdp_session *remote_sdp,
396 unsigned media_index);
397
398 /**
399 * This function is called by application to generate the SDP parts
400 * related to transport type, e.g: ICE, SRTP.
401 *
402 * Application should call #pjmedia_transport_encode_sdp() instead of
403 * calling this function directly.
404 */
405 pj_status_t (*encode_sdp)(pjmedia_transport *tp,
406 pj_pool_t *sdp_pool,
407 pjmedia_sdp_session *sdp_local,
408 const pjmedia_sdp_session *rem_sdp,
409 unsigned media_index);
410
411 /**
412 * This function is called by application to start the transport
413 * based on local and remote SDP.
414 *
415 * Application should call #pjmedia_transport_media_start() instead of
416 * calling this function directly.
417 */
418 pj_status_t (*media_start) (pjmedia_transport *tp,
419 pj_pool_t *tmp_pool,
420 const pjmedia_sdp_session *sdp_local,
421 const pjmedia_sdp_session *sdp_remote,
422 unsigned media_index);
423
424 /**
425 * This function is called by application to stop the transport.
426 *
427 * Application should call #pjmedia_transport_media_stop() instead of
428 * calling this function directly.
429 */
430 pj_status_t (*media_stop) (pjmedia_transport *tp);
431
432 /**
433 * This function can be called to simulate packet lost.
434 *
435 * Application should call #pjmedia_transport_simulate_lost() instead of
436 * calling this function directly.
437 */
438 pj_status_t (*simulate_lost)(pjmedia_transport *tp,
439 pjmedia_dir dir,
440 unsigned pct_lost);
441
442 /**
443 * This function can be called to destroy this transport.
444 *
445 * Application should call #pjmedia_transport_close() instead of
446 * calling this function directly.
447 */
448 pj_status_t (*destroy)(pjmedia_transport *tp);
449
450 /**
451 * This function is called by the stream when the transport is about
452 * to be used by the stream for the first time, and it tells the transport
453 * about remote RTP address to send the packet and some callbacks to be
454 * called for incoming packets.
455 *
456 * Application should call #pjmedia_transport_attach2() instead of
457 * calling this function directly.
458 */
459 pj_status_t (*attach2)(pjmedia_transport *tp,
460 pjmedia_transport_attach_param *att_param);
461 };
462
463
464 /**
465 * @see pjmedia_transport_op.
466 */
467 typedef struct pjmedia_transport_op pjmedia_transport_op;
468
469
470 /**
471 * Media transport type.
472 */
473 typedef enum pjmedia_transport_type
474 {
475 /** Media transport using standard UDP */
476 PJMEDIA_TRANSPORT_TYPE_UDP,
477
478 /** Media transport using ICE */
479 PJMEDIA_TRANSPORT_TYPE_ICE,
480
481 /**
482 * Media transport SRTP, this transport is actually security adapter to be
483 * stacked with other transport to enable encryption on the underlying
484 * transport.
485 */
486 PJMEDIA_TRANSPORT_TYPE_SRTP,
487
488 /** Loopback media transport */
489 PJMEDIA_TRANSPORT_TYPE_LOOP,
490
491 /**
492 * Start of user defined transport.
493 */
494 PJMEDIA_TRANSPORT_TYPE_USER
495
496 } pjmedia_transport_type;
497
498
499 /**
500 * This structure declares media transport. A media transport is called
501 * by the stream to transmit a packet, and will notify stream when
502 * incoming packet is arrived.
503 */
504 struct pjmedia_transport
505 {
506 /** Transport name (for logging purpose). */
507 char name[PJ_MAX_OBJ_NAME];
508
509 /** Transport type. */
510 pjmedia_transport_type type;
511
512 /** Transport's "virtual" function table. */
513 pjmedia_transport_op *op;
514
515 /** Application/user data */
516 void *user_data;
517 };
518
519 /**
520 * This structure describes storage buffer of transport specific info.
521 * The actual transport specific info contents will be defined by transport
522 * implementation. Note that some transport implementations do not need to
523 * provide specific info, since the general socket info is enough.
524 */
525 typedef struct pjmedia_transport_specific_info
526 {
527 /**
528 * Specify media transport type.
529 */
530 pjmedia_transport_type type;
531
532 /**
533 * Specify storage buffer size of transport specific info.
534 */
535 int cbsize;
536
537 /**
538 * Storage buffer of transport specific info.
539 */
540 char buffer[PJMEDIA_TRANSPORT_SPECIFIC_INFO_MAXSIZE];
541
542 } pjmedia_transport_specific_info;
543
544
545 /**
546 * This structure describes transport informations, including general
547 * socket information and specific information of single transport or
548 * stacked transports (e.g: SRTP stacked on top of UDP)
549 */
550 struct pjmedia_transport_info
551 {
552 /**
553 * General socket info.
554 */
555 pjmedia_sock_info sock_info;
556
557 /**
558 * Remote address where RTP/RTCP originated from. In case this transport
559 * hasn't ever received packet, the address can be invalid (zero).
560 */
561 pj_sockaddr src_rtp_name;
562 pj_sockaddr src_rtcp_name;
563
564 /**
565 * Specifies number of transport specific info included.
566 */
567 unsigned specific_info_cnt;
568
569 /**
570 * Buffer storage of transport specific info.
571 */
572 pjmedia_transport_specific_info spc_info[PJMEDIA_TRANSPORT_SPECIFIC_INFO_MAXCNT];
573
574 };
575
576 /**
577 * This structure describes the data passed when calling #rtp_cb2().
578 */
579 typedef struct pjmedia_tp_cb_param
580 {
581 /**
582 * User data.
583 */
584 void *user_data;
585
586 /**
587 * Packet buffer.
588 */
589 void *pkt;
590
591 /**
592 * Packet size.
593 */
594 pj_ssize_t size;
595
596 /**
597 * Packet's source address.
598 */
599 pj_sockaddr *src_addr;
600
601 /**
602 * Should media transport switch remote address to \a rtp_src_addr?
603 * Media transport should initialize it to PJ_FALSE, and application
604 * can change the value as necessary.
605 */
606 pj_bool_t rem_switch;
607
608 } pjmedia_tp_cb_param;
609
610 /**
611 * This structure describes the data passed when calling
612 * #pjmedia_transport_attach2().
613 */
614 struct pjmedia_transport_attach_param
615 {
616 /**
617 * The media stream.
618 */
619 void *stream;
620
621 /**
622 * Indicate the stream type, either it's audio (PJMEDIA_TYPE_AUDIO)
623 * or video (PJMEDIA_TYPE_VIDEO).
624 */
625 pjmedia_type media_type;
626
627 /**
628 * Remote RTP address to send RTP packet to.
629 */
630 pj_sockaddr rem_addr;
631
632 /**
633 * Optional remote RTCP address. If the argument is NULL
634 * or if the address is zero, the RTCP address will be
635 * calculated from the RTP address (which is RTP port plus one).
636 */
637 pj_sockaddr rem_rtcp;
638
639 /**
640 * Length of the remote address.
641 */
642 unsigned addr_len;
643
644 /**
645 * Arbitrary user data to be set when the callbacks are called.
646 */
647 void *user_data;
648
649 /**
650 * Callback to be called when RTP packet is received on the transport.
651 */
652 void (*rtp_cb)(void *user_data, void *pkt, pj_ssize_t);
653
654 /**
655 * Callback to be called when RTCP packet is received on the transport.
656 */
657 void (*rtcp_cb)(void *user_data, void *pkt, pj_ssize_t);
658
659 /**
660 * Callback to be called when RTP packet is received on the transport.
661 */
662 void (*rtp_cb2)(pjmedia_tp_cb_param *param);
663
664 };
665
666 /**
667 * Initialize transport info.
668 *
669 * @param info Transport info to be initialized.
670 */
pjmedia_transport_info_init(pjmedia_transport_info * info)671 PJ_INLINE(void) pjmedia_transport_info_init(pjmedia_transport_info *info)
672 {
673 pj_bzero(info, sizeof(pjmedia_transport_info));
674 info->sock_info.rtp_sock = info->sock_info.rtcp_sock = PJ_INVALID_SOCKET;
675 }
676
677
678 /**
679 * Get media transport info from the specified transport and all underlying
680 * transports if any. The transport also contains information about socket info
681 * which describes the local address of the transport, and would be needed
682 * for example to fill in the "c=" and "m=" line of local SDP.
683 *
684 * @param tp The transport.
685 * @param info Media transport info to be initialized.
686 *
687 * @return PJ_SUCCESS on success.
688 */
pjmedia_transport_get_info(pjmedia_transport * tp,pjmedia_transport_info * info)689 PJ_INLINE(pj_status_t) pjmedia_transport_get_info(pjmedia_transport *tp,
690 pjmedia_transport_info *info)
691 {
692 if (tp && tp->op && tp->op->get_info)
693 return (*tp->op->get_info)(tp, info);
694
695 return PJ_ENOTSUP;
696 }
697
698
699 /**
700 * Utility API to get transport type specific info from the specified media
701 * transport info.
702 *
703 * @param info Media transport info.
704 * @param type Media transport type.
705 *
706 * @return Pointer to media transport specific info, or NULL if
707 * specific info for the transport type is not found.
708 */
pjmedia_transport_info_get_spc_info(pjmedia_transport_info * info,pjmedia_transport_type type)709 PJ_INLINE(void*) pjmedia_transport_info_get_spc_info(
710 pjmedia_transport_info *info,
711 pjmedia_transport_type type)
712 {
713 unsigned i;
714 for (i = 0; i < info->specific_info_cnt; ++i) {
715 if (info->spc_info[i].type == type)
716 return (void*)info->spc_info[i].buffer;
717 }
718 return NULL;
719 }
720
721
722 /**
723 * Attach callbacks to be called on receipt of incoming RTP/RTCP packets.
724 * This is just a simple wrapper which calls <tt>attach2()</tt> member of
725 * the transport if it is implemented, otherwise it calls <tt>attach()</tt>
726 * member of the transport.
727 *
728 * @param tp The media transport.
729 * @param att_param The transport attach param.
730 *
731 * @return PJ_SUCCESS on success, or the appropriate error code.
732 */
pjmedia_transport_attach2(pjmedia_transport * tp,pjmedia_transport_attach_param * att_param)733 PJ_INLINE(pj_status_t) pjmedia_transport_attach2(pjmedia_transport *tp,
734 pjmedia_transport_attach_param *att_param)
735 {
736 if (tp->op->attach2) {
737 return (*tp->op->attach2)(tp, att_param);
738 } else {
739 return (*tp->op->attach)(tp, att_param->user_data,
740 (pj_sockaddr_t*)&att_param->rem_addr,
741 (pj_sockaddr_t*)&att_param->rem_rtcp,
742 att_param->addr_len, att_param->rtp_cb,
743 att_param->rtcp_cb);
744 }
745 }
746
747
748 /**
749 * Attach callbacks to be called on receipt of incoming RTP/RTCP packets.
750 * This is just a simple wrapper which calls <tt>attach()</tt> member of
751 * the transport.
752 *
753 * @param tp The media transport.
754 * @param user_data Arbitrary user data to be set when the callbacks are
755 * called.
756 * @param rem_addr Remote RTP address to send RTP packet to.
757 * @param rem_rtcp Optional remote RTCP address. If the argument is NULL
758 * or if the address is zero, the RTCP address will be
759 * calculated from the RTP address (which is RTP port
760 * plus one).
761 * @param addr_len Length of the remote address.
762 * @param rtp_cb Callback to be called when RTP packet is received on
763 * the transport.
764 * @param rtcp_cb Callback to be called when RTCP packet is received on
765 * the transport.
766 *
767 * @return PJ_SUCCESS on success, or the appropriate error code.
768 */
pjmedia_transport_attach(pjmedia_transport * tp,void * user_data,const pj_sockaddr_t * rem_addr,const pj_sockaddr_t * rem_rtcp,unsigned addr_len,void (* rtp_cb)(void * user_data,void * pkt,pj_ssize_t),void (* rtcp_cb)(void * usr_data,void * pkt,pj_ssize_t))769 PJ_INLINE(pj_status_t) pjmedia_transport_attach(pjmedia_transport *tp,
770 void *user_data,
771 const pj_sockaddr_t *rem_addr,
772 const pj_sockaddr_t *rem_rtcp,
773 unsigned addr_len,
774 void (*rtp_cb)(void *user_data,
775 void *pkt,
776 pj_ssize_t),
777 void (*rtcp_cb)(void *usr_data,
778 void*pkt,
779 pj_ssize_t))
780 {
781 if (tp->op->attach2) {
782 pjmedia_transport_attach_param param;
783
784 pj_bzero(¶m, sizeof(param));
785 param.user_data = user_data;
786 pj_sockaddr_cp(¶m.rem_addr, rem_addr);
787 if (rem_rtcp && pj_sockaddr_has_addr(rem_rtcp)) {
788 pj_sockaddr_cp(¶m.rem_rtcp, rem_rtcp);
789 } else {
790 /* Copy RTCP address from the RTP address, with port + 1 */
791 pj_memcpy(¶m.rem_rtcp, rem_addr, addr_len);
792 pj_sockaddr_set_port(¶m.rem_rtcp,
793 pj_sockaddr_get_port(rem_addr) + 1);
794 }
795 param.addr_len = addr_len;
796 param.rtp_cb = rtp_cb;
797 param.rtcp_cb = rtcp_cb;
798
799 return (*tp->op->attach2)(tp, ¶m);
800 } else {
801 return (*tp->op->attach)(tp, user_data, rem_addr, rem_rtcp, addr_len,
802 rtp_cb, rtcp_cb);
803 }
804 }
805
806
807 /**
808 * Detach callbacks from the transport.
809 * This is just a simple wrapper which calls <tt>detach()</tt> member of
810 * the transport. After the transport is detached, it will ignore incoming
811 * RTP/RTCP packets, and will refuse to send outgoing RTP/RTCP packets.
812 * Application may re-attach the media transport to another transport user
813 * (e.g. stream) after the transport has been detached.
814 *
815 * @param tp The media transport.
816 * @param user_data User data which must match the previously set value
817 * on attachment.
818 */
pjmedia_transport_detach(pjmedia_transport * tp,void * user_data)819 PJ_INLINE(void) pjmedia_transport_detach(pjmedia_transport *tp,
820 void *user_data)
821 {
822 (*tp->op->detach)(tp, user_data);
823 }
824
825
826 /**
827 * Send RTP packet with the specified media transport. This is just a simple
828 * wrapper which calls <tt>send_rtp()</tt> member of the transport. The
829 * RTP packet will be delivered to the destination address specified in
830 * #pjmedia_transport_attach() function.
831 *
832 * @param tp The media transport.
833 * @param pkt The packet to send.
834 * @param size Size of the packet.
835 *
836 * @return PJ_SUCCESS on success, or the appropriate error code.
837 */
pjmedia_transport_send_rtp(pjmedia_transport * tp,const void * pkt,pj_size_t size)838 PJ_INLINE(pj_status_t) pjmedia_transport_send_rtp(pjmedia_transport *tp,
839 const void *pkt,
840 pj_size_t size)
841 {
842 return (*tp->op->send_rtp)(tp, pkt, size);
843 }
844
845
846 /**
847 * Send RTCP packet with the specified media transport. This is just a simple
848 * wrapper which calls <tt>send_rtcp()</tt> member of the transport. The
849 * RTCP packet will be delivered to the destination address specified in
850 * #pjmedia_transport_attach() function.
851 *
852 * @param tp The media transport.
853 * @param pkt The packet to send.
854 * @param size Size of the packet.
855 *
856 * @return PJ_SUCCESS on success, or the appropriate error code.
857 */
pjmedia_transport_send_rtcp(pjmedia_transport * tp,const void * pkt,pj_size_t size)858 PJ_INLINE(pj_status_t) pjmedia_transport_send_rtcp(pjmedia_transport *tp,
859 const void *pkt,
860 pj_size_t size)
861 {
862 return (*tp->op->send_rtcp)(tp, pkt, size);
863 }
864
865
866 /**
867 * Send RTCP packet with the specified media transport. This is just a simple
868 * wrapper which calls <tt>send_rtcp2()</tt> member of the transport. The
869 * RTCP packet will be delivered to the destination address specified in
870 * param addr, if addr is NULL, RTCP packet will be delivered to destination
871 * address specified in #pjmedia_transport_attach() function.
872 *
873 * @param tp The media transport.
874 * @param addr The destination address.
875 * @param addr_len Length of destination address.
876 * @param pkt The packet to send.
877 * @param size Size of the packet.
878 *
879 * @return PJ_SUCCESS on success, or the appropriate error code.
880 */
pjmedia_transport_send_rtcp2(pjmedia_transport * tp,const pj_sockaddr_t * addr,unsigned addr_len,const void * pkt,pj_size_t size)881 PJ_INLINE(pj_status_t) pjmedia_transport_send_rtcp2(pjmedia_transport *tp,
882 const pj_sockaddr_t *addr,
883 unsigned addr_len,
884 const void *pkt,
885 pj_size_t size)
886 {
887 return (*tp->op->send_rtcp2)(tp, addr, addr_len, pkt, size);
888 }
889
890
891 /**
892 * Prepare the media transport for a new media session, Application must
893 * call this function before starting a new media session using this
894 * transport.
895 *
896 * This is just a simple wrapper which calls <tt>media_create()</tt> member
897 * of the transport.
898 *
899 * @param tp The media transport.
900 * @param sdp_pool Pool object to allocate memory related to SDP
901 * messaging components.
902 * @param options Option flags, from #pjmedia_tranport_media_option
903 * @param rem_sdp Remote SDP if local SDP is an answer, otherwise
904 * specify NULL if SDP is an offer.
905 * @param media_index Media index in SDP.
906 *
907 * @return PJ_SUCCESS on success, or the appropriate error code.
908 */
pjmedia_transport_media_create(pjmedia_transport * tp,pj_pool_t * sdp_pool,unsigned options,const pjmedia_sdp_session * rem_sdp,unsigned media_index)909 PJ_INLINE(pj_status_t) pjmedia_transport_media_create(pjmedia_transport *tp,
910 pj_pool_t *sdp_pool,
911 unsigned options,
912 const pjmedia_sdp_session *rem_sdp,
913 unsigned media_index)
914 {
915 return (*tp->op->media_create)(tp, sdp_pool, options, rem_sdp,
916 media_index);
917 }
918
919
920 /**
921 * Put transport specific information into the SDP. This function can be
922 * called to put transport specific information in the initial or
923 * subsequent SDP offer or answer.
924 *
925 * This is just a simple wrapper which calls <tt>encode_sdp()</tt> member
926 * of the transport.
927 *
928 * @param tp The media transport.
929 * @param sdp_pool Pool object to allocate memory related to SDP
930 * messaging components.
931 * @param sdp The local SDP to be filled in information from the
932 * media transport.
933 * @param rem_sdp Remote SDP if local SDP is an answer, otherwise
934 * specify NULL if SDP is an offer.
935 * @param media_index Media index in SDP.
936 *
937 * @return PJ_SUCCESS on success, or the appropriate error code.
938 */
pjmedia_transport_encode_sdp(pjmedia_transport * tp,pj_pool_t * sdp_pool,pjmedia_sdp_session * sdp,const pjmedia_sdp_session * rem_sdp,unsigned media_index)939 PJ_INLINE(pj_status_t) pjmedia_transport_encode_sdp(pjmedia_transport *tp,
940 pj_pool_t *sdp_pool,
941 pjmedia_sdp_session *sdp,
942 const pjmedia_sdp_session *rem_sdp,
943 unsigned media_index)
944 {
945 return (*tp->op->encode_sdp)(tp, sdp_pool, sdp, rem_sdp, media_index);
946 }
947
948
949 /**
950 * Start the transport session with the settings in both local and remote
951 * SDP. The actual work that is done by this function depends on the
952 * underlying transport type. For SRTP, this will activate the encryption
953 * and decryption based on the keys found the SDPs. For ICE, this will
954 * start ICE negotiation according to the information found in the SDPs.
955 *
956 * This is just a simple wrapper which calls <tt>media_start()</tt> member
957 * of the transport.
958 *
959 * @param tp The media transport.
960 * @param tmp_pool The memory pool for allocating temporary objects.
961 * @param sdp_local Local SDP.
962 * @param sdp_remote Remote SDP.
963 * @param media_index Media index in the SDP.
964 *
965 * @return PJ_SUCCESS on success, or the appropriate error code.
966 */
pjmedia_transport_media_start(pjmedia_transport * tp,pj_pool_t * tmp_pool,const pjmedia_sdp_session * sdp_local,const pjmedia_sdp_session * sdp_remote,unsigned media_index)967 PJ_INLINE(pj_status_t) pjmedia_transport_media_start(pjmedia_transport *tp,
968 pj_pool_t *tmp_pool,
969 const pjmedia_sdp_session *sdp_local,
970 const pjmedia_sdp_session *sdp_remote,
971 unsigned media_index)
972 {
973 return (*tp->op->media_start)(tp, tmp_pool, sdp_local, sdp_remote,
974 media_index);
975 }
976
977
978 /**
979 * This API should be called when the session is stopped, to allow the media
980 * transport to release its resources used for the session.
981 *
982 * This is just a simple wrapper which calls <tt>media_stop()</tt> member
983 * of the transport.
984 *
985 * @param tp The media transport.
986 *
987 * @return PJ_SUCCESS on success, or the appropriate error code.
988 */
pjmedia_transport_media_stop(pjmedia_transport * tp)989 PJ_INLINE(pj_status_t) pjmedia_transport_media_stop(pjmedia_transport *tp)
990 {
991 return (*tp->op->media_stop)(tp);
992 }
993
994 /**
995 * Close media transport. This is just a simple wrapper which calls
996 * <tt>destroy()</tt> member of the transport. This function will free
997 * all resources created by this transport (such as sockets, memory, etc.).
998 *
999 * @param tp The media transport.
1000 *
1001 * @return PJ_SUCCESS on success, or the appropriate error code.
1002 */
pjmedia_transport_close(pjmedia_transport * tp)1003 PJ_INLINE(pj_status_t) pjmedia_transport_close(pjmedia_transport *tp)
1004 {
1005 if (tp->op->destroy)
1006 return (*tp->op->destroy)(tp);
1007 else
1008 return PJ_SUCCESS;
1009 }
1010
1011 /**
1012 * Simulate packet lost in the specified direction (for testing purposes).
1013 * When enabled, the transport will randomly drop packets to the specified
1014 * direction.
1015 *
1016 * @param tp The media transport.
1017 * @param dir Media direction to which packets will be randomly dropped.
1018 * @param pct_lost Percent lost (0-100). Set to zero to disable packet
1019 * lost simulation.
1020 *
1021 * @return PJ_SUCCESS on success.
1022 */
pjmedia_transport_simulate_lost(pjmedia_transport * tp,pjmedia_dir dir,unsigned pct_lost)1023 PJ_INLINE(pj_status_t) pjmedia_transport_simulate_lost(pjmedia_transport *tp,
1024 pjmedia_dir dir,
1025 unsigned pct_lost)
1026 {
1027 return (*tp->op->simulate_lost)(tp, dir, pct_lost);
1028 }
1029
1030
1031 PJ_END_DECL
1032
1033 /**
1034 * @}
1035 */
1036
1037
1038 #endif /* __PJMEDIA_TRANSPORT_H__ */
1039
1040