← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjsip/include/pjsip/sip_transport.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
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/pjsip/include/pjsip/sip_transport.h
1
 
/* $Id: sip_transport.h 4173 2012-06-20 10:39:05Z ming $ */
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 __PJSIP_SIP_TRANSPORT_H__
21
 
#define __PJSIP_SIP_TRANSPORT_H__
22
 
 
23
 
/**
24
 
 * @file sip_transport.h
25
 
 * @brief SIP Transport
26
 
 */
27
 
 
28
 
#include <pjsip/sip_msg.h>
29
 
#include <pjsip/sip_parser.h>
30
 
#include <pjsip/sip_resolve.h>
31
 
#include <pj/sock.h>
32
 
#include <pj/list.h>
33
 
#include <pj/ioqueue.h>
34
 
#include <pj/timer.h>
35
 
 
36
 
PJ_BEGIN_DECL
37
 
 
38
 
/**
39
 
 * @defgroup PJSIP_TRANSPORT Transport
40
 
 * @ingroup PJSIP_CORE
41
 
 * @brief This is the transport framework.
42
 
 *
43
 
 * The transport framework is fully extensible. Please see
44
 
 * <A HREF="/docs.htm">PJSIP Developer's Guide</A> PDF
45
 
 * document for more information.
46
 
 *
47
 
 * Application MUST register at least one transport to PJSIP before any
48
 
 * messages can be sent or received. Please see @ref PJSIP_TRANSPORT_UDP
49
 
 * on how to create/register UDP transport to the transport framework.
50
 
 *
51
 
 * @{
52
 
 */
53
 
 
54
 
/*****************************************************************************
55
 
 *
56
 
 * GENERAL TRANSPORT (NAMES, TYPES, ETC.)
57
 
 *
58
 
 *****************************************************************************/
59
 
 
60
 
/*
61
 
 * Forward declaration for transport factory (since it is referenced by
62
 
 * the transport factory itself).
63
 
 */
64
 
typedef struct pjsip_tpfactory pjsip_tpfactory;
65
 
 
66
 
 
67
 
/**
68
 
 * Flags for SIP transports.
69
 
 */
70
 
enum pjsip_transport_flags_e
71
 
{
72
 
    PJSIP_TRANSPORT_RELIABLE        = 1,    /**< Transport is reliable.     */
73
 
    PJSIP_TRANSPORT_SECURE          = 2,    /**< Transport is secure.       */
74
 
    PJSIP_TRANSPORT_DATAGRAM        = 4     /**< Datagram based transport.
75
 
                                                 (it's also assumed to be
76
 
                                                 connectionless)            */
77
 
};
78
 
 
79
 
/**
80
 
 * Check if transport tp is reliable.
81
 
 */
82
 
#define PJSIP_TRANSPORT_IS_RELIABLE(tp)     \
83
 
            ((tp)->flag & PJSIP_TRANSPORT_RELIABLE)
84
 
 
85
 
/**
86
 
 * Check if transport tp is secure.
87
 
 */
88
 
#define PJSIP_TRANSPORT_IS_SECURE(tp)       \
89
 
            ((tp)->flag & PJSIP_TRANSPORT_SECURE)
90
 
 
91
 
/**
92
 
 * Register new transport type to PJSIP. The PJSIP transport framework
93
 
 * contains the info for some standard transports, as declared by
94
 
 * #pjsip_transport_type_e. Application may use non-standard transport
95
 
 * with PJSIP, but before it does so, it must register the information
96
 
 * about the new transport type to PJSIP by calling this function.
97
 
 *
98
 
 * @param tp_flag   The flags describing characteristics of this
99
 
 *                  transport type.
100
 
 * @param tp_name   Transport type name.
101
 
 * @param def_port  Default port to be used for the transport.
102
 
 * @param p_tp_type On successful registration, it will be filled with
103
 
 *                  the registered type. This argument is optional.
104
 
 *
105
 
 * @return          PJ_SUCCESS if registration is successful, or
106
 
 *                  PJSIP_ETYPEEXISTS if the same transport type has
107
 
 *                  already been registered.
108
 
 */
109
 
PJ_DECL(pj_status_t) pjsip_transport_register_type(unsigned tp_flag,
110
 
                                                   const char *tp_name,
111
 
                                                   int def_port,
112
 
                                                   int *p_tp_type);
113
 
 
114
 
 
115
 
/**
116
 
 * Get the transport type from the transport name.
117
 
 *
118
 
 * @param name      Transport name, such as "TCP", or "UDP".
119
 
 *
120
 
 * @return          The transport type, or PJSIP_TRANSPORT_UNSPECIFIED if
121
 
 *                  the name is not recognized as the name of supported
122
 
 *                  transport.
123
 
 */
124
 
PJ_DECL(pjsip_transport_type_e)
125
 
pjsip_transport_get_type_from_name(const pj_str_t *name);
126
 
 
127
 
/**
128
 
 * Get the transport type for the specified flags.
129
 
 *
130
 
 * @param flag      The transport flag.
131
 
 *
132
 
 * @return          Transport type.
133
 
 */
134
 
PJ_DECL(pjsip_transport_type_e)
135
 
pjsip_transport_get_type_from_flag(unsigned flag);
136
 
 
137
 
/**
138
 
 * Get the socket address family of a given transport type.
139
 
 *
140
 
 * @param type      Transport type.
141
 
 *
142
 
 * @return          Transport type.
143
 
 */
144
 
PJ_DECL(int) pjsip_transport_type_get_af(pjsip_transport_type_e type);
145
 
 
146
 
/**
147
 
 * Get transport flag from type.
148
 
 *
149
 
 * @param type      Transport type.
150
 
 *
151
 
 * @return          Transport flags.
152
 
 */
153
 
PJ_DECL(unsigned)
154
 
pjsip_transport_get_flag_from_type( pjsip_transport_type_e type );
155
 
 
156
 
/**
157
 
 * Get the default SIP port number for the specified type.
158
 
 *
159
 
 * @param type      Transport type.
160
 
 *
161
 
 * @return          The port number, which is the default SIP port number for
162
 
 *                  the specified type.
163
 
 */
164
 
PJ_DECL(int)
165
 
pjsip_transport_get_default_port_for_type(pjsip_transport_type_e type);
166
 
 
167
 
/**
168
 
 * Get transport type name.
169
 
 *
170
 
 * @param t         Transport type.
171
 
 *
172
 
 * @return          Transport name.
173
 
 */
174
 
PJ_DECL(const char*) pjsip_transport_get_type_name(pjsip_transport_type_e t);
175
 
 
176
 
/**
177
 
 * Get longer description for the specified transport type.
178
 
 *
179
 
 * @param t         Transport type.
180
 
 *
181
 
 * @return          Transport description.
182
 
 */
183
 
PJ_DECL(const char*) pjsip_transport_get_type_desc(pjsip_transport_type_e t);
184
 
 
185
 
 
186
 
 
187
 
/*****************************************************************************
188
 
 *
189
 
 * TRANSPORT SELECTOR.
190
 
 *
191
 
 *****************************************************************************/
192
 
 
193
 
/**
194
 
 * This structure describes the type of data in pjsip_tpselector.
195
 
 */
196
 
typedef enum pjsip_tpselector_type
197
 
