stun.h 8.47 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2 3
/*
 * This file is part of the Sofia-SIP package
 *
4
 * Copyright (C) 2005-2006 Nokia Corporation.
Pekka Pessi's avatar
Pekka Pessi committed
5 6 7
 *
 * Contact: Pekka Pessi <pekka.pessi@nokia.com>
 *
8
 * This library is free software; you can redistribute it and/or
Pekka Pessi's avatar
Pekka Pessi committed
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 *
 */

#ifndef STUN_H /** Defined when stun.h has been included. */
Pekka Pessi's avatar
Pekka Pessi committed
26
#define STUN_H
27 28

/**@file stun.h STUN module public interface
Pekka Pessi's avatar
Pekka Pessi committed
29 30
 *
 * @author Tat Chan <Tat.Chan@nokia.com>
31
 * @author Martti Mela <Martti.Mela@nokia.com>
Pekka Pessi's avatar
Pekka Pessi committed
32
 * @author Pekka Pessi <Pekka.Pessi@nokia.com>
33
 * @author Kai Vehmanen <kai.vehmanen@nokia.com>
Pekka Pessi's avatar
Pekka Pessi committed
34 35
 */

36
#ifndef SU_WAIT_H
37
#include <sofia-sip/su_wait.h>
38 39
#endif
#ifndef SU_TAG_H
40
#include <sofia-sip/su_tag.h>
41
#endif
42
#include "sofia-sip/stun_common.h"
Pekka Pessi's avatar
Pekka Pessi committed
43

44
#include <sofia-sip/su_localinfo.h>
Martti Mela's avatar
Martti Mela committed
45

46 47
SOFIA_BEGIN_DECLS

48 49 50 51
typedef struct stun_handle_s     stun_handle_t;
typedef struct stun_request_s    stun_request_t;
typedef struct stun_discovery_s  stun_discovery_t;
typedef struct stun_dns_lookup_s stun_dns_lookup_t;
Pekka Pessi's avatar
Pekka Pessi committed
52

53 54 55 56 57 58
#ifndef STUN_MAGIC_T 
#define STUN_MAGIC_T            struct stun_magic_t
#endif
/** STUN server context */
typedef STUN_MAGIC_T stun_magic_t;

59 60 61 62 63 64
#ifndef STUN_DISCOVERY_MAGIC_T 
#define STUN_DISCOVERY_MAGIC_T            struct stun_discovery_magic_t
#endif
/** STUN discovery_ context */
typedef STUN_DISCOVERY_MAGIC_T stun_discovery_magic_t;

Pekka Pessi's avatar
Pekka Pessi committed
65 66
extern char const stun_version[]; /**< Name and version of STUN software */

67 68 69 70 71
/**
 * STUN Action types. These define the current discovery process.
 */
typedef enum stun_action_s {
  stun_action_no_action,
72
  stun_action_tls_query,
73 74 75 76 77 78
  stun_action_binding_request,
  stun_action_keepalive,
  stun_action_get_nattype,
  stun_action_get_lifetime,
} stun_action_t;

79 80 81
/**
 * States of the STUN client->server query process.
 */ 
82
typedef enum stun_state_e {
83 84
  
  stun_no_assigned_event,
85
  stun_dispose_me,
86

Martti Mela's avatar
Martti Mela committed
87 88 89 90 91 92 93 94
  /* TLS events */
  stun_tls_connecting,
  stun_tls_ssl_connecting,
  stun_tls_writing,
  stun_tls_closing,
  stun_tls_reading,
  stun_tls_done,

95 96 97 98 99
  /* STUN discovery events */
  stun_discovery_init,
  stun_discovery_processing,
  stun_discovery_done,

Martti Mela's avatar
Martti Mela committed
100 101 102 103 104
  /* STUN bind events */
  stun_bind_init,             /**< Initial state */
  stun_bind_processing,       /**< Processing server reply */
  stun_bind_done,             /**< Initial state */

105 106
  stun_request_not_found,     /**< Response without matching request */

Martti Mela's avatar
Martti Mela committed
107
  /* STUN errors */
108
  /* Do not change the order! Errors need to be after stun_error */
Martti Mela's avatar
Martti Mela committed
109 110 111 112 113

  stun_error,
  stun_tls_connection_timeout,
  stun_tls_connection_failed,
  stun_tls_ssl_connect_failed,
114 115

  /* stun client errors */
Martti Mela's avatar
Martti Mela committed
116 117
  stun_bind_error,
  stun_bind_timeout,
118

119
  stun_request_timeout,
120 121 122
  stun_discovery_timeout,

} stun_state_t;
123

