Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjsip / include / pjsip / sip_transport_tcp.h
1 /* $Id$ */
2 /* 
3  * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4  * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
19  */
20 #ifndef __PJSIP_TRANSPORT_TCP_H__
21 #define __PJSIP_TRANSPORT_TCP_H__
22
23 /**
24  * @file sip_transport_tcp.h
25  * @brief SIP TCP Transport.
26  */
27
28 #include <pjsip/sip_transport.h>
29 #include <pj/sock_qos.h>
30
31
32 /* Only declare the API if PJ_HAS_TCP is true */
33 #if defined(PJ_HAS_TCP) && PJ_HAS_TCP!=0
34
35
36 PJ_BEGIN_DECL
37
38 /**
39  * @defgroup PJSIP_TRANSPORT_TCP TCP Transport
40  * @ingroup PJSIP_TRANSPORT
41  * @brief API to create and register TCP transport.
42  * @{
43  * The functions below are used to create TCP transport and register 
44  * the transport to the framework.
45  */
46
47 /**
48  * Settings to be specified when creating the TCP transport. Application 
49  * should initialize this structure with its default values by calling 
50  * pjsip_tcp_transport_cfg_default().
51  */
52 typedef struct pjsip_tcp_transport_cfg
53 {
54     /**
55      * Address family to use. Valid values are pj_AF_INET() and
56      * pj_AF_INET6(). Default is pj_AF_INET().
57      */
58     int                 af;
59
60     /**
61      * Optional address to bind the socket to. Default is to bind to 
62      * PJ_INADDR_ANY and to any available port.
63      */
64     pj_sockaddr         bind_addr;
65
66     /**
67      * Optional published address, which is the address to be
68      * advertised as the address of this SIP transport. 
69      * By default the bound address will be used as the published address.
70      */
71     pjsip_host_port     addr_name;
72
73     /**
74      * Number of simultaneous asynchronous accept() operations to be 
75      * supported. It is recommended that the number here corresponds to 
76      * the number of processors in the system (or the number of SIP
77      * worker threads).
78      *
79      * Default: 1
80      */
81     unsigned           async_cnt;
82
83     /**
84      * QoS traffic type to be set on this transport. When application wants
85      * to apply QoS tagging to the transport, it's preferable to set this
86      * field rather than \a qos_param fields since this is more portable.
87      *
88      * Default is QoS not set.
89      */
90     pj_qos_type         qos_type;
91
92     /**
93      * Set the low level QoS parameters to the transport. This is a lower
94      * level operation than setting the \a qos_type field and may not be
95      * supported on all platforms.
96      *
97      * Default is QoS not set.
98      */
99     pj_qos_params       qos_params;
100
101 } pjsip_tcp_transport_cfg;
102
103
104 /**
105  * Initialize pjsip_tcp_transport_cfg structure with default values for
106  * the specifed address family.
107  *
108  * @param cfg           The structure to initialize.
109  * @param af            Address family to be used.
110  */
111 PJ_DECL(void) pjsip_tcp_transport_cfg_default(pjsip_tcp_transport_cfg *cfg,
112                                               int af);
113
114
115 /**
116  * Register support for SIP TCP transport by creating TCP listener on
117  * the specified address and port. This function will create an
118  * instance of SIP TCP transport factory and register it to the
119  * transport manager.
120  *
121  * @param endpt         The SIP endpoint.
122  * @param local         Optional local address to bind, or specify the
123  *                      address to bind the server socket to. Both IP 
124  *                      interface address and port fields are optional.
125  *                      If IP interface address is not specified, socket
126  *                      will be bound to PJ_INADDR_ANY. If port is not
127  *                      specified, socket will be bound to any port
128  *                      selected by the operating system.
129  * @param async_cnt     Number of simultaneous asynchronous accept()
130  *                      operations to be supported. It is recommended that
131  *                      the number here corresponds to the number of
132  *                      processors in the system (or the number of SIP
133  *                      worker threads).
134  * @param p_factory     Optional pointer to receive the instance of the
135  *                      SIP TCP transport factory just created.
136  *
137  * @return              PJ_SUCCESS when the transport has been successfully
138  *                      started and registered to transport manager, or
139  *                      the appropriate error code.
140  */
141 PJ_DECL(pj_status_t) pjsip_tcp_transport_start(pjsip_endpoint *endpt,
142                                                const pj_sockaddr_in *local,
143                                                unsigned async_cnt,
144                                                pjsip_tpfactory **p_factory);
145
146
147
148 /**
149  * A newer variant of #pjsip_tcp_transport_start(), which allows specifying
150  * the published/public address of the TCP transport.
151  *
152  * @param endpt         The SIP endpoint.
153  * @param local         Optional local address to bind, or specify the
154  *                      address to bind the server socket to. Both IP 
155  *                      interface address and port fields are optional.
156  *                      If IP interface address is not specified, socket
157  *                      will be bound to PJ_INADDR_ANY. If port is not
158  *                      specified, socket will be bound to any port
159  *                      selected by the operating system.
160  * @param a_name        Optional published address, which is the address to be
161  *                      advertised as the address of this SIP transport. 
162  *                      If this argument is NULL, then the bound address
163  *                      will be used as the published address.
164  * @param async_cnt     Number of simultaneous asynchronous accept()
165  *                      operations to be supported. It is recommended that
166  *                      the number here corresponds to the number of
167  *                      processors in the system (or the number of SIP
168  *                      worker threads).
169  * @param p_factory     Optional pointer to receive the instance of the
170  *                      SIP TCP transport factory just created.
171  *
172  * @return              PJ_SUCCESS when the transport has been successfully
173  *                      started and registered to transport manager, or
174  *                      the appropriate error code.
175  */
176 PJ_DECL(pj_status_t) pjsip_tcp_transport_start2(pjsip_endpoint *endpt,
177                                                 const pj_sockaddr_in *local,
178                                                 const pjsip_host_port *a_name,
179                                                 unsigned async_cnt,
180                                                 pjsip_tpfactory **p_factory);
181
182 /**
183  * Another variant of #pjsip_tcp_transport_start().
184  *
185  * @param endpt         The SIP endpoint.
186  * @param cfg           TCP transport settings. Application should initialize
187  *                      this setting with #pjsip_tcp_transport_cfg_default().
188  * @param p_factory     Optional pointer to receive the instance of the
189  *                      SIP TCP transport factory just created.
190  *
191  * @return              PJ_SUCCESS when the transport has been successfully
192  *                      started and registered to transport manager, or
193  *                      the appropriate error code.
194  */
195 PJ_DECL(pj_status_t) pjsip_tcp_transport_start3(
196                                         pjsip_endpoint *endpt,
197                                         const pjsip_tcp_transport_cfg *cfg,
198                                         pjsip_tpfactory **p_factory
199                                         );
200
201
202 PJ_END_DECL
203
204 /**
205  * @}
206  */
207
208 #endif  /* PJ_HAS_TCP */
209
210 #endif  /* __PJSIP_TRANSPORT_TCP_H__ */