{
198
 
    /** Transport is not specified. */
199
 
    PJSIP_TPSELECTOR_NONE,
200
 
 
201
 
    /** Use the specific transport to send request. */
202
 
    PJSIP_TPSELECTOR_TRANSPORT,
203
 
 
204
 
    /** Use the specific listener to send request. */
205
 
    PJSIP_TPSELECTOR_LISTENER,
206
 
 
207
 
} pjsip_tpselector_type;
208
 
 
209
 
 
210
 
/**
211
 
 * This structure describes the transport/listener preference to be used
212
 
 * when sending outgoing requests.
213
 
 *
214
 
 * Normally transport will be selected automatically according to rules about
215
 
 * sending requests. But some applications (such as proxies or B2BUAs) may
216
 
 * want to explicitly use specific transport to send requests, for example
217
 
 * when they want to make sure that outgoing request should go from a specific
218
 
 * network interface.
219
 
 *
220
 
 * The pjsip_tpselector structure is used for that purpose, i.e. to allow
221
 
 * application specificly request that a particular transport/listener
222
 
 * should be used to send request. This structure is used when calling
223
 
 * pjsip_tsx_set_transport() and pjsip_dlg_set_transport().
224
 
 */
225
 
typedef struct pjsip_tpselector
226
 
{
227
 
    /** The type of data in the union */
228
 
    pjsip_tpselector_type   type;
229
 
 
230
 
    /** Union representing the transport/listener criteria to be used. */
231
 
    union {
232
 
        pjsip_transport *transport;
233
 
        pjsip_tpfactory *listener;
234
 
        void            *ptr;
235
 
    } u;
236
 
 
237
 
} pjsip_tpselector;
238
 
 
239
 
 
240
 
/**
241
 
 * Add transport/listener reference in the selector to prevent the specified
242
 
 * transport/listener from being destroyed while application still has
243
 
 * reference to it.
244
 
 *
245
 
 * @param sel   The transport selector.
246
 
 */
247
 
PJ_DECL(void) pjsip_tpselector_add_ref(pjsip_tpselector *sel);
248
 
 
249
 
 
250
 
/**
251
 
 * Decrement transport/listener reference in the selector.
252
 
 * @param sel   The transport selector
253
 
 */
254
 
PJ_DECL(void) pjsip_tpselector_dec_ref(pjsip_tpselector *sel);
255
 
 
256
 
 
257
 
/*****************************************************************************
258
 
 *
259
 
 * RECEIVE DATA BUFFER.
260
 
 *
261
 
 *****************************************************************************/
262
 
 
263
 
/**
264
 
 * A customized ioqueue async operation key which is used by transport
265
 
 * to locate rdata when a pending read operation completes.
266
 
 */
267
 
typedef struct pjsip_rx_data_op_key
268
 
{
269
 
    pj_ioqueue_op_key_t         op_key; /**< ioqueue op_key.            */
270
 
    pjsip_rx_data              *rdata;  /**< rdata associated with this */
271
 
} pjsip_rx_data_op_key;
272
 
 
273
 
 
274
 
/**
275
 
 * Incoming message buffer.
276
 
 * This structure keep all the information regarding the received message. This
277
 
 * buffer lifetime is only very short, normally after the transaction has been
278
 
 * called, this buffer will be deleted/recycled. So care must be taken when
279
 
 * allocating storage from the pool of this buffer.
280
 
 */
281
 
struct pjsip_rx_data
282
 
{
283
 
 
284
 
    /**
285
 
     * tp_info is part of rdata that remains static for the duration of the
286
 
     * buffer. It is initialized when the buffer was created by transport.
287
 
     */
288
 
    struct
289
 
    {
290
 
        /** Memory pool for this buffer. */
291
 
        pj_pool_t               *pool;
292
 
 
293
 
        /** The transport object which received this packet. */
294
 
        pjsip_transport         *transport;
295
 
 
296
 
        /** Other transport specific data to be attached to this buffer. */
297
 
        void                    *tp_data;
298
 
 
299
 
        /** Ioqueue key. */
300
 
        pjsip_rx_data_op_key     op_key;
301
 
 
302
 
    } tp_info;
303
 
 
304
 
 
305
 
    /**
306
 
     * pkt_info is initialized by transport when it receives an incoming
307
 
     * packet.
308
 
     */
309
 
    struct
310
 
    {
311
 
        /** Time when the message was received. */
312
 
        pj_time_val              timestamp;
313
 
 
314
 
        /** Pointer to the original packet. */
315
 
        char                     packet[PJSIP_MAX_PKT_LEN];
316
 
 
317
 
        /** Zero termination for the packet. */
318
 
        pj_uint32_t              zero;
319
 
 
320
 
        /** The length of the packet received. */
321
 
        pj_ssize_t               len;
322
 
 
323
 
        /** The source address from which the packet was received. */
324
 
        pj_sockaddr              src_addr;
325
 
 
326
 
        /** The length of the source address. */
327
 
        int                      src_addr_len;
328
 
 
329
 
        /** The IP source address string (NULL terminated). */
330
 
        char                     src_name[PJ_INET6_ADDRSTRLEN];
331
 
 
332
 
        /** The IP source port number. */
333
 
        int                      src_port;
334
 
 
335
 
    } pkt_info;
336
 
 
337
 
 
338
 
    /**
339
 
     * msg_info is initialized by transport mgr (tpmgr) before this buffer
340
 
     * is passed to endpoint.
341
 
     */
342
 
    struct
343
 
    {
344
 
        /** Start of msg buffer. */
345
 
        char                    *msg_buf;
346
 
 
347
 
        /** Length fo message. */
348
 
        int                      len;
349
 
 
350
 
        /** The parsed message, if any. */
351
 
        pjsip_msg               *msg;
352
 
 
353
 
        /** Short description about the message.
354
 
         *  Application should use #pjsip_rx_data_get_info() instead.
355
 
         */
356
 
        char                    *info;
357
 
 
358
 
        /** The Call-ID header as found in the message. */
359
 
        pjsip_cid_hdr           *cid;
360
 
 
361
 
        /** The From header as found in the message. */
362
 
        pjsip_from_hdr          *from;
363
 
 
364
 
        /** The To header as found in the message. */
365
 
        pjsip_to_hdr            *to;
366
 
 
367
 
        /** The topmost Via header as found in the message. */
368
 
        pjsip_via_hdr           *via;
369
 
 
370
 
        /** The CSeq header as found in the message. */
371
 
        pjsip_cseq_hdr          *cseq;
372
 
 
373
 
        /** Max forwards header. */
374
 
        pjsip_max_fwd_hdr       *max_fwd;
375
 
 
376
 
        /** The first route header. */
377
 
        pjsip_route_hdr         *route;
378
 
 
379
 
        /** The first record-route header. */
380
 
        pjsip_rr_hdr            *record_route;
381
 
 
382
 
        /** Content-type header. */
383
 
        pjsip_ctype_hdr         *ctype;
384
 
 
385
 
        /** Content-length header. */
386
 
        pjsip_clen_hdr          *clen;
387
 
 
388
 
        /** "Require" header containing aggregates of all Require
389
 
         *  headers found in the message, or NULL.
390
 
         */
391
 
        pjsip_require_hdr       *require;
392
 
 
393
 
        /** "Supported" header containing aggregates of all Supported
394
 
         *  headers found in the message, or NULL.
395
 
         */
396
 
        pjsip_supported_hdr     *supported;
397
 
 
398
 
        /** The list of error generated by the parser when parsing
399
 
            this message.
400
 
         */
401
 
        pjsip_parser_err_report parse_err;
402
 
 
403
 
    } msg_info;
404
 
 
405
 
 
406
 
    /**
407
 
     * endpt_info is initialized by endpoint after this buffer reaches
408
 
     * endpoint.
409
 
     */
410
 
    struct
411
 
    {
412
 
        /**
413
 
         * Data attached by modules to this message.
414
 
         */
415
 
        void    *mod_data[PJSIP_MAX_MODULE];
416
 
 
417
 
    } endpt_info;
418
 
 
419
 
};
420
 
 
421
 
