← Back to branch summary

~ubuntu-branches/ubuntu/trusty/sflphone/trusty

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/transport.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (4.3.4 sid)
  • Revision ID: package-import@ubuntu.com-20140128182336-jrsv0k9u6cawc068
Tags: 1.3.0-1
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/transport.h
1
 
/* $Id: transport.h 3664 2011-07-19 03:42:28Z nanang $ */
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
 
 * This enumeration specifies the general behaviour of media processing
245
 
 */
246
 
typedef enum pjmedia_tranport_media_option
247
 
{
248
 
    /**
249
 
     * When this flag is specified, the transport will not perform media
250
 
     * transport validation, this is useful when transport is stacked with
251
 
     * other transport, for example when transport UDP is stacked under
252
 
     * transport SRTP, media transport validation only need to be done by
253
 
     * transport SRTP.
254
 
     */
255
 
    PJMEDIA_TPMED_NO_TRANSPORT_CHECKING = 1
256
 
 
257
 
} pjmedia_tranport_media_option;
258
 
 
259
 
 
260
 
/**
261
 
 * Media socket info is used to describe the underlying sockets
262
 
 * to be used as media transport.
263
 
 */
264
 
typedef struct pjmedia_sock_info
265
 
{
266
 
    /** The RTP socket handle */
267
 
    pj_sock_t       rtp_sock;
268
 
 
269
 
    /** Address to be advertised as the local address for the RTP
270
 
     *  socket, which does not need to be equal as the bound
271
 
     *  address (for example, this address can be the address resolved
272
 
     *  with STUN).
273
 
     */
274
 
    pj_sockaddr     rtp_addr_name;
275
 
 
276
 
    /** The RTCP socket handle. */
277
 
    pj_sock_t       rtcp_sock;
278
 
 
279
 
    /** Address to be advertised as the local address for the RTCP
280
 
     *  socket, which does not need to be equal as the bound
281
 
     *  address (for example, this address can be the address resolved
282
 
     *  with STUN).
283
 
     */
284
 
    pj_sockaddr     rtcp_addr_name;
285
 
 
286
 
} pjmedia_sock_info;
287
 
 
288
 
 
289
 
/**
290
 
 * This structure describes the operations for the stream transport.
291
 
 */
292
 
struct pjmedia_transport_op
293
 
