stun  1.12.11
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) */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

Sofia-SIP 1.12.11 - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.