/**
422
 
 * Get printable information about the message in the rdata.
423
 
 *
424
 
 * @param rdata     The receive data buffer.
425
 
 *
426
 
 * @return          Printable information.
427
 
 */
428
 
PJ_DECL(char*) pjsip_rx_data_get_info(pjsip_rx_data *rdata);
429
 
 
430
 
 
431
 
/*****************************************************************************
432
 
 *
433
 
 * TRANSMIT DATA BUFFER MANIPULATION.
434
 
 *
435
 
 *****************************************************************************/
436
 
 
437
 
/** Customized ioqueue async operation key, used by transport to keep
438
 
 *  callback parameters.
439
 
 */
440
 
typedef struct pjsip_tx_data_op_key
441
 
{
442
 
    /** ioqueue pending operation key. */
443
 
    pj_ioqueue_op_key_t     key;
444
 
 
445
 
    /** Transmit data associated with this key. */
446
 
    pjsip_tx_data          *tdata;
447
 
 
448
 
    /** Arbitrary token (attached by transport) */
449
 
    void                   *token;
450
 
 
451
 
    /** Callback to be called when pending transmit operation has
452
 
        completed.
453
 
     */
454
 
    void                  (*callback)(pjsip_transport*,void*,pj_ssize_t);
455
 
} pjsip_tx_data_op_key;
456
 
 
457
 
 
458
 
/**
459
 
 * Data structure for sending outgoing message. Application normally creates
460
 
 * this buffer by calling #pjsip_endpt_create_tdata.
461
 
 *
462
 
 * The lifetime of this buffer is controlled by the reference counter in this
463
 
 * structure, which is manipulated by calling #pjsip_tx_data_add_ref and
464
 
 * #pjsip_tx_data_dec_ref. When the reference counter has reached zero, then
465
 
 * this buffer will be destroyed.
466
 
 *
467
 
 * A transaction object normally will add reference counter to this buffer
468
 
 * when application calls #pjsip_tsx_send_msg, because it needs to keep the
469
 
 * message for retransmission. The transaction will release the reference
470
 
 * counter once its state has reached final state.
471
 
 */
472
 
struct pjsip_tx_data
473
 
{
474
 
    /** This is for transmission queue; it's managed by transports. */
475
 
    PJ_DECL_LIST_MEMBER(struct pjsip_tx_data);
476
 
 
477
 
    /** Memory pool for this buffer. */
478
 
    pj_pool_t           *pool;
479
 
 
480
 
    /** A name to identify this buffer. */
481
 
    char                 obj_name[PJ_MAX_OBJ_NAME];
482
 
 
483
 
    /** Short information describing this buffer and the message in it.
484
 
     *  Application should use #pjsip_tx_data_get_info() instead of
485
 
     *  directly accessing this member.
486
 
     */
487
 
    char                *info;
488
 
 
489
 
    /** For response message, this contains the reference to timestamp when
490
 
     *  the original request message was received. The value of this field
491
 
     *  is set when application creates response message to a request by
492
 
     *  calling #pjsip_endpt_create_response.
493
 
     */
494
 
    pj_time_val          rx_timestamp;
495
 
 
496
 
    /** The transport manager for this buffer. */
497
 
    pjsip_tpmgr         *mgr;
498
 
 
499
 
    /** Ioqueue asynchronous operation key. */
500
 
    pjsip_tx_data_op_key op_key;
501
 
 
502
 
    /** Lock object. */
503
 
    pj_lock_t           *lock;
504
 
 
505
 
    /** The message in this buffer. */
506
 
    pjsip_msg           *msg;
507
 
 
508
 
    /** Strict route header saved by #pjsip_process_route_set(), to be
509
 
     *  restored by #pjsip_restore_strict_route_set().
510
 
     */
511
 
    pjsip_route_hdr     *saved_strict_route;
512
 
 
513
 
    /** Buffer to the printed text representation of the message. When the
514
 
     *  content of this buffer is set, then the transport will send the content
515
 
     *  of this buffer instead of re-printing the message structure. If the
516
 
     *  message structure has changed, then application must invalidate this
517
 
     *  buffer by calling #pjsip_tx_data_invalidate_msg.
518
 
     */
519
 
    pjsip_buffer         buf;
520
 
 
521
 
    /** Reference counter. */
522
 
    pj_atomic_t         *ref_cnt;
523
 
 
524
 
    /** Being processed by transport? */
525
 
    int                  is_pending;
526
 
 
527
 
    /** Transport manager internal. */
528
 
    void                *token;
529
 
 
530
 
    /** Callback to be called when this tx_data has been transmitted.   */
531
 
    void               (*cb)(void*, pjsip_tx_data*, pj_ssize_t);
532
 
 
533
 
    /** Destination information, to be used to determine the network address
534
 
     *  of the message. For a request, this information is  initialized when
535
 
     *  the request is sent with #pjsip_endpt_send_request_stateless() and
536
 
     *  network address is resolved. For CANCEL request, this information
537
 
     *  will be copied from the original INVITE to make sure that the CANCEL
538
 
     *  request goes to the same physical network address as the INVITE
539
 
     *  request.
540
 
     */
541
 
    struct
542
 
    {
543
 
        /** Server name.
544
 
         */
545
 
        pj_str_t                 name;
546
 
 
547
 
        /** Server addresses resolved.
548
 
         */
549
 
        pjsip_server_addresses   addr;
550
 
 
551
 
        /** Current server address being tried.
552
 
         */
553
 
        unsigned cur_addr;
554
 
 
555
 
    } dest_info;
556
 
 
557
 
    /** Transport information, only valid during on_tx_request() and
558
 
     *  on_tx_response() callback.
559
 
     */
560
 
    struct
561
 
    {
562
 
        pjsip_transport     *transport;     /**< Transport being used.  */
563
 
        pj_sockaddr          dst_addr;      /**< Destination address.   */
564
 
        int                  dst_addr_len;  /**< Length of address.     */
565
 
        char                 dst_name[PJ_INET6_ADDRSTRLEN]; /**< Destination address.   */
566
 
        int                  dst_port;      /**< Destination port.      */
567
 
    } tp_info;
568
 
 
569
 
    /**
570
 
     * Transport selector, to specify which transport to be used.
571
 
     * The value here must be set with pjsip_tx_data_set_transport(),
572
 
     * to allow reference counter to be set properly.
573
 
     */
574
 
    pjsip_tpselector        tp_sel;
575
 
 
576
 
    /**
577
 
     * Special flag to indicate that this transmit data is a request that has
578
 
     * been updated with proper authentication response and is ready to be
579
 
     * sent for retry.
580
 
     */
581
 
    pj_bool_t               auth_retry;
582
 
 
583
 
    /**
584
 
     * Arbitrary data attached by PJSIP modules.
585
 
     */
586
 
    void                    *mod_data[PJSIP_MAX_MODULE];
587
 
 
588
 
    /**
589
 
     * If via_addr is set, it will be used as the "sent-by" field of the
590
 
     * Via header for outgoing requests as long as the request uses via_tp
591
 
     * transport. Normally application should not use or access these fields.
592
 
     */
593
 
    pjsip_host_port          via_addr;      /**< Via address.           */
594
 
    const void              *via_tp;        /**< Via transport.         */
595
 
};
596
 
 
597
 
 
598
 
