← Back to branch summary

~ubuntu-branches/ubuntu/vivid/sflphone/vivid

« back to all changes in this revision

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

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2015-01-07 14:51:16 UTC
  • mfrom: (4.3.5 sid)
  • Revision ID: package-import@ubuntu.com-20150107145116-yxnafinf4lrdvrmx
Tags: 1.4.1-0.1ubuntu1
* Merge with Debian, remaining changes:
 - Drop soprano, nepomuk build-dep
* Drop ubuntu patches, now upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.2.1/pjmedia/include/pjmedia/transport.h
 
1
/* $Id: transport.h 4345 2013-02-13 07:43:32Z 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 transport 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
 * Utility API to get transport type specific info from the specified media
 
585
 * transport info.
 
586
 * 
 
587
 * @param info      Media transport info.
 
588
 * @param type      Media transport type.
 
589
 *
 
590
 * @return          Pointer to media transport specific info, or NULL if
 
591
 *                  specific info for the transport type is not found.
 
592
 */
 
593
PJ_INLINE(void*) pjmedia_transport_info_get_spc_info(
 
594
                                                pjmedia_transport_info *info,
 
595
                                                pjmedia_transport_type type)
 
596
{
 
597
    unsigned i;
 
598
    for (i = 0; i < info->specific_info_cnt; ++i) {
 
599
        if (info->spc_info[i].type == type)
 
600
            return (void*)info->spc_info[i].buffer;
 
601
    }
 
602
    return NULL;
 
603
}
 
604
 
 
605
 
 
606
/**
 
607
 * Attach callbacks to be called on receipt of incoming RTP/RTCP packets.
 
608
 * This is just a simple wrapper which calls <tt>attach()</tt> member of 
 
609
 * the transport.
 
610
 *
 
611
 * @param tp        The media transport.
 
612
 * @param user_data Arbitrary user data to be set when the callbacks are 
 
613
 *                  called.
 
614
 * @param rem_addr  Remote RTP address to send RTP packet to.
 
615
 * @param rem_rtcp  Optional remote RTCP address. If the argument is NULL
 
616
 *                  or if the address is zero, the RTCP address will be
 
617
 *                  calculated from the RTP address (which is RTP port
 
618
 *                  plus one).
 
619
 * @param addr_len  Length of the remote address.
 
620
 * @param rtp_cb    Callback to be called when RTP packet is received on
 
621
 *                  the transport.
 
622
 * @param rtcp_cb   Callback to be called when RTCP packet is received on
 
623
 *                  the transport.
 
624
 *
 
625
 * @return          PJ_SUCCESS on success, or the appropriate error code.
 
626
 */
 
627
PJ_INLINE(pj_status_t) pjmedia_transport_attach(pjmedia_transport *tp,
 
628
                                                void *user_data,
 
629
                                                const pj_sockaddr_t *rem_addr,
 
630
                                                const pj_sockaddr_t *rem_rtcp,
 
631
                                                unsigned addr_len,
 
632
                                                void (*rtp_cb)(void *user_data,
 
633
                                                               void *pkt,
 
634
                                                               pj_ssize_t),
 
635
                                                void (*rtcp_cb)(void *usr_data,
 
636
                                                                void*pkt,
 
637
                                                                pj_ssize_t))
 
638
{
 
639
    return tp->op->attach(tp, user_data, rem_addr, rem_rtcp, addr_len, 
 
640
                          rtp_cb, rtcp_cb);
 
641
}
 
642
 
 
643
 
 
644
/**
 
645
 * Detach callbacks from the transport.
 
646
 * This is just a simple wrapper which calls <tt>detach()</tt> member of 
 
647
 * the transport. After the transport is detached, it will ignore incoming
 
648
 * RTP/RTCP packets, and will refuse to send outgoing RTP/RTCP packets.
 
649
 * Application may re-attach the media transport to another transport user
 
650
 * (e.g. stream) after the transport has been detached.
 
651
 *
 
652
 * @param tp        The media transport.
 
653
 * @param user_data User data which must match the previously set value
 
654
 *                  on attachment.
 
655
 */
 
656
PJ_INLINE(void) pjmedia_transport_detach(pjmedia_transport *tp,
 
657
                                         void *user_data)
 
658
{
 
659
    tp->op->detach(tp, user_data);
 
660
}
 
661
 
 
662
 
 
663
/**
 
664
 * Send RTP packet with the specified media transport. This is just a simple
 
665
 * wrapper which calls <tt>send_rtp()</tt> member of the transport. The 
 
666
 * RTP packet will be delivered to the destination address specified in
 
667
 * #pjmedia_transport_attach() function.
 
668
 *
 
669
 * @param tp        The media transport.
 
670
 * @param pkt       The packet to send.
 
671
 * @param size      Size of the packet.
 
672
 *
 
673
 * @return          PJ_SUCCESS on success, or the appropriate error code.
 
674
 */
 