{
294
 
    /**
295
 
     * Get media socket info from the specified transport.
296
 
     *
297
 
     * Application should call #pjmedia_transport_get_info() instead
298
 
     */
299
 
    pj_status_t (*get_info)(pjmedia_transport *tp,
300
 
                            pjmedia_transport_info *info);
301
 
 
302
 
    /**
303
 
     * This function is called by the stream when the transport is about
304
 
     * to be used by the stream for the first time, and it tells the transport
305
 
     * about remote RTP address to send the packet and some callbacks to be
306
 
     * called for incoming packets.
307
 
     *
308
 
     * Application should call #pjmedia_transport_attach() instead of
309
 
     * calling this function directly.
310
 
     */
311
 
    pj_status_t (*attach)(pjmedia_transport *tp,
312
 
                          void *user_data,
313
 
                          const pj_sockaddr_t *rem_addr,
314
 
                          const pj_sockaddr_t *rem_rtcp,
315
 
                          unsigned addr_len,
316
 
                          void (*rtp_cb)(void *user_data,
317
 
                                         void *pkt,
318
 
                                         pj_ssize_t size),
319
 
                          void (*rtcp_cb)(void *user_data,
320
 
                                          void *pkt,
321
 
                                          pj_ssize_t size));
322
 
 
323
 
    /**
324
 
     * This function is called by the stream when the stream no longer
325
 
     * needs the transport (normally when the stream is about to be closed).
326
 
     * After the transport is detached, it will ignore incoming
327
 
     * RTP/RTCP packets, and will refuse to send outgoing RTP/RTCP packets.
328
 
     * Application may re-attach the media transport to another transport
329
 
     * user (e.g. stream) after the transport has been detached.
330
 
     *
331
 
     * Application should call #pjmedia_transport_detach() instead of
332
 
     * calling this function directly.
333
 
     */
334
 
    void (*detach)(pjmedia_transport *tp,
335
 
                   void *user_data);
336
 
 
337
 
    /**
338
 
     * This function is called by the stream to send RTP packet using the
339
 
     * transport.
340
 
     *
341
 
     * Application should call #pjmedia_transport_send_rtp() instead of
342
 
     * calling this function directly.
343
 
     */
344
 
    pj_status_t (*send_rtp)(pjmedia_transport *tp,
345
 
                            const void *pkt,
346
 
                            pj_size_t size);
347
 
 
348
 
    /**
349
 
     * This function is called by the stream to send RTCP packet using the
350
 
     * transport.
351
 
     *
352
 
     * Application should call #pjmedia_transport_send_rtcp() instead of
353
 
     * calling this function directly.
354
 
     */
355
 
    pj_status_t (*send_rtcp)(pjmedia_transport *tp,
356
 
                             const void *pkt,
357
 
                             pj_size_t size);
358
 
 
359
 
    /**
360
 
     * This function is called by the stream to send RTCP packet using the
361
 
     * transport with destination address other than default specified in
362
 
     * #pjmedia_transport_attach().
363
 
     *
364
 
     * Application should call #pjmedia_transport_send_rtcp2() instead of
365
 
     * calling this function directly.
366
 
     */
367
 
    pj_status_t (*send_rtcp2)(pjmedia_transport *tp,
368
 
                              const pj_sockaddr_t *addr,
369
 
                              unsigned addr_len,
370
 
                              const void *pkt,
371
 
                              pj_size_t size);
372
 
 
373
 
    /**
374
 
     * Prepare the transport for a new media session.
375
 
     *
376
 
     * Application should call #pjmedia_transport_media_create() instead of
377
 
     * calling this function directly.
378
 
     */
379
 
    pj_status_t (*media_create)(pjmedia_transport *tp,
380
 
                                pj_pool_t *sdp_pool,
381
 
                                unsigned options,
382
 
                                const pjmedia_sdp_session *remote_sdp,
383
 
                                unsigned media_index);
384
 
 
385
 
    /**
386
 
     * This function is called by application to generate the SDP parts
387
 
     * related to transport type, e.g: ICE, SRTP.
388
 
     *
389
 
     * Application should call #pjmedia_transport_encode_sdp() instead of
390
 
     * calling this function directly.
391
 
     */
392
 
    pj_status_t (*encode_sdp)(pjmedia_transport *tp,
393
 
                              pj_pool_t *sdp_pool,
394
 
                              pjmedia_sdp_session *sdp_local,
395
 
                              const pjmedia_sdp_session *rem_sdp,
396
 
                              unsigned media_index);
397
 
 
398
 
    /**
399
 
     * This function is called by application to start the transport
400
 
     * based on local and remote SDP.
401
 
     *
402
 
     * Application should call #pjmedia_transport_media_start() instead of
403
 
     * calling this function directly.
404
 
     */
405
 
    pj_status_t (*media_start) (pjmedia_transport *tp,
406
 
                                pj_pool_t *tmp_pool,
407
 
                                const pjmedia_sdp_session *sdp_local,
408
 
                                const pjmedia_sdp_session *sdp_remote,
409
 
                                unsigned media_index);
410
 
 
411
 
    /**
412
 
     * This function is called by application to stop the transport.
413
 
     *
414
 
     * Application should call #pjmedia_transport_media_stop() instead of
415
 
     * calling this function directly.
416
 
     */
417
 
    pj_status_t (*media_stop)  (pjmedia_transport *tp);
418
 
 
419
 
    /**
420
 
     * This function can be called to simulate packet lost.
421
 
     *
422
 
     * Application should call #pjmedia_transport_simulate_lost() instead of
423
 
     * calling this function directly.
424
 
     */
425
 
    pj_status_t (*simulate_lost)(pjmedia_transport *tp,
426
 
                                 pjmedia_dir dir,
427
 
                                 unsigned pct_lost);
428
 
 
429
 
    /**
430
 
     * This function can be called to destroy this transport.
431
 
     *
432
 
     * Application should call #pjmedia_transport_close() instead of
433
 
     * calling this function directly.
434
 
     */
435
 
    pj_status_t (*destroy)(pjmedia_transport *tp);
436
 
};
437
 
 
438
 
 
439
 
/**
440
 
 * @see pjmedia_transport_op.
441
 
 */
442
 
typedef struct pjmedia_transport_op pjmedia_transport_op;
443
 
 
444
 
 
445
 
/**
446
 
 * Media transport type.
447
 
 */