/**
599
 
 * Create a new, blank transmit buffer. The reference count is initialized
600
 
 * to zero.
601
 
 *
602
 
 * @param mgr           The transport manager.
603
 
 * @param tdata         Pointer to receive transmit data.
604
 
 *
605
 
 * @return              PJ_SUCCESS, or the appropriate error code.
606
 
 *
607
 
 * @see pjsip_endpt_create_tdata
608
 
 */
609
 
PJ_DECL(pj_status_t) pjsip_tx_data_create( pjsip_tpmgr *mgr,
610
 
                                           pjsip_tx_data **tdata );
611
 
 
612
 
/**
613
 
 * Add reference counter to the transmit buffer. The reference counter controls
614
 
 * the life time of the buffer, ie. when the counter reaches zero, then it
615
 
 * will be destroyed.
616
 
 *
617
 
 * @param tdata     The transmit buffer.
618
 
 */
619
 
PJ_DECL(void) pjsip_tx_data_add_ref( pjsip_tx_data *tdata );
620
 
 
621
 
/**
622
 
 * Decrement reference counter of the transmit buffer.
623
 
 * When the transmit buffer is no longer used, it will be destroyed and
624
 
 * caller is informed with PJSIP_EBUFDESTROYED return status.
625
 
 *
626
 
 * @param tdata     The transmit buffer data.
627
 
 * @return          This function will always succeeded eventhough the return
628
 
 *                  status is non-zero. A status PJSIP_EBUFDESTROYED will be
629
 
 *                  returned to inform that buffer is destroyed.
630
 
 */
631
 
PJ_DECL(pj_status_t) pjsip_tx_data_dec_ref( pjsip_tx_data *tdata );
632
 
 
633
 
/**
634
 
 * Print the SIP message to transmit data buffer's internal buffer. This
635
 
 * may allocate memory for the buffer, if the buffer has not been allocated
636
 
 * yet, and encode the SIP message to that buffer.
637
 
 *
638
 
 * @param tdata     The transmit buffer.
639
 
 *
640
 
 * @return          PJ_SUCCESS on success of the appropriate error code.
641
 
 */
642
 
PJ_DECL(pj_status_t) pjsip_tx_data_encode(pjsip_tx_data *tdata);
643
 
 
644
 
/**
645
 
 * Check if transmit data buffer contains a valid message.
646
 
 *
647
 
 * @param tdata     The transmit buffer.
648
 
 * @return          Non-zero (PJ_TRUE) if buffer contains a valid message.
649
 
 */
650
 
PJ_DECL(pj_bool_t) pjsip_tx_data_is_valid( pjsip_tx_data *tdata );
651
 
 
652
 
/**
653
 
 * Invalidate the print buffer to force message to be re-printed. Call
654
 
 * when the message has changed after it has been printed to buffer. The
655
 
 * message is printed to buffer normally by transport when it is about to be
656
 
 * sent to the wire. Subsequent sending of the message will not cause
657
 
 * the message to be re-printed, unless application invalidates the buffer
658
 
 * by calling this function.
659
 
 *
660
 
 * @param tdata     The transmit buffer.
661
 
 */
662
 
PJ_DECL(void) pjsip_tx_data_invalidate_msg( pjsip_tx_data *tdata );
663
 
 
664
 
/**
665
 
 * Get short printable info about the transmit data. This will normally return
666
 
 * short information about the message.
667
 
 *
668
 
 * @param tdata     The transmit buffer.
669
 
 *
670
 
 * @return          Null terminated info string.
671
 
 */
672
 
PJ_DECL(char*) pjsip_tx_data_get_info( pjsip_tx_data *tdata );
673
 
 
674
 
/**
675
 
 * Set the explicit transport to be used when sending this transmit data.
676
 
 * Application should not need to call this function, but rather use
677
 
 * pjsip_tsx_set_transport() and pjsip_dlg_set_transport() instead (which
678
 
 * will call this function).
679
 
 *
680
 
 * @param tdata     The transmit buffer.
681
 
 * @param sel       Transport selector.
682
 
 *
683
 
 * @return          PJ_SUCCESS on success.
684
 
 */
685
 
PJ_DECL(pj_status_t) pjsip_tx_data_set_transport(pjsip_tx_data *tdata,
686
 
                                                 const pjsip_tpselector *sel);
687
 
 
688
 
 
689
 
/*****************************************************************************
690
 
 *
691
 
 * TRANSPORT
692
 
 *
693
 
 *****************************************************************************/
694
 
/**
695
 
 * Type of callback to receive transport operation status.
696
 
 */
697
 
typedef void (*pjsip_transport_callback)(pjsip_transport *tp, void *token,
698
 
                                         pj_ssize_t sent_bytes);
699
 
 
700
 
/**
701
 
 * This structure describes transport key to be registered to hash table.
702
 
 */
703
 
typedef struct pjsip_transport_key
704
 
{
705
 
    /**
706
 
     * Transport type.
707
 
     */
708
 
    long                    type;
709
 
 
710
 
    /**
711
 
     * Destination address.
712
 
     */
713
 
    pj_sockaddr             rem_addr;
714
 
 
715
 
} pjsip_transport_key;
716
 
 
717
 
 
718
 
/**
719
 
 * Enumeration of transport direction types.
720
 
 */
721
 
typedef enum pjsip_transport_dir
722
 
{
723
 
    PJSIP_TP_DIR_NONE,              /**< Direction not set, normally used by
724
 
                                         connectionless transports such as
725
 
                                         UDP transport.                     */
726
 
    PJSIP_TP_DIR_OUTGOING,          /**< Outgoing connection or client mode,
727
 
                                         this is only for connection-oriented
728
 
                                         transports.                        */
729
 
    PJSIP_TP_DIR_INCOMING,          /**< Incoming connection or server mode,
730
 
                                         this is only for connection-oriented
731
 
                                         transports.                        */
732
 
} pjsip_transport_dir;
733
 
 
734
 
 
735
 
/**
736
 
 * This structure represent the "public" interface of a SIP transport.
737
 
 * Applications normally extend this structure to include transport
738
 
 * specific members.
739
 
 */
740
 
struct pjsip_transport
741
 