675
PJ_INLINE(pj_status_t) pjmedia_transport_send_rtp(pjmedia_transport *tp,
 
676
                                                  const void *pkt,
 
677
                                                  pj_size_t size)
 
678
{
 
679
    return (*tp->op->send_rtp)(tp, pkt, size);
 
680
}
 
681
 
 
682
 
 
683
/**
 
684
 * Send RTCP packet with the specified media transport. This is just a simple
 
685
 * wrapper which calls <tt>send_rtcp()</tt> member of the transport. The 
 
686
 * RTCP packet will be delivered to the destination address specified in
 
687
 * #pjmedia_transport_attach() function.
 
688
 *
 
689
 * @param tp        The media transport.
 
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_rtcp(pjmedia_transport *tp,
 
696
                                                  const void *pkt,
 
697
                                                  pj_size_t size)
 
698
{
 
699
    return (*tp->op->send_rtcp)(tp, pkt, size);
 
700
}
 
701
 
 
702
 
 
703
/**
 
704
 * Send RTCP packet with the specified media transport. This is just a simple
 
705
 * wrapper which calls <tt>send_rtcp2()</tt> member of the transport. The 
 
706
 * RTCP packet will be delivered to the destination address specified in
 
707
 * param addr, if addr is NULL, RTCP packet will be delivered to destination 
 
708
 * address specified in #pjmedia_transport_attach() function.
 
709
 *
 
710
 * @param tp        The media transport.
 
711
 * @param addr      The destination address.
 
712
 * @param addr_len  Length of destination address.
 
713
 * @param pkt       The packet to send.
 
714
 * @param size      Size of the packet.
 
715
 *
 
716
 * @return          PJ_SUCCESS on success, or the appropriate error code.
 
717
 */
 
718
PJ_INLINE(pj_status_t) pjmedia_transport_send_rtcp2(pjmedia_transport *tp,
 
719
                                                    const pj_sockaddr_t *addr,
 
720
                                                    unsigned addr_len,
 
721
                                                    const void *pkt,
 
722
                                                    pj_size_t size)
 
723
{
 
724
    return (*tp->op->send_rtcp2)(tp, addr, addr_len, pkt, size);
 
725
}
 
726
 
 
727
 
 
728
/**
 
729
 * Prepare the media transport for a new media session, Application must
 
730
 * call this function before starting a new media session using this
 
731
 * transport.
 
732
 *
 
733
 * This is just a simple wrapper which calls <tt>media_create()</tt> member 
 
734
 * of the transport.
 
735
 *
 
736
 * @param tp            The media transport.
 
737
 * @param sdp_pool      Pool object to allocate memory related to SDP
 
738
 *                      messaging components.
 
739
 * @param options       Option flags, from #pjmedia_tranport_media_option
 
740
 * @param rem_sdp       Remote SDP if local SDP is an answer, otherwise
 
741
 *                      specify NULL if SDP is an offer.
 
742
 * @param media_index   Media index in SDP.
 
743
 *
 
744
 * @return              PJ_SUCCESS on success, or the appropriate error code.
 
745
 */
 
746
PJ_INLINE(pj_status_t) pjmedia_transport_media_create(pjmedia_transport *tp,
 
747
                                    pj_pool_t *sdp_pool,
 
748
                                    unsigned options,
 
749
                                    const pjmedia_sdp_session *rem_sdp,
 
750
                                    unsigned media_index)
 
751
{
 
752
    return (*tp->op->media_create)(tp, sdp_pool, options, rem_sdp, 
 
753
                                   media_index);
 
754
}
 
755
 
 
756
 
 
757
/**
 
758
 * Put transport specific information into the SDP. This function can be
 
759
 * called to put transport specific information in the initial or
 
760
 * subsequent SDP offer or answer.
 
761
 *
 
762
 * This is just a simple wrapper which calls <tt>encode_sdp()</tt> member 
 
763
 * of the transport.
 
764
 *
 
765
 * @param tp            The media transport.
 
766
 * @param sdp_pool      Pool object to allocate memory related to SDP
 
767
 *                      messaging components.
 
768
 * @param sdp           The local SDP to be filled in information from the
 
769
 *                      media transport.
 
770
 * @param rem_sdp       Remote SDP if local SDP is an answer, otherwise
 
771
 *                      specify NULL if SDP is an offer.
 
772
 * @param media_index   Media index in SDP.
 
773
 *
 
774
 * @return              PJ_SUCCESS on success, or the appropriate error code.
 
775
 */
 