448
 
typedef enum pjmedia_transport_type
449
 
{
450
 
    /** Media transport using standard UDP */
451
 
    PJMEDIA_TRANSPORT_TYPE_UDP,
452
 
 
453
 
    /** Media transport using ICE */
454
 
    PJMEDIA_TRANSPORT_TYPE_ICE,
455
 
 
456
 
    /**
457
 
     * Media transport SRTP, this transport is actually security adapter to be
458
 
     * stacked with other transport to enable encryption on the underlying
459
 
     * transport.
460
 
     */
461
 
    PJMEDIA_TRANSPORT_TYPE_SRTP,
462
 
 
463
 
    /**
464
 
     * Start of user defined transport.
465
 
     */
466
 
    PJMEDIA_TRANSPORT_TYPE_USER
467
 
 
468
 
} pjmedia_transport_type;
469
 
 
470
 
 
471
 
/**
472
 
 * This structure declares media transport. A media transport is called
473
 
 * by the stream to transmit a packet, and will notify stream when
474
 
 * incoming packet is arrived.
475
 
 */
476
 
struct pjmedia_transport
477
 
{
478
 
    /** Transport name (for logging purpose). */
479
 
    char                     name[PJ_MAX_OBJ_NAME];
480
 
 
481
 
    /** Transport type. */
482
 
    pjmedia_transport_type   type;
483
 
 
484
 
    /** Transport's "virtual" function table. */
485
 
    pjmedia_transport_op    *op;
486
 
 
487
 
    /** Application/user data */
488
 
    void                    *user_data;
489
 
};
490
 
 
491
 
/**
492
 
 * This structure describes storage buffer of transport specific info.
493
 
 * The actual transport specific info contents will be defined by transport
494
 
 * implementation. Note that some transport implementations do not need to
495
 
 * provide specific info, since the general socket info is enough.
496
 
 */
497
 
typedef struct pjmedia_transport_specific_info
498
 
{
499
 
    /**
500
 
     * Specify media transport type.
501
 
     */
502
 
    pjmedia_transport_type   type;
503
 
 
504
 
    /**
505
 
     * Specify storage buffer size of transport specific info.
506
 
     */
507
 
    int                      cbsize;
508
 
 
509
 
    /**
510
 
     * Storage buffer of transport specific info.
511
 
     */
512
 
    char                     buffer[PJMEDIA_TRANSPORT_SPECIFIC_INFO_MAXSIZE];
513
 
 
514
 
} pjmedia_transport_specific_info;
515
 
 
516
 
 
517
 
/**
518
 
 * This structure describes transport informations, including general
519
 
 * socket information and specific information of single transport or
520
 
 * stacked transports (e.g: SRTP stacked on top of UDP)
521
 
 */
522
 
struct pjmedia_transport_info
523
 
{
524
 
    /**
525
 
     * General socket info.
526
 
     */
527
 
    pjmedia_sock_info sock_info;
528
 
 
529
 
    /**
530
 
     * Remote address where RTP/RTCP originated from. In case this transport
531
 
     * hasn't ever received packet, the
532
 
     */
533
 
    pj_sockaddr     src_rtp_name;
534
 
    pj_sockaddr     src_rtcp_name;
535
 
 
536
 
    /**
537
 
     * Specifies number of transport specific info included.
538
 
     */
539
 
    unsigned specific_info_cnt;
540
 
 
541
 
    /**
542
 
     * Buffer storage of transport specific info.
543
 
     */
544
 
    pjmedia_transport_specific_info spc_info[PJMEDIA_TRANSPORT_SPECIFIC_INFO_MAXCNT];
545
 
 
546
 
};
547
 
 
548
 
 
549
 
/**
550
 
 * Initialize transport info.
551
 
 *
552
 
 * @param info      Transport info to be initialized.
553
 
 */
554
 
PJ_INLINE(void) pjmedia_transport_info_init(pjmedia_transport_info *info)
555
 
{
556
 
    pj_bzero(&info->sock_info, sizeof(pjmedia_sock_info));
557
 
    info->sock_info.rtp_sock = info->sock_info.rtcp_sock = PJ_INVALID_SOCKET;
558
 
    info->specific_info_cnt = 0;
559
 
}
560
 
 
561
 
 
562
 