{
742
 
    char                    obj_name[PJ_MAX_OBJ_NAME];  /**< Name. */
743
 
 
744
 
    pj_pool_t              *pool;           /**< Pool used by transport.    */
745
 
    pj_atomic_t            *ref_cnt;        /**< Reference counter.         */
746
 
    pj_lock_t              *lock;           /**< Lock object.               */
747
 
    pj_bool_t               tracing;        /**< Tracing enabled?           */
748
 
    pj_bool_t               is_shutdown;    /**< Being shutdown?            */
749
 
    pj_bool_t               is_destroying;  /**< Destroy in progress?       */
750
 
 
751
 
    /** Key for indexing this transport in hash table. */
752
 
    pjsip_transport_key     key;
753
 
 
754
 
    char                   *type_name;      /**< Type name.                 */
755
 
    unsigned                flag;           /**< #pjsip_transport_flags_e   */
756
 
    char                   *info;           /**< Transport info/description.*/
757
 
 
758
 
    int                     addr_len;       /**< Length of addresses.       */
759
 
    pj_sockaddr             local_addr;     /**< Bound address.             */
760
 
    pjsip_host_port         local_name;     /**< Published name (eg. STUN). */
761
 
    pjsip_host_port         remote_name;    /**< Remote address name.       */
762
 
    pjsip_transport_dir     dir;            /**< Connection direction.      */
763
 
 
764
 
    pjsip_endpoint         *endpt;          /**< Endpoint instance.         */
765
 
    pjsip_tpmgr            *tpmgr;          /**< Transport manager.         */
766
 
    pj_timer_entry          idle_timer;     /**< Timer when ref cnt is zero.*/
767
 
 
768
 
    void                   *data;           /**< Internal transport data.   */
769
 
 
770
 
    /**
771
 
     * Function to be called by transport manager to send SIP message.
772
 
     *
773
 
     * @param transport     The transport to send the message.
774
 
     * @param packet        The buffer to send.
775
 
     * @param length        The length of the buffer to send.
776
 
     * @param op_key        Completion token, which will be supplied to
777
 
     *                      caller when pending send operation completes.
778
 
     * @param rem_addr      The remote destination address.
779
 
     * @param addr_len      Size of remote address.
780
 
     * @param callback      If supplied, the callback will be called
781
 
     *                      once a pending transmission has completed. If
782
 
     *                      the function completes immediately (i.e. return
783
 
     *                      code is not PJ_EPENDING), the callback will not
784
 
     *                      be called.
785
 
     *
786
 
     * @return              Should return PJ_SUCCESS only if data has been
787
 
     *                      succesfully queued to operating system for
788
 
     *                      transmission. Otherwise it may return PJ_EPENDING
789
 
     *                      if the underlying transport can not send the
790
 
     *                      data immediately and will send it later, which in
791
 
     *                      this case caller doesn't have to do anything
792
 
     *                      except wait the calback to be called, if it
793
 
     *                      supplies one.
794
 
     *                      Other return values indicate the error code.
795
 
     */
796
 
    pj_status_t (*send_msg)(pjsip_transport *transport,
797
 
                            pjsip_tx_data *tdata,
798
 
                            const pj_sockaddr_t *rem_addr,
799
 
                            int addr_len,
800
 
                            void *token,
801
 
                            pjsip_transport_callback callback);
802
 
 
803
 
    /**
804
 
     * Instruct the transport to initiate graceful shutdown procedure.
805
 
     * After all objects release their reference to this transport,
806
 
     * the transport will be deleted.
807
 
     *
808
 
     * Note that application MUST use #pjsip_transport_shutdown() instead.
809
 
     *
810
 
     * @param transport     The transport.
811
 
     *
812
 
     * @return              PJ_SUCCESS on success.
813
 
     */
814
 
    pj_status_t (*do_shutdown)(pjsip_transport *transport);
815
 
 
816
 
    /**
817
 
     * Forcefully destroy this transport regardless whether there are
818
 
     * objects that currently use this transport. This function should only
819
 
     * be called by transport manager or other internal objects (such as the
820
 
     * transport itself) who know what they're doing. Application should use
821
 
     * #pjsip_transport_shutdown() instead.
822
 
     *
823
 
     * @param transport     The transport.
824
 
     *
825
 
     * @return              PJ_SUCCESS on success.
826
 
     */
827
 
    pj_status_t (*destroy)(pjsip_transport *transport);
828
 
 
829
 
    /*
830
 
     * Application may extend this structure..
831
 
     */
832
 
};
833
 
 
834
 
 
835
 
/**
836
 
 * Register a transport instance to the transport manager. This function
837
 
 * is normally called by the transport instance when it is created
838
 
 * by application.
839
 
 *
840
 
 * @param mgr           The transport manager.
841
 
 * @param tp            The new transport to be registered.
842
 
 *
843
 
 * @return              PJ_SUCCESS on success.
844
 
 */
845
 
PJ_DECL(pj_status_t) pjsip_transport_register( pjsip_tpmgr *mgr,
846
 
                                               pjsip_transport *tp );
847
 
 
848
 
 
849
 
/**
850
 
 * Start graceful shutdown procedure for this transport. After graceful
851
 
 * shutdown has been initiated, no new reference can be obtained for
852
 
 * the transport. However, existing objects that currently uses the
853
 
 * transport may still use this transport to send and receive packets.
854
 
 *
855
 
 * After all objects release their reference to this transport,
856
 
 * the transport will be destroyed immediately.
857
 
 *
858
 
 * @param tp                The transport.
859
 
 *
860
 
 * @return                  PJ_SUCCESS on success.
861
 
 */
862
 
PJ_DECL(pj_status_t) pjsip_transport_shutdown(pjsip_transport *tp);
863
 
 
864
 
/**
865
 
 * Destroy a transport when there is no object currently uses the transport.
866
 
 * This function is normally called internally by transport manager or the
867
 
 * transport itself. Application should use #pjsip_transport_shutdown()
868
 
 * instead.
869
 
 *
870
 
 * @param tp            The transport instance.
871
 
 *
872
 
 * @return              PJ_SUCCESS on success or the appropriate error code.
873
 
 *                      Some of possible errors are PJSIP_EBUSY if the
874
 
 *                      transport's reference counter is not zero.
875
 
 */
876
 
PJ_DECL(pj_status_t) pjsip_transport_destroy( pjsip_transport *tp);
877
 
 
878
 
/**
879
 
 * Add reference counter to the specified transport. Any objects that wishes
880
 
 * to keep the reference of the transport MUST increment the transport's
881
 
 * reference counter to prevent it from being destroyed.
882
 
 *
883
 
 * @param tp            The transport instance.
884
 
 *
885
 
 * @return              PJ_SUCCESS on success or the appropriate error code.
886
 
 */
887
 
PJ_DECL(pj_status_t) pjsip_transport_add_ref( pjsip_transport *tp );
888
 
 
889
 
/**
890
 
 * Decrement reference counter of the specified transport. When an object no
891
 
 * longer want to keep the reference to the transport, it must decrement the
892
 
 * reference counter. When the reference counter of the transport reaches
893
 
 * zero, the transport manager will start the idle timer to destroy the
894
 
 * transport if no objects acquire the reference counter during the idle
895
 
 * interval.
896
 
 *
897
 
 * @param tp            The transport instance.
898
 
 *
899
 
 * @return              PJ_SUCCESS on success.
900
 
 */
901
 
PJ_DECL(pj_status_t) pjsip_transport_dec_ref( pjsip_transport *tp );
902
 
 
903
 
 
904
 
/**
905
 
 * This function is called by transport instances to report an incoming
906
 
 * packet to the transport manager. The transport manager then would try to
907
 
 * parse all SIP messages in the packet, and for each parsed SIP message, it
908
 
 * would report the message to the SIP endpoint (#pjsip_endpoint).
909
 
 *
910
 
 * @param mgr           The transport manager instance.
911
 
 * @param rdata         The receive data buffer containing the packet. The
912
 
 *                      transport MUST fully initialize tp_info and pkt_info
913
 
 *                      member of the rdata.
914
 
 *
915
 
 * @return              The number of bytes successfully processed from the
916
 
 *                      packet. If the transport is datagram oriented, the
917
 
 *                      value will be equal to the size of the packet. For
918
 
 *                      stream oriented transport (e.g. TCP, TLS), the value
919
 
 *                      returned may be less than the packet size, if
920
 
 *                      partial message is received. The transport then MUST
921
 
 *                      keep the remainder part and report it again to
922
 
 *                      this function once more data/packet is received.
923
 
 */