124 125 126
/* -------------------------------------------------------------------
 * Calback function prototypes (signals emitted by the stack) */

127 128 129 130 131 132 133 134 135
/* Per discovery */
typedef void (*stun_discovery_f)(stun_discovery_magic_t *magic,
				 stun_handle_t *sh,
				 stun_request_t *req,
				 stun_discovery_t *sd,
				 stun_action_t action,
				 stun_state_t event);

/* Used if no stun_discovery_f specified for a discovery  */
Martti Mela's avatar
Martti Mela committed
136
typedef void (*stun_event_f)(stun_magic_t *magic,
137
			     stun_handle_t *sh,
138
			     stun_request_t *req,
139 140
			     stun_discovery_t *sd,
			     stun_action_t action,
141
			     stun_state_t event);
Martti Mela's avatar
Martti Mela committed
142

143 144
/** Callback invoked by stun handle when it has a message to send. */
typedef int (*stun_send_callback)(stun_magic_t *magic,
145
				  stun_handle_t *sh,
146 147 148 149 150
				  int socket,
				  void *data,
				  unsigned len,
				  int only_a_keepalive);

151 152 153 154
/** Callback for delivering DNS lookup results */
typedef void (*stun_dns_lookup_f)(stun_dns_lookup_t *self,
				  stun_magic_t *magic);

155 156
/* -------------------------------------------------------------------
 * Functions for managing STUN handles. */
Pekka Pessi's avatar
Pekka Pessi committed
157

158 159 160 161
char const *stun_str_state(stun_state_t state);

/** Check if a STUN handle should be created. */

Martti Mela's avatar
Martti Mela committed
162
stun_handle_t *stun_handle_create(stun_magic_t *context,
163
				  su_root_t *root,
164
				  stun_event_f cb,
Pekka Pessi's avatar
Pekka Pessi committed
165
				  tag_type_t tag, tag_value_t value, ...); 
166
int stun_handle_release(stun_handle_t *sh, su_socket_t s);
167
void stun_handle_destroy(stun_handle_t *sh);
168 169

su_root_t *stun_root(stun_handle_t *sh);
170
int stun_is_requested(tag_type_t tag, tag_value_t value, ...);
Pekka Pessi's avatar
Pekka Pessi committed
171

172 173
/* ------------------------------------------------------------------- 
 * Functions for 'Binding Discovery' usage (RFC3489bis) */
174
int stun_request_shared_secret(stun_handle_t *sh);
Pekka Pessi's avatar
Pekka Pessi committed
175

176 177 178 179 180 181 182 183 184
/** Bind a socket using STUN.  */
int stun_bind(stun_handle_t *sh, 
	      stun_discovery_f,
	      stun_discovery_magic_t *magic,
	      /* su_localinfo_t *my_addr, */
	      tag_type_t tag, tag_value_t value,
	      ...);

int stun_get_nattype(stun_handle_t *sh,
185 186
		     stun_discovery_f,
		     stun_discovery_magic_t *magic,
187 188
		     tag_type_t tag, tag_value_t value,
		     ...);
Pekka Pessi's avatar
Pekka Pessi committed
189

Pekka Pessi's avatar
Pekka Pessi committed
190
char const *stun_nattype(stun_discovery_t *sd);
191 192 193
su_sockaddr_t *stun_discovery_get_address(stun_discovery_t *sd);
su_socket_t stun_discovery_get_socket(stun_discovery_t *sd);

