sofia-sip/stun.h
Go to the documentation of this file.
00001 /* 00002 * This file is part of the Sofia-SIP package 00003 * 00004 * Copyright (C) 2005-2006 Nokia Corporation. 00005 * 00006 * Contact: Pekka Pessi <pekka.pessi@nokia-email.address.hidden> 00007 * 00008 * This library is free software; you can redistribute it and/or 00009 * modify it under the terms of the GNU Lesser General Public License 00010 * as published by the Free Software Foundation; either version 2.1 of 00011 * the License, or (at your option) any later version. 00012 * 00013 * This library is distributed in the hope that it will be useful, but 00014 * WITHOUT ANY WARRANTY; without even the implied warranty of 00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00016 * Lesser General Public License for more details. 00017 * 00018 * You should have received a copy of the GNU Lesser General Public 00019 * License along with this library; if not, write to the Free Software 00020 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 00021 * 02110-1301 USA 00022 * 00023 */ 00024 00025 #ifndef STUN_H 00026 00027 #define STUN_H 00028 00037 #include <sofia-sip/stun_common.h> 00038 00039 #ifndef SU_WAIT_H 00040 #include <sofia-sip/su_wait.h> 00041 #endif 00042 00043 #ifndef SU_TAG_H 00044 #include <sofia-sip/su_tag.h> 00045 #endif 00046 00047 #include <sofia-sip/su_localinfo.h> 00048 00049 00050 SOFIA_BEGIN_DECLS 00051 00052 typedef struct stun_handle_s stun_handle_t; 00053 typedef struct stun_request_s stun_request_t; 00054 typedef struct stun_discovery_s stun_discovery_t; 00055 typedef struct stun_dns_lookup_s stun_dns_lookup_t; 00056 00057 typedef struct stun_mini_s stun_mini_t; 00058 00059 #ifndef STUN_MAGIC_T 00060 #define STUN_MAGIC_T struct stun_magic_t 00061 #endif 00062 00063 typedef STUN_MAGIC_T stun_magic_t; 00064 00065 #ifndef STUN_DISCOVERY_MAGIC_T 00066 #define STUN_DISCOVERY_MAGIC_T struct stun_discovery_magic_t 00067 #endif 00068 00069 typedef STUN_DISCOVERY_MAGIC_T stun_discovery_magic_t; 00070 00072 SOFIAPUBVAR char const stun_version[]; 00073 00078 typedef enum stun_action_s { 00079 stun_action_no_action = 1, 00080 stun_action_tls_query = 2, 00081 stun_action_binding_request = 4, 00082 stun_action_keepalive = 8, 00083 stun_action_test_nattype = 16, 00084 stun_action_test_lifetime = 32, 00085 } stun_action_t; 00086 00097 typedef enum stun_nattype_e { 00098 stun_nat_unknown = 0, 00099 00100 /* no NAT between client and STUN server */ 00101 stun_open_internet, 00102 00103 /* UDP communication blocked by FW */ 00104 stun_udp_blocked, 00105 00106 /* No NAT, but a FW element is performing address and port 00107 * restricted filtering. */ 00108 stun_sym_udp_fw, 00109 00110 /* Endpoint independent filtering (endpoint independent mapping) 00111 * RFC3489 full cone NAT. */ 00112 stun_nat_full_cone, 00113 00114 /* Address restricted filtering (endpoint independent mapping), 00115 * RFC3489 restricted cone NAT. */ 00116 stun_nat_res_cone, 00117 00118 /* Address and port restricted filtering (endpoint 00119 * independent mapping), RFC3489 port restricted cone */ 00120 stun_nat_port_res_cone, 00121 00122 /* Endpoint independent filtering, endpoint dependent mapping. */ 00123 stun_nat_ei_filt_ad_map, 00124 00125 /* Address dependent filtering, endpoint dependent mapping. */ 00126 stun_nat_ad_filt_ad_map, 00127 00128 /* Address and port dependent filtering, endpoint dependent mapping 00129 * RFC3489 symmetric NAT). */ 00130 stun_nat_adp_filt_ad_map, 00131 00132 } stun_nattype_t; 00133 00142 typedef enum stun_state_e { 00143 00144 stun_no_assigned_event, 00145 00146 /* TLS events; see stun_obtain_shared_request() */ 00147 stun_tls_connecting, 00148 stun_tls_ssl_connecting, 00149 stun_tls_writing, 00150 stun_tls_closing, 00151 stun_tls_reading, 00152 stun_tls_done, 00154 /* STUN discovery events */ 00155 stun_discovery_done, 00157 /* STUN errors */ 00158 /* Do not change the order! Errors need to be after stun_error */ 00159 00160 stun_error, 00161 stun_tls_connection_timeout, 00162 stun_tls_connection_failed, 00163 stun_tls_ssl_connect_failed, 00165 stun_discovery_error, 00166 stun_discovery_timeout, 00168 } stun_state_t; 00169 00170 /* ------------------------------------------------------------------- 00171 * Calback function prototypes (signals emitted by the stack) */ 00172 00173 /* Per discovery */ 00174 typedef void (*stun_discovery_f)(stun_discovery_magic_t *magic, 00175 stun_handle_t *sh, 00176 stun_discovery_t *sd, 00177 stun_action_t action, 00178 stun_state_t event); 00179 00181 typedef int (*stun_send_callback)(stun_magic_t *magic, 00182 stun_handle_t *sh, 00183 int socket, 00184 void *data, 00185 unsigned len, 00186 int only_a_keepalive); 00187 00189 typedef void (*stun_dns_lookup_f)(stun_dns_lookup_t *self, 00190 stun_magic_t *magic); 00191 00192 /* ------------------------------------------------------------------- 00193 * Functions for managing STUN handles. */ 00194 00195 SOFIAPUBFUN stun_handle_t *stun_handle_init(su_root_t *root, 00196 tag_type_t, tag_value_t, ...); 00197 00198 SOFIAPUBFUN void stun_handle_destroy(stun_handle_t *sh); 00199 00200 SOFIAPUBFUN su_root_t *stun_root(stun_handle_t *sh); 00201 SOFIAPUBFUN int stun_is_requested(tag_type_t tag, tag_value_t value, ...); 00202 SOFIAPUBFUN char const *stun_str_state(stun_state_t state); 00203 SOFIAPUBFUN su_addrinfo_t const *stun_server_address(stun_handle_t *sh); 00204 00205 SOFIAPUBFUN 00206 int stun_process_message(stun_handle_t *sh, su_socket_t s, 00207 su_sockaddr_t *sa, socklen_t salen, 00208 void *data, isize_t len); 00209 SOFIAPUBFUN 00210 int stun_process_request(su_socket_t s, stun_msg_t *req, 00211 int sid, su_sockaddr_t *from_addr, 00212 socklen_t from_len); 00213 00214 /* ------------------------------------------------------------------- 00215 * Functions for 'Binding Discovery' usage (RFC3489/3489bis) */ 00216 00217 SOFIAPUBFUN 00218 int stun_obtain_shared_secret(stun_handle_t *sh, stun_discovery_f, 00219 stun_discovery_magic_t *magic, 00220 tag_type_t tag, tag_value_t value, ...); 00221 00222 SOFIAPUBFUN 00223 int stun_bind(stun_handle_t *sh, 00224 stun_discovery_f, stun_discovery_magic_t *magic, 00225 tag_type_t tag, tag_value_t value, ...); 00226 00227 SOFIAPUBFUN 00228 int stun_discovery_get_address(stun_discovery_t *sd, 00229 void *addr, 00230 socklen_t *return_addrlen); 00231 SOFIAPUBFUN su_socket_t stun_discovery_get_socket(stun_discovery_t *sd); 00232 SOFIAPUBFUN int stun_discovery_release_socket(stun_discovery_t *sd); 00233 00234 SOFIAPUBFUN 00235 int stun_test_nattype(stun_handle_t *sh, 00236 stun_discovery_f, stun_discovery_magic_t *magic, 00237 tag_type_t tag, tag_value_t value, ...); 00238 SOFIAPUBFUN char const *stun_nattype_str(stun_discovery_t *sd); 00239 SOFIAPUBFUN stun_nattype_t stun_nattype(stun_discovery_t *sd); 00240 00241 SOFIAPUBFUN 00242 int stun_test_lifetime(stun_handle_t *sh, 00243 stun_discovery_f, stun_discovery_magic_t *magic, 00244 tag_type_t tag, tag_value_t value, ...); 00245 SOFIAPUBFUN int stun_lifetime(stun_discovery_t *sd); 00246 00247 /* ------------------------------------------------------------------- 00248 * Functions for 'Connectivity Check' and 'NAT Keepalives' usages (RFC3489bis) */ 00249 00250 SOFIAPUBFUN 00251 int stun_set_uname_pwd(stun_handle_t *sh, 00252 const char *uname, 00253 isize_t len_uname, 00254 const char *pwd, 00255 isize_t len_pwd); 00256 00257 SOFIAPUBFUN int stun_msg_is_keepalive(uint16_t data); 00258 SOFIAPUBFUN int stun_message_length(void *data, isize_t len, int end_of_message); 00259 00260 /* Create a keepalive dispatcher for bound SIP sockets */ 00261 00262 SOFIAPUBFUN 00263 int stun_keepalive(stun_handle_t *sh, 00264 su_sockaddr_t *sa, 00265 tag_type_t tag, tag_value_t value, 00266 ...); 00267 SOFIAPUBFUN int stun_keepalive_destroy(stun_handle_t *sh, su_socket_t s); 00268 00269 /* ------------------------------------------------------------------- 00270 * Functions for 'Short-Term password' usage (RFC3489bis) */ 00271 00272 /* (not implemented, see stun_request_shared_secret()) */ 00273 00274 /* ------------------------------------------------------------------- 00275 * Functions for STUN server discovery using DNS (RFC3489/3489bis) */ 00276 00277 SOFIAPUBFUN 00278 stun_dns_lookup_t *stun_dns_lookup(stun_magic_t *magic, 00279 su_root_t *root, 00280 stun_dns_lookup_f func, 00281 const char *domain); 00282 SOFIAPUBFUN void stun_dns_lookup_destroy(stun_dns_lookup_t *self); 00283 00284 SOFIAPUBFUN int stun_dns_lookup_udp_addr(stun_dns_lookup_t *, 00285 const char **target, uint16_t *port); 00286 SOFIAPUBFUN int stun_dns_lookup_tcp_addr(stun_dns_lookup_t *self, 00287 const char **target, uint16_t *port); 00288 SOFIAPUBFUN int stun_dns_lookup_stp_addr(stun_dns_lookup_t *self, 00289 const char **target, uint16_t *port); 00290 00291 /* ------------------------------------------------------------------- 00292 * Functions for minimal STUN server */ 00293 00294 SOFIAPUBFUN stun_mini_t *stun_mini_create(void); 00295 SOFIAPUBFUN void stun_mini_destroy(stun_mini_t *); 00296 00297 SOFIAPUBFUN int stun_mini_add_socket(stun_mini_t *server, 00298 su_socket_t socket); 00299 SOFIAPUBFUN int stun_mini_remove_socket(stun_mini_t *server, 00300 su_socket_t socket); 00301 00302 SOFIAPUBFUN void stun_mini_request(stun_mini_t *server, su_socket_t socket, 00303 void *msg, ssize_t msglen, 00304 void *addr, socklen_t addrlen); 00305 00306 SOFIA_END_DECLS 00307 00308 #endif /* !defined(STUN_H) */