924
 
PJ_DECL(pj_ssize_t) pjsip_tpmgr_receive_packet(pjsip_tpmgr *mgr,
925
 
                                               pjsip_rx_data *rdata);
926
 
 
927
 
 
928
 
/*****************************************************************************
929
 
 *
930
 
 * TRANSPORT FACTORY
931
 
 *
932
 
 *****************************************************************************/
933
 
 
934
 
 
935
 
/**
936
 
 * A transport factory is normally used for connection oriented transports
937
 
 * (such as TCP or TLS) to create instances of transports. It registers
938
 
 * a new transport type to the transport manager, and the transport manager
939
 
 * would ask the factory to create a transport instance when it received
940
 
 * command from application to send a SIP message using the specified
941
 
 * transport type.
942
 
 */
943
 
struct pjsip_tpfactory
944
 
{
945
 
    /** This list is managed by transport manager. */
946
 
    PJ_DECL_LIST_MEMBER(struct pjsip_tpfactory);
947
 
 
948
 
    char                    obj_name[PJ_MAX_OBJ_NAME];  /**< Name.      */
949
 
 
950
 
    pj_pool_t              *pool;           /**< Owned memory pool.     */
951
 
    pj_lock_t              *lock;           /**< Lock object.           */
952
 
 
953
 
    pjsip_transport_type_e  type;           /**< Transport type.        */
954
 
    char                   *type_name;      /**< Type string name.      */
955
 
    unsigned                flag;           /**< Transport flag.        */
956
 
 
957
 
    pj_sockaddr             local_addr;     /**< Bound address.         */
958
 
    pjsip_host_port         addr_name;      /**< Published name.        */
959
 
 
960
 
    /**
961
 
     * Create new outbound connection suitable for sending SIP message
962
 
     * to specified remote address.
963
 
     * Note that the factory is responsible for both creating the
964
 
     * transport and registering it to the transport manager.
965
 
     */
966
 
    pj_status_t (*create_transport)(pjsip_tpfactory *factory,
967
 
                                    pjsip_tpmgr *mgr,
968
 
                                    pjsip_endpoint *endpt,
969
 
                                    const pj_sockaddr *rem_addr,
970
 
                                    int addr_len,
971
 
                                    pjsip_transport **transport);
972
 
 
973
 
    /**
974
 
     * Create new outbound connection suitable for sending SIP message
975
 
     * to specified remote address by also considering outgoing SIP
976
 
     * message data.
977
 
     * Note that the factory is responsible for both creating the
978
 
     * transport and registering it to the transport manager.
979
 
     */
980
 
    pj_status_t (*create_transport2)(pjsip_tpfactory *factory,
981
 
                                     pjsip_tpmgr *mgr,
982
 
                                     pjsip_endpoint *endpt,
983
 
                                     const pj_sockaddr *rem_addr,
984
 
                                     int addr_len,
985
 
                                     pjsip_tx_data *tdata,
986
 
                                     pjsip_transport **transport);
987
 
 
988
 
    /**
989
 
     * Destroy the listener.
990
 
     */
991
 
    pj_status_t (*destroy)(pjsip_tpfactory *factory);
992
 
 
993
 
    /*
994
 
     * Application may extend this structure..
995
 
     */
996
 
};
997
 
 
998
 
 
999
 
 
1000
 
/**
1001
 
 * Register a transport factory.
1002
 
 *
1003
 
 * @param mgr           The transport manager.
1004
 
 * @param tpf           Transport factory.
1005
 
 *
1006
 
 * @return              PJ_SUCCESS if listener was successfully created.
1007
 
 */
1008
 
PJ_DECL(pj_status_t) pjsip_tpmgr_register_tpfactory(pjsip_tpmgr *mgr,
1009
 
                                                    pjsip_tpfactory *tpf);
1010
 
 
1011
 
/**
1012
 
 * Unregister factory.
1013
 
 *
1014
 
 * @param mgr           The transport manager.
1015
 
 * @param tpf           Transport factory.
1016
 
 *
1017
 
 * @return              PJ_SUCCESS is sucessfully unregistered.
1018
 
 */
1019
 
PJ_DECL(pj_status_t) pjsip_tpmgr_unregister_tpfactory(pjsip_tpmgr *mgr,
1020
 
                                                      pjsip_tpfactory *tpf);
1021
 
 
1022
 
 
1023
 
/*****************************************************************************
1024
 
 *
1025
 
 * TRANSPORT MANAGER
1026
 
 *
1027
 
 *****************************************************************************/
1028
 
 
1029
 
/**
1030
 
 * Type of callback to be called when transport manager receives incoming
1031
 
 * SIP message.
1032
 
 *
1033
 
 * @param ep        Endpoint.
1034
 
 * @param status    Receiption status.
1035
 
 * @param rd        Received packet.
1036
 
 */
1037
 
typedef void (*pjsip_rx_callback)(pjsip_endpoint *ep, pj_status_t status,
1038
 
                                  pjsip_rx_data *rd);
1039
 
 
1040
 
/**
1041
 
 * Type of callback to be called before transport manager is about
1042
 
 * to transmit SIP message.
1043
 
 *
1044
 
 * @param ep        Endpoint.
1045
 
 * @param td        Transmit data.
1046
 
 */
1047
 
typedef pj_status_t (*pjsip_tx_callback)(pjsip_endpoint *ep, pjsip_tx_data*td);
1048
 
 
1049
 
/**
1050
 
 * Create a transport manager. Normally application doesn't need to call
1051
 
 * this function directly, since a transport manager will be created and
1052
 
 * destroyed automatically by the SIP endpoint.
1053
 
 *
1054
 
 * @param pool      Pool.
1055
 
 * @param endpt     Endpoint instance.
1056
 
 * @param rx_cb     Callback to receive incoming message.
1057
 
 * @param tx_cb     Callback to be called before transport manager is sending
1058
 
 *                  outgoing message.
1059
 
 * @param p_mgr     Pointer to receive the new transport manager.
1060
 
 *
1061
 
 * @return          PJ_SUCCESS or the appropriate error code on error.
1062
 
 */
1063
 
PJ_DECL(pj_status_t) pjsip_tpmgr_create( pj_pool_t *pool,
1064
 
                                         pjsip_endpoint * endpt,
1065
 
                                         pjsip_rx_callback rx_cb,
1066
 
                                         pjsip_tx_callback tx_cb,
1067
 
                                         pjsip_tpmgr **p_mgr);
1068
 
 
1069
 
 
1070
 
/**
1071
 
 * Find out the appropriate local address info (IP address and port) to
1072
 
 * advertise in Contact header based on the remote address to be
1073
 
 * contacted. The local address info would be the address name of the
1074
 
 * transport or listener which will be used to send the request.
1075
 
 *
1076
 
 * In this implementation, it will only select the transport based on
1077
 
 * the transport type in the request.
1078
 
 *
1079
 
 * @param tpmgr     The transport manager.
1080
 
 * @param pool      Pool to allocate memory for the IP address.
1081
 
 * @param type      Destination address to contact.
1082
 
 * @param sel       Optional pointer to prefered transport, if any.
1083
 
 * @param ip_addr   Pointer to receive the IP address.
1084
 
 * @param port      Pointer to receive the port number.
1085
 
 *
1086
 
 * @return          PJ_SUCCESS, or the appropriate error code.
1087
 
 */