/**
563
 
 * Get media transport info from the specified transport and all underlying
564
 
 * transports if any. The transport also contains information about socket info
565
 
 * which describes the local address of the transport, and would be needed
566
 
 * for example to fill in the "c=" and "m=" line of local SDP.
567
 
 *
568
 
 * @param tp        The transport.
569
 
 * @param info      Media socket info to be initialized.
570
 
 *
571
 
 * @return          PJ_SUCCESS on success.
572
 
 */
573
 
PJ_INLINE(pj_status_t) pjmedia_transport_get_info(pjmedia_transport *tp,
574
 
                                                  pjmedia_transport_info *info)
575
 
{
576
 
    if (tp && tp->op && tp->op->get_info)
577
 
        return (*tp->op->get_info)(tp, info);
578
 
 
579
 
    return PJ_ENOTSUP;
580
 
}
581
 
 
582
 
 
583
 
/**
584
 
 * Attach callbacks to be called on receipt of incoming RTP/RTCP packets.
585
 
 * This is just a simple wrapper which calls <tt>attach()</tt> member of
586
 
 * the transport.
587
 
 *
588
 
 * @param tp        The media transport.
589
 
 * @param user_data Arbitrary user data to be set when the callbacks are
590
 
 *                  called.
591
 
 * @param rem_addr  Remote RTP address to send RTP packet to.
592
 
 * @param rem_rtcp  Optional remote RTCP address. If the argument is NULL
593
 
 *                  or if the address is zero, the RTCP address will be
594
 
 *                  calculated from the RTP address (which is RTP port
595
 
 *                  plus one).
596
 
 * @param addr_len  Length of the remote address.
597
 
 * @param rtp_cb    Callback to be called when RTP packet is received on
598
 
 *                  the transport.
599
 
 * @param rtcp_cb   Callback to be called when RTCP packet is received on
600
 
 *                  the transport.
601
 
 *
602
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
603
 
 */
604
 
PJ_INLINE(pj_status_t) pjmedia_transport_attach(pjmedia_transport *tp,
605
 
                                                void *user_data,
606
 
                                                const pj_sockaddr_t *rem_addr,
607
 
                                                const pj_sockaddr_t *rem_rtcp,
608
 
                                                unsigned addr_len,
609
 
                                                void (*rtp_cb)(void *user_data,
610
 
                                                               void *pkt,
611
 
                                                               pj_ssize_t),
612
 
                                                void (*rtcp_cb)(void *usr_data,
613
 
                                                                void*pkt,
614
 
                                                                pj_ssize_t))
615
 
{
616
 
    return tp->op->attach(tp, user_data, rem_addr, rem_rtcp, addr_len,
617
 
                          rtp_cb, rtcp_cb);
618
 
}
619
 
 
620
 
 
621
 
/**
622
 
 * Detach callbacks from the transport.
623
 
 * This is just a simple wrapper which calls <tt>detach()</tt> member of
624
 
 * the transport. After the transport is detached, it will ignore incoming
625
 
 * RTP/RTCP packets, and will refuse to send outgoing RTP/RTCP packets.
626
 
 * Application may re-attach the media transport to another transport user
627
 
 * (e.g. stream) after the transport has been detached.
628
 
 *
629
 
 * @param tp        The media transport.
630
 
 * @param user_data User data which must match the previously set value
631
 
 *                  on attachment.
632
 
 */
633
 
PJ_INLINE(void) pjmedia_transport_detach(pjmedia_transport *tp,
634
 
                                         void *user_data)
635
 
{
636
 
    tp->op->detach(tp, user_data);
637
 
}
638
 
 
639
 
 
640
 
/**
641
 
 * Send RTP packet with the specified media transport. This is just a simple
642
 
 * wrapper which calls <tt>send_rtp()</tt> member of the transport. The
643
 
 * RTP packet will be delivered to the destination address specified in
644
 
 * #pjmedia_transport_attach() function.
645
 
 *
646
 
 * @param tp        The media transport.
647
 
 * @param pkt       The packet to send.
648
 
 * @param size      Size of the packet.
649
 
 *
650
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
651
 
 */
652
 
PJ_INLINE(pj_status_t) pjmedia_transport_send_rtp(pjmedia_transport *tp,
653
 
                                                  const void *pkt,
654
 
                                                  pj_size_t size)
655
 
{
656
 
    return (*tp->op->send_rtp)(tp, pkt, size);
657
 
}
658
 
 
659
 
 
660
 