776
PJ_INLINE(pj_status_t) pjmedia_transport_encode_sdp(pjmedia_transport *tp,
 
777
                                            pj_pool_t *sdp_pool,
 
778
                                            pjmedia_sdp_session *sdp,
 
779
                                            const pjmedia_sdp_session *rem_sdp,
 
780
                                            unsigned media_index)
 
781
{
 
782
    return (*tp->op->encode_sdp)(tp, sdp_pool, sdp, rem_sdp, media_index);
 
783
}
 
784
 
 
785
 
 
786
/**
 
787
 * Start the transport session with the settings in both local and remote 
 
788
 * SDP. The actual work that is done by this function depends on the 
 
789
 * underlying transport type. For SRTP, this will activate the encryption
 
790
 * and decryption based on the keys found the SDPs. For ICE, this will
 
791
 * start ICE negotiation according to the information found in the SDPs.
 
792
 *
 
793
 * This is just a simple wrapper which calls <tt>media_start()</tt> member 
 
794
 * of the transport.
 
795
 *
 
796
 * @param tp            The media transport.
 
797
 * @param tmp_pool      The memory pool for allocating temporary objects.
 
798
 * @param sdp_local     Local SDP.
 
799
 * @param sdp_remote    Remote SDP.
 
800
 * @param media_index   Media index in the SDP.
 
801
 *
 
802
 * @return              PJ_SUCCESS on success, or the appropriate error code.
 
803
 */
 
804
PJ_INLINE(pj_status_t) pjmedia_transport_media_start(pjmedia_transport *tp,
 
805
                                    pj_pool_t *tmp_pool,
 
806
                                    const pjmedia_sdp_session *sdp_local,
 
807
                                    const pjmedia_sdp_session *sdp_remote,
 
808
                                    unsigned media_index)
 
809
{
 
810
    return (*tp->op->media_start)(tp, tmp_pool, sdp_local, sdp_remote, 
 
811
                                  media_index);
 
812
}
 
813
 
 
814
 
 
815
/**
 
816
 * This API should be called when the session is stopped, to allow the media
 
817
 * transport to release its resources used for the session.
 
818
 *
 
819
 * This is just a simple wrapper which calls <tt>media_stop()</tt> member 
 
820
 * of the transport.
 
821
 *
 
822
 * @param tp            The media transport.
 
823
 *
 
824
 * @return              PJ_SUCCESS on success, or the appropriate error code.
 
825
 */
 
826
PJ_INLINE(pj_status_t) pjmedia_transport_media_stop(pjmedia_transport *tp)
 
827
{
 
828
    return (*tp->op->media_stop)(tp);
 
829
}
 
830
 
 
831
/**
 
832
 * Close media transport. This is just a simple wrapper which calls 
 
833
 * <tt>destroy()</tt> member of the transport. This function will free
 
834
 * all resources created by this transport (such as sockets, memory, etc.).
 
835
 *
 
836
 * @param tp        The media transport.
 
837
 *
 
838
 * @return          PJ_SUCCESS on success, or the appropriate error code.
 
839
 */
 
840
PJ_INLINE(pj_status_t) pjmedia_transport_close(pjmedia_transport *tp)
 
841
{
 
842
    if (tp->op->destroy)
 
843
        return (*tp->op->destroy)(tp);
 
844
    else
 
845
        return PJ_SUCCESS;
 
846
}
 
847
 
 
848
/**
 
849
 * Simulate packet lost in the specified direction (for testing purposes).
 
850
 * When enabled, the transport will randomly drop packets to the specified
 
851
 * direction.
 
852
 *
 
853
 * @param tp        The media transport.
 
854
 * @param dir       Media direction to which packets will be randomly dropped.
 
855
 * @param pct_lost  Percent lost (0-100). Set to zero to disable packet
 
856
 *                  lost simulation.
 
857
 *
 
858
 * @return          PJ_SUCCESS on success.
 
859
 */
 
860
PJ_INLINE(pj_status_t) pjmedia_transport_simulate_lost(pjmedia_transport *tp,
 
861
                                                       pjmedia_dir dir,
 
862
                                                       unsigned pct_lost)
 
863
{
 
864
    return (*tp->op->simulate_lost)(tp, dir, pct_lost);
 
865
}
 
866
 
 
867
 
 
868
PJ_END_DECL
 
869
 
 
870
/**
 
871
 * @}
 
872
 */
 
873
 
 
874
 
 
875
#endif  /* __PJMEDIA_TRANSPORT_H__ */
 
876