1088
 
PJ_DECL(pj_status_t) pjsip_tpmgr_find_local_addr( pjsip_tpmgr *tpmgr,
1089
 
                                                  pj_pool_t *pool,
1090
 
                                                  pjsip_transport_type_e type,
1091
 
                                                  const pjsip_tpselector *sel,
1092
 
                                                  pj_str_t *ip_addr,
1093
 
                                                  int *port);
1094
 
 
1095
 
/**
1096
 
 * Return number of transports currently registered to the transport
1097
 
 * manager.
1098
 
 *
1099
 
 * @param mgr       The transport manager.
1100
 
 *
1101
 
 * @return          Number of transports.
1102
 
 */
1103
 
PJ_DECL(unsigned) pjsip_tpmgr_get_transport_count(pjsip_tpmgr *mgr);
1104
 
 
1105
 
 
1106
 
/**
1107
 
 * Destroy a transport manager. Normally application doesn't need to call
1108
 
 * this function directly, since a transport manager will be created and
1109
 
 * destroyed automatically by the SIP endpoint.
1110
 
 *
1111
 
 * @param mgr       The transport manager.
1112
 
 *
1113
 
 * @return          PJ_SUCCESS on success.
1114
 
 */
1115
 
PJ_DECL(pj_status_t) pjsip_tpmgr_destroy(pjsip_tpmgr *mgr);
1116
 
 
1117
 
 
1118
 
/**
1119
 
 * Dump transport info and status to log.
1120
 
 *
1121
 
 * @param mgr       The transport manager.
1122
 
 */
1123
 
PJ_DECL(void) pjsip_tpmgr_dump_transports(pjsip_tpmgr *mgr);
1124
 
 
1125
 
 
1126
 
/*****************************************************************************
1127
 
 *
1128
 
 * PUBLIC API
1129
 
 *
1130
 
 *****************************************************************************/
1131
 
 
1132
 
 
1133
 
/**
1134
 
 * Find transport to be used to send message to remote destination. If no
1135
 
 * suitable transport is found, a new one will be created.
1136
 
 *
1137
 
 * This is an internal function since normally application doesn't have access
1138
 
 * to transport manager. Application should use pjsip_endpt_acquire_transport()
1139
 
 * instead.
1140
 
 *
1141
 
 * @param mgr       The transport manager instance.
1142
 
 * @param type      The type of transport to be acquired.
1143
 
 * @param remote    The remote address to send message to.
1144
 
 * @param addr_len  Length of the remote address.
1145
 
 * @param sel       Optional pointer to transport selector instance which is
1146
 
 *                  used to find explicit transport, if required.
1147
 
 * @param tp        Pointer to receive the transport instance, if one is found.
1148
 
 *
1149
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
1150
 
 */
1151
 
PJ_DECL(pj_status_t) pjsip_tpmgr_acquire_transport(pjsip_tpmgr *mgr,
1152
 
                                                   pjsip_transport_type_e type,
1153
 
                                                   const pj_sockaddr_t *remote,
1154
 
                                                   int addr_len,
1155
 
                                                   const pjsip_tpselector *sel,
1156
 
                                                   pjsip_transport **tp);
1157
 
 
1158
 
/**
1159
 
 * Find suitable transport for sending SIP message to specified remote
1160
 
 * destination by also considering the outgoing SIP message. If no suitable
1161
 
 * transport is found, a new one will be created.
1162
 
 *
1163
 
 * This is an internal function since normally application doesn't have access
1164
 
 * to transport manager. Application should use pjsip_endpt_acquire_transport2()
1165
 
 * instead.
1166
 
 *
1167
 
 * @param mgr       The transport manager instance.
1168
 
 * @param type      The type of transport to be acquired.
1169
 
 * @param remote    The remote address to send message to.
1170
 
 * @param addr_len  Length of the remote address.
1171
 
 * @param sel       Optional pointer to transport selector instance which is
1172
 
 *                  used to find explicit transport, if required.
1173
 
 * @param tdata     Optional pointer to data to be sent.
1174
 
 * @param tp        Pointer to receive the transport instance, if one is found.
1175
 
 *
1176
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
1177
 
 */
1178
 
PJ_DECL(pj_status_t) pjsip_tpmgr_acquire_transport2(pjsip_tpmgr *mgr,
1179
 
                                                    pjsip_transport_type_e type,
1180
 
                                                    const pj_sockaddr_t *remote,
1181
 
                                                    int addr_len,
1182
 
                                                    const pjsip_tpselector *sel,
1183
 
                                                    pjsip_tx_data *tdata,
1184
 
                                                    pjsip_transport **tp);
1185
 
 
1186
 
/**
1187
 
 * Type of callback to receive notification when message or raw data
1188
 
 * has been sent.
1189
 
 *
1190
 
 * @param token         The token that was given when calling the function
1191
 
 *                      to send message or raw data.
1192
 
 * @param tdata         The transmit buffer used to send the message.
1193
 
 * @param bytes_sent    Number of bytes sent. On success, the value will be
1194
 
 *                      positive number indicating the number of bytes sent.
1195
 
 *                      On failure, the value will be a negative number of
1196
 
 *                      the error code (i.e. bytes_sent = -status).
1197
 
 */
1198
 
typedef void (*pjsip_tp_send_callback)(void *token, pjsip_tx_data *tdata,
1199
 
                                       pj_ssize_t bytes_sent);
1200
 
 
1201
 
 
1202
 
/**
1203
 
 * This is a low-level function to send a SIP message using the specified
1204
 
 * transport to the specified destination.
1205
 
 *
1206
 
 * @param tr        The SIP transport to be used.
1207
 
 * @param tdata     Transmit data buffer containing SIP message.
1208
 
 * @param addr      Destination address.
1209
 
 * @param addr_len  Length of destination address.
1210
 
 * @param token     Arbitrary token to be returned back to callback.
1211
 
 * @param cb        Optional callback to be called to notify caller about
1212
 
 *                  the completion status of the pending send operation.
1213
 
 *
1214
 
 * @return          If the message has been sent successfully, this function
1215
 
 *                  will return PJ_SUCCESS and the callback will not be
1216
 
 *                  called. If message cannot be sent immediately, this
1217
 
 *                  function will return PJ_EPENDING, and application will
1218
 
 *                  be notified later about the completion via the callback.
1219
 
 *                  Any statuses other than PJ_SUCCESS or PJ_EPENDING
1220
 
 *                  indicates immediate failure, and in this case the
1221
 
 *                  callback will not be called.
1222
 
 */
1223
 
PJ_DECL(pj_status_t) pjsip_transport_send( pjsip_transport *tr,
1224
 
                                           pjsip_tx_data *tdata,
1225
 
                                           const pj_sockaddr_t *addr,
1226
 
                                           int addr_len,
1227
 
                                           void *token,
1228
 
                                           pjsip_tp_send_callback cb);
1229
 
 
1230
 
 
1231
 