/**
661
 
 * Send RTCP packet with the specified media transport. This is just a simple
662
 
 * wrapper which calls <tt>send_rtcp()</tt> member of the transport. The
663
 
 * RTCP packet will be delivered to the destination address specified in
664
 
 * #pjmedia_transport_attach() function.
665
 
 *
666
 
 * @param tp        The media transport.
667
 
 * @param pkt       The packet to send.
668
 
 * @param size      Size of the packet.
669
 
 *
670
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
671
 
 */
672
 
PJ_INLINE(pj_status_t) pjmedia_transport_send_rtcp(pjmedia_transport *tp,
673
 
                                                  const void *pkt,
674
 
                                                  pj_size_t size)
675
 
{
676
 
    return (*tp->op->send_rtcp)(tp, pkt, size);
677
 
}
678
 
 
679
 
 
680
 
/**
681
 
 * Send RTCP packet with the specified media transport. This is just a simple
682
 
 * wrapper which calls <tt>send_rtcp2()</tt> member of the transport. The
683
 
 * RTCP packet will be delivered to the destination address specified in
684
 
 * param addr, if addr is NULL, RTCP packet will be delivered to destination
685
 
 * address specified in #pjmedia_transport_attach() function.
686
 
 *
687
 
 * @param tp        The media transport.
688
 
 * @param addr      The destination address.
689
 
 * @param addr_len  Length of destination address.
690
 
 * @param pkt       The packet to send.
691
 
 * @param size      Size of the packet.
692
 
 *
693
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
694
 
 */
695
 
PJ_INLINE(pj_status_t) pjmedia_transport_send_rtcp2(pjmedia_transport *tp,
696
 
                                                    const pj_sockaddr_t *addr,
697
 
                                                    unsigned addr_len,
698
 
                                                    const void *pkt,
699
 
                                                    pj_size_t size)
700
 
{
701
 
    return (*tp->op->send_rtcp2)(tp, addr, addr_len, pkt, size);
702
 
}
703
 
 
704
 
 
705
 
/**
706
 
 * Prepare the media transport for a new media session, Application must
707
 
 * call this function before starting a new media session using this
708
 
 * transport.
709
 
 *
710
 
 * This is just a simple wrapper which calls <tt>media_create()</tt> member
711
 
 * of the transport.
712
 
 *
713
 
 * @param tp            The media transport.
714
 
 * @param sdp_pool      Pool object to allocate memory related to SDP
715
 
 *                      messaging components.
716
 
 * @param options       Option flags, from #pjmedia_tranport_media_option
717
 
 * @param rem_sdp       Remote SDP if local SDP is an answer, otherwise
718
 
 *                      specify NULL if SDP is an offer.
719
 
 * @param media_index   Media index in SDP.
720
 
 *
721
 
 * @return              PJ_SUCCESS on success, or the appropriate error code.
722
 
 */
723
 
PJ_INLINE(pj_status_t) pjmedia_transport_media_create(pjmedia_transport *tp,
724
 
                                    pj_pool_t *sdp_pool,
725
 
                                    unsigned options,
726
 
                                    const pjmedia_sdp_session *rem_sdp,
727
 
                                    unsigned media_index)
728
 
{
729
 
    return (*tp->op->media_create)(tp, sdp_pool, options, rem_sdp,
730
 
                                   media_index);
731
 
}
732
 
 
733
 
 
734
 
/**
735
 
 * Put transport specific information into the SDP. This function can be
736
 
 * called to put transport specific information in the initial or
737
 
 * subsequent SDP offer or answer.
738
 
 *
739
 
 * This is just a simple wrapper which calls <tt>encode_sdp()</tt> member
740
 
 * of the transport.
741
 
 *
742
 
 * @param tp            The media transport.
743
 
 * @param sdp_pool      Pool object to allocate memory related to SDP
744
 
 *                      messaging components.
745
 
 * @param sdp           The local SDP to be filled in information from the
746
 
 *                      media transport.
747
 
 * @param rem_sdp       Remote SDP if local SDP is an answer, otherwise
748
 
 *                      specify NULL if SDP is an offer.
749
 
 * @param media_index   Media index in SDP.
750
 
 *
751
 
 * @return              PJ_SUCCESS on success, or the appropriate error code.
752
 
 */
753
 