194 195 196 197 198
int stun_get_lifetime(stun_handle_t *sh,
		      stun_discovery_f,
		      stun_discovery_magic_t *magic,
		      tag_type_t tag, tag_value_t value,
		      ...);
Pekka Pessi's avatar
Pekka Pessi committed
199

Pekka Pessi's avatar
Pekka Pessi committed
200 201
int stun_lifetime(stun_discovery_t *sd);

202 203
/* ------------------------------------------------------------------- 
 * Functions for 'Connectivity Check' and 'NAT Keepalives' usages (RFC3489bis) */
204 205 206 207 208 209
/* other functions */
int stun_set_uname_pwd(stun_handle_t *sh,
		       const char *uname,
		       int len_uname, 
		       const char *pwd,
		       int len_pwd);
Pekka Pessi's avatar
Pekka Pessi committed
210

Martti Mela's avatar
Martti Mela committed
211
int stun_msg_is_keepalive(uint16_t data);
212
int stun_message_length(void *data, int len, int end_of_message);
213 214 215 216 217 218 219 220 221 222 223 224

/** Process incoming message */
int stun_process_message(stun_handle_t *sh, su_socket_t s,
			 su_sockaddr_t *sa, socklen_t salen,
			 void *data, int len);

int stun_process_request(su_socket_t s, stun_msg_t *req,
			 int sid, su_sockaddr_t *from_addr,
			 int from_len);

/* Create a keepalive dispatcher for bound SIP sockets */

225
int stun_keepalive(stun_handle_t *sh,
Martti Mela's avatar
Martti Mela committed
226
		   su_sockaddr_t *sa,
227 228 229 230
		   tag_type_t tag, tag_value_t value,
		   ...);
int stun_keepalive_destroy(stun_handle_t *sh, su_socket_t s);

231 232 233
/* -------------------------------------------------------------------
 * Functions for 'Short-Term password' usage (RFC3489bis) */

234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268
/* Return socket attached to discovery object */
su_socket_t stun_discovery_get_socket(stun_discovery_t *sd);



/*********************************************************/
/* Deprecated functions. These are supported with limited
   compatibility. */

su_root_t *stun_handle_root(stun_handle_t *sh);
int stun_handle_request_shared_secret(stun_handle_t *sh);

/** Bind a socket using STUN.  */
int stun_handle_bind(stun_handle_t *sh, 
		     /* su_localinfo_t *my_addr, */
		     tag_type_t tag, tag_value_t value,
		     ...);
int stun_handle_get_nattype(stun_handle_t *sh,
			    tag_type_t tag, tag_value_t value,
			    ...);
int stun_handle_get_lifetime(stun_handle_t *sh,
			     tag_type_t tag, tag_value_t value,
			     ...);
int stun_handle_set_uname_pwd(stun_handle_t *sh,
			      const char *uname,
			      int len_uname, 
			      const char *pwd,
			      int len_pwd);

int stun_handle_process_message(stun_handle_t *sh,
				su_socket_t s,
				su_sockaddr_t *sa,
				socklen_t salen,
				void *data,
				int len);
269 270 271 272 273 274
int stun_handle_request_shared_secret(stun_handle_t *sh);
int stun_handle_set_uname_pwd(stun_handle_t *sh,
			      const char *uname,
			      int len_uname, 
			      const char *pwd,
			      int len_pwd);
275

276 277 278 279 280 281 282 283 284 285 286 287 288
/* -------------------------------------------------------------------
 * Functions for STUN server discovery using DNS (RFC3489/3489bis) */

stun_dns_lookup_t *stun_dns_lookup(stun_magic_t *magic, 
				   su_root_t *root,
				   stun_dns_lookup_f func, 
				   const char *domain);
int stun_dns_lookup_get_results(stun_dns_lookup_t *self, 
				const char **tls_target,
				uint16_t *tls_port,
				const char **udp_target,
				uint16_t *udp_port);
void stun_dns_lookup_destroy(stun_dns_lookup_t *self);
289

290 291
SOFIA_END_DECLS

Pekka Pessi's avatar
Pekka Pessi committed
292
#endif /* !defined(STUN_H) */