/**
1232
 
 * This is a low-level function to send raw data to a destination.
1233
 
 *
1234
 
 * See also #pjsip_endpt_send_raw() and #pjsip_endpt_send_raw_to_uri().
1235
 
 *
1236
 
 * @param mgr       Transport manager.
1237
 
 * @param tp_type   Transport type.
1238
 
 * @param sel       Optional pointer to transport selector instance if
1239
 
 *                  application wants to use a specific transport instance
1240
 
 *                  rather then letting transport manager finds the suitable
1241
 
 *                  transport.
1242
 
 * @param tdata     Optional transmit data buffer to be used. If this value
1243
 
 *                  is NULL, this function will create one internally. If
1244
 
 *                  tdata is specified, this function will decrement the
1245
 
 *                  reference counter upon completion.
1246
 
 * @param raw_data  The data to be sent.
1247
 
 * @param data_len  The length of the data.
1248
 
 * @param addr      Destination address.
1249
 
 * @param addr_len  Length of destination address.
1250
 
 * @param token     Arbitrary token to be returned back to callback.
1251
 
 * @param cb        Optional callback to be called to notify caller about
1252
 
 *                  the completion status of the pending send operation.
1253
 
 *
1254
 
 * @return          If the message has been sent successfully, this function
1255
 
 *                  will return PJ_SUCCESS and the callback will not be
1256
 
 *                  called. If message cannot be sent immediately, this
1257
 
 *                  function will return PJ_EPENDING, and application will
1258
 
 *                  be notified later about the completion via the callback.
1259
 
 *                  Any statuses other than PJ_SUCCESS or PJ_EPENDING
1260
 
 *                  indicates immediate failure, and in this case the
1261
 
 *                  callback will not be called.
1262
 
 */
1263
 
PJ_DECL(pj_status_t) pjsip_tpmgr_send_raw(pjsip_tpmgr *mgr,
1264
 
                                          pjsip_transport_type_e tp_type,
1265
 
                                          const pjsip_tpselector *sel,
1266
 
                                          pjsip_tx_data *tdata,
1267
 
                                          const void *raw_data,
1268
 
                                          pj_size_t data_len,
1269
 
                                          const pj_sockaddr_t *addr,
1270
 
                                          int addr_len,
1271
 
                                          void *token,
1272
 
                                          pjsip_tp_send_callback cb);
1273
 
 
1274
 
 
1275
 
/**
1276
 
 * Enumeration of transport state types.
1277
 
 */
1278
 
typedef enum pjsip_transport_state
1279
 
{
1280
 
    PJSIP_TP_STATE_CONNECTED,       /**< Transport connected, applicable only
1281
 
                                         to connection-oriented transports
1282
 
                                         such as TCP and TLS.               */
1283
 
    PJSIP_TP_STATE_DISCONNECTED     /**< Transport disconnected, applicable
1284
 
                                         only to connection-oriented
1285
 
                                         transports such as TCP and TLS.    */
1286
 
} pjsip_transport_state;
1287
 
 
1288
 
 
1289
 
/**
1290
 
 * Definition of transport state listener key.
1291
 
 */
1292
 
typedef void pjsip_tp_state_listener_key;
1293
 
 
1294
 
/**
1295
 
 * Structure of transport state info passed by #pjsip_tp_state_callback.
1296
 
 */
1297
 
typedef struct pjsip_transport_state_info {
1298
 
    /**
1299
 
     * The last error code related to the transport state.
1300
 
     */
1301
 
    pj_status_t          status;
1302
 
 
1303
 
    /**
1304
 
     * Optional extended info, the content is specific for each transport type.
1305
 
     */
1306
 
    void                *ext_info;
1307
 
 
1308
 
    /**
1309
 
     * Optional user data. In global transport state notification, this will
1310
 
     * always be NULL.
1311
 
     */
1312
 
    void                *user_data;
1313
 
 
1314
 
} pjsip_transport_state_info;
1315
 
 
1316
 
 
1317
 
/**
1318
 
 * Type of callback to receive transport state notifications, such as
1319
 
 * transport connected/disconnected. Application may shutdown the transport
1320
 
 * in this callback.
1321
 
 *
1322
 
 * @param tp            The transport instance.
1323
 
 * @param state         The transport state.
1324
 
 * @param info          The transport state info.
1325
 
 */
1326
 
typedef void (*pjsip_tp_state_callback)(
1327
 
                                    pjsip_transport *tp,
1328
 
                                    pjsip_transport_state state,
1329
 
                                    const pjsip_transport_state_info *info);
1330
 
 
1331
 
 
1332
 
/**
1333
 
 * Set callback of global transport state notification. The caller will be
1334
 
 * notified whenever the state of any transport is changed. The type of events
1335
 
 * are defined in #pjsip_transport_state.
1336
 
 *
1337
 
 * Note that this function will override the existing callback, if any, so
1338
 
 * application is recommended to keep the old callback and manually forward
1339
 
 * the notification to the old callback, otherwise other component that
1340
 
 * concerns about the transport state will no longer receive transport state
1341
 
 * events.
1342
 
 *
1343
 
 * @param mgr       Transport manager.
1344
 
 * @param cb        Callback to be called to notify caller about transport
1345
 
 *                  state changing.
1346
 
 *
1347
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
1348
 
 */
1349
 
PJ_DECL(pj_status_t) pjsip_tpmgr_set_state_cb(pjsip_tpmgr *mgr,
1350
 
                                              pjsip_tp_state_callback cb);
1351
 
 
1352
 
 
1353
 
/**
1354
 
 * Get the callback of global transport state notification.
1355
 
 *
1356
 
 * @param mgr       Transport manager.
1357
 
 *
1358
 
 * @return          The transport state callback or NULL if it is not set.
1359
 
 */
1360
 
PJ_DECL(pjsip_tp_state_callback) pjsip_tpmgr_get_state_cb(
1361
 
                                              const pjsip_tpmgr *mgr);
1362
 
 
1363
 
 
1364
 
/**
1365
 
 * Add a listener to the specified transport for transport state notification.
1366
 
 *
1367
 
 * @param tp        The transport.
1368
 
 * @param cb        Callback to be called to notify listener about transport
1369
 
 *                  state changing.
1370
 
 * @param user_data The user data.
1371
 
 * @param key       Output key, used to remove this listener.
1372
 
 *
1373
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
1374
 
 */
1375
 
PJ_DECL(pj_status_t) pjsip_transport_add_state_listener (
1376
 
                                            pjsip_transport *tp,
1377
 
                                            pjsip_tp_state_callback cb,
1378
 
                                            void *user_data,
1379
 
                                            pjsip_tp_state_listener_key **key);
1380
 
 
1381
 
 
1382
 
/**
1383
 
 * Remove a listener from the specified transport for transport state
1384
 
 * notification.
1385
 
 *
1386
 
 * @param tp        The transport.
1387
 
 * @param key       The listener key.
1388
 
 * @param user_data The user data, for validation purpose.
1389
 
 *
1390
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
1391
 
 */
1392
 
PJ_DECL(pj_status_t) pjsip_transport_remove_state_listener (
1393
 
                                    pjsip_transport *tp,
1394
 
                                    pjsip_tp_state_listener_key *key,
1395
 
                                    const void *user_data);
1396
 
 
1397
 
 
1398
 
/**
1399
 
 * @}
1400
 
 */
1401
 
 
1402
 
 
1403
 
PJ_END_DECL
1404
 
 
1405
 
#endif  /* __PJSIP_SIP_TRANSPORT_H__ */