PJ_INLINE(pj_status_t) pjmedia_transport_encode_sdp(pjmedia_transport *tp,
754
 
                                            pj_pool_t *sdp_pool,
755
 
                                            pjmedia_sdp_session *sdp,
756
 
                                            const pjmedia_sdp_session *rem_sdp,
757
 
                                            unsigned media_index)
758
 
{
759
 
    return (*tp->op->encode_sdp)(tp, sdp_pool, sdp, rem_sdp, media_index);
760
 
}
761
 
 
762
 
 
763
 
/**
764
 
 * Start the transport session with the settings in both local and remote
765
 
 * SDP. The actual work that is done by this function depends on the
766
 
 * underlying transport type. For SRTP, this will activate the encryption
767
 
 * and decryption based on the keys found the SDPs. For ICE, this will
768
 
 * start ICE negotiation according to the information found in the SDPs.
769
 
 *
770
 
 * This is just a simple wrapper which calls <tt>media_start()</tt> member
771
 
 * of the transport.
772
 
 *
773
 
 * @param tp            The media transport.
774
 
 * @param tmp_pool      The memory pool for allocating temporary objects.
775
 
 * @param sdp_local     Local SDP.
776
 
 * @param sdp_remote    Remote SDP.
777
 
 * @param media_index   Media index in the SDP.
778
 
 *
779
 
 * @return              PJ_SUCCESS on success, or the appropriate error code.
780
 
 */
781
 
PJ_INLINE(pj_status_t) pjmedia_transport_media_start(pjmedia_transport *tp,
782
 
                                    pj_pool_t *tmp_pool,
783
 
                                    const pjmedia_sdp_session *sdp_local,
784
 
                                    const pjmedia_sdp_session *sdp_remote,
785
 
                                    unsigned media_index)
786
 
{
787
 
    return (*tp->op->media_start)(tp, tmp_pool, sdp_local, sdp_remote,
788
 
                                  media_index);
789
 
}
790
 
 
791
 
 
792
 
/**
793
 
 * This API should be called when the session is stopped, to allow the media
794
 
 * transport to release its resources used for the session.
795
 
 *
796
 
 * This is just a simple wrapper which calls <tt>media_stop()</tt> member
797
 
 * of the transport.
798
 
 *
799
 
 * @param tp            The media transport.
800
 
 *
801
 
 * @return              PJ_SUCCESS on success, or the appropriate error code.
802
 
 */
803
 
PJ_INLINE(pj_status_t) pjmedia_transport_media_stop(pjmedia_transport *tp)
804
 
{
805
 
    return (*tp->op->media_stop)(tp);
806
 
}
807
 
 
808
 
/**
809
 
 * Close media transport. This is just a simple wrapper which calls
810
 
 * <tt>destroy()</tt> member of the transport. This function will free
811
 
 * all resources created by this transport (such as sockets, memory, etc.).
812
 
 *
813
 
 * @param tp        The media transport.
814
 
 *
815
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
816
 
 */
817
 
PJ_INLINE(pj_status_t) pjmedia_transport_close(pjmedia_transport *tp)
818
 
{
819
 
    if (tp->op->destroy)
820
 
        return (*tp->op->destroy)(tp);
821
 
    else
822
 
        return PJ_SUCCESS;
823
 
}
824
 
 
825
 
/**
826
 
 * Simulate packet lost in the specified direction (for testing purposes).
827
 
 * When enabled, the transport will randomly drop packets to the specified
828
 
 * direction.
829
 
 *
830
 
 * @param tp        The media transport.
831
 
 * @param dir       Media direction to which packets will be randomly dropped.
832
 
 * @param pct_lost  Percent lost (0-100). Set to zero to disable packet
833
 
 *                  lost simulation.
834
 
 *
835
 
 * @return          PJ_SUCCESS on success.
836
 
 */
837
 
PJ_INLINE(pj_status_t) pjmedia_transport_simulate_lost(pjmedia_transport *tp,
838
 
                                                       pjmedia_dir dir,
839
 
                                                       unsigned pct_lost)
840
 
{
841
 
    return (*tp->op->simulate_lost)(tp, dir, pct_lost);
842
 
}
843
 
 
844
 
 
845
 
PJ_END_DECL
846
 
 
847
 
/**
848
 
 * @}
849
 
 */
850
 
 
851
 
 
852
 
#endif  /* __PJMEDIA_TRANSPORT_H__ */