sofia-sip/stun.h File Reference


Detailed Description

STUN module public interface.

Author:
Martti Mela <Martti.Mela@nokia-email.address.hidden>

Tat Chan <Tat.Chan@nokia-email.address.hidden>

Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>

Kai Vehmanen <kai.vehmanen@nokia-email.address.hidden>

#include <sofia-sip/su_wait.h>
#include <sofia-sip/su_tag.h>
#include "sofia-sip/stun_common.h"
#include <sofia-sip/su_localinfo.h>

Include dependency graph for stun.h:

Go to the source code of this file.

Typedefs

typedef STUN_MAGIC_T stun_magic_t
 STUN server context.
typedef STUN_DISCOVERY_MAGIC_T stun_discovery_magic_t
 STUN discovery_ context.
typedef enum stun_action_s stun_action_t
 STUN Action types.
typedef enum stun_nattype_e stun_nattype_t
 NAT types.
typedef enum stun_state_e stun_state_t
 States of the STUN client->server query process.
typedef int(*) stun_send_callback (stun_magic_t *magic, stun_handle_t *sh, int socket, void *data, unsigned len, int only_a_keepalive)
 Callback invoked by stun handle when it has a message to send.
typedef void(*) stun_dns_lookup_f (stun_dns_lookup_t *self, stun_magic_t *magic)
 Callback for delivering DNS lookup results.

Enumerations

enum  stun_action_s
 STUN Action types. More...
enum  stun_nattype_e
 NAT types. More...
enum  stun_state_e { ,
  stun_tls_connecting,
  stun_tls_ssl_connecting,
  stun_tls_writing,
  stun_tls_closing,
  stun_tls_reading,
  stun_tls_done,
  stun_discovery_done,
  stun_error,
  stun_tls_connection_timeout,
  stun_tls_connection_failed,
  stun_tls_ssl_connect_failed,
  stun_discovery_error,
  stun_discovery_timeout
}
 States of the STUN client->server query process. More...

Functions

SOFIAPUBFUN stun_handle_t * stun_handle_init (su_root_t *root, tag_type_t, tag_value_t,...)
 Creates a STUN handle.
SOFIAPUBFUN void stun_handle_destroy (stun_handle_t *sh)
 Destroy a STUN client.
SOFIAPUBFUN su_root_tstun_root (stun_handle_t *sh)
 Return su_root_t assigned to stun_handle_t.
SOFIAPUBFUN int stun_is_requested (tag_type_t tag, tag_value_t value,...)
 Check if a STUN handle should be created.
SOFIAPUBFUN int stun_process_message (stun_handle_t *sh, su_socket_t s, su_sockaddr_t *sa, socklen_t salen, void *data, int len)
 Process incoming message.
SOFIAPUBFUN int stun_obtain_shared_secret (stun_handle_t *sh, stun_discovery_f, stun_discovery_magic_t *magic, tag_type_t tag, tag_value_t value,...)
 Performs shared secret request/response processing.
SOFIAPUBFUN int stun_bind (stun_handle_t *sh, stun_discovery_f, stun_discovery_magic_t *magic, tag_type_t tag, tag_value_t value,...)
 Performs a STUN Binding Discovery (see RFC3489/3489bis) process.
SOFIAPUBFUN int stun_discovery_get_address (stun_discovery_t *sd, void *addr, socklen_t *return_addrlen)
 Returns the address of the public binding allocated by the NAT.
SOFIAPUBFUN su_socket_t stun_discovery_get_socket (stun_discovery_t *sd)
 Returns socket attached to the discovery object.
SOFIAPUBFUN int stun_test_nattype (stun_handle_t *sh, stun_discovery_f, stun_discovery_magic_t *magic, tag_type_t tag, tag_value_t value,...)
 Initiates STUN discovery process to find out NAT characteristics.
SOFIAPUBFUN char const * stun_nattype_str (stun_discovery_t *sd)
 Returns the NAT type attached to STUN discovery handle.
SOFIAPUBFUN stun_nattype_t stun_nattype (stun_discovery_t *sd)
 Returns the detected NAT type.
SOFIAPUBFUN int stun_test_lifetime (stun_handle_t *sh, stun_discovery_f, stun_discovery_magic_t *magic, tag_type_t tag, tag_value_t value,...)
 Initiates STUN discovery process to find out NAT binding life-time settings.
SOFIAPUBFUN int stun_set_uname_pwd (stun_handle_t *sh, const char *uname, int len_uname, const char *pwd, int len_pwd)
 other functions
SOFIAPUBFUN int stun_msg_is_keepalive (uint16_t data)
 Determines if the message is STUN message (-1 if not stun).
SOFIAPUBFUN int stun_message_length (void *data, int len, int end_of_message)
 Determines length of STUN message (0 if not stun).
SOFIAPUBFUN int stun_keepalive (stun_handle_t *sh, su_sockaddr_t *sa, tag_type_t tag, tag_value_t value,...)
 Creates a keepalive dispatcher for bound SIP sockets.
SOFIAPUBFUN int stun_keepalive_destroy (stun_handle_t *sh, su_socket_t s)
 Destroys the keepalive dispatcher without touching the socket.
SOFIAPUBFUN stun_dns_lookup_t * stun_dns_lookup (stun_magic_t *magic, su_root_t *root, stun_dns_lookup_f func, const char *domain)
 Performs a DNS-SRV check for STUN 'stun' (tcp) and 'stun' (udp) services for 'domain'.
SOFIAPUBFUN void stun_dns_lookup_destroy (stun_dns_lookup_t *self)
 Destroys the 'self' object created by stun_dns_lookup_destroy().
SOFIAPUBFUN int stun_dns_lookup_udp_addr (stun_dns_lookup_t *, const char **target, uint16_t *port)
 Fetches the results of a completed STUN DNS-SRV lookup for "_stun._udp" service (RFC3489/3489bis).
SOFIAPUBFUN int stun_dns_lookup_tcp_addr (stun_dns_lookup_t *self, const char **target, uint16_t *port)
 Fetches the results of a completed STUN DNS-SRV lookup for "_stun._tcp" service (RFC3489).
SOFIAPUBFUN int stun_dns_lookup_stp_addr (stun_dns_lookup_t *self, const char **target, uint16_t *port)
 Fetches the results of a completed STUN DNS-SRV lookup for "_stun._udp" service (3489bis, "Short-Term Password").
SOFIAPUBFUN stun_mini_t * stun_mini_create (void)
 Create a stun miniserver.
SOFIAPUBFUN void stun_mini_destroy (stun_mini_t *)
 Destroy a stun miniserver.
SOFIAPUBFUN int stun_mini_add_socket (stun_mini_t *server, int socket)
 Add a socket to stun miniserver.
SOFIAPUBFUN int stun_mini_remove_socket (stun_mini_t *server, int socket)
 Remove socket from stun miniserver.

Variables

SOFIAPUBVAR char const stun_version []
 Name and version of STUN software.


Typedef Documentation

typedef enum stun_action_s stun_action_t

STUN Action types.

These define the current discovery process. Defined as a bitmap.

typedef enum stun_nattype_e stun_nattype_t

NAT types.

XXX: should be extended to distinguish between filtering and mapping allocation behaviour (see IETF BEHAVE documents)

Note: the NAT type detection algorithm can fail in case where the NAT behaves in a nondeterministic fashion.

typedef enum stun_state_e stun_state_t

States of the STUN client->server query process.

See also:
stun_bind()

stun_obtain_shared_secret()

stun_test_nattype()

stun_test_lifetime()


Enumeration Type Documentation

enum stun_action_s

STUN Action types.

These define the current discovery process. Defined as a bitmap.

enum stun_nattype_e

NAT types.

XXX: should be extended to distinguish between filtering and mapping allocation behaviour (see IETF BEHAVE documents)

Note: the NAT type detection algorithm can fail in case where the NAT behaves in a nondeterministic fashion.

enum stun_state_e

States of the STUN client->server query process.

See also:
stun_bind()

stun_obtain_shared_secret()

stun_test_nattype()

stun_test_lifetime()

Enumerator:
stun_tls_connecting  Connecting to TLS port.
stun_tls_ssl_connecting  Started the TLS/SSL handshake.
stun_tls_writing  Next step: send request.
stun_tls_closing  Closing TLS connection.
stun_tls_reading  Request send, waiting for response.
stun_tls_done  Shared-secret acquired.
stun_discovery_done  Discovery process done.
stun_error  Generic error in discovery process.
stun_tls_connection_timeout  No response to connect attempt.
stun_tls_connection_failed  No response from TLS/SSL server.
stun_tls_ssl_connect_failed  TLS/SSL handshake failed.
stun_discovery_error  Error in discovery process.
stun_discovery_timeout  No response to discovery request.


Function Documentation

SOFIAPUBFUN int stun_bind ( stun_handle_t *  sh,
stun_discovery_f  sdf,
stun_discovery_magic_t magic,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Performs a STUN Binding Discovery (see RFC3489/3489bis) process.

To integrity protect the discovery process, first call stun_request_shared_secret() on the handle 'sh'.

If STUNTAG_REGISTER_SOCKET() is omitted, or set to false, the client is responsible for socket i/o. Other stun module will perform the whole discovery process and return the results via callback 'sdf'.

Parameters:
sh pointer to valid stun handle
sdf callback to signal process progress
magic context pointer attached to 'sdf'
Related Tags:
STUNTAG_SOCKET Bind socket for STUN (socket handle).
STUNTAG_REGISTER_SOCKET Register socket for eventloop owned by STUN (boolean)
Returns:
On success, zero is returned. Upon error, -1 is returned, and errno is set appropriately.
Errors:
EFAULT An invalid address is given as argument
EPROTONOSUPPORT Not a UDP socket.
EINVAL The socket is already bound to an address.
EACCESS The address is protected, and the user is not the super-user.
ENOTSOCK Argument is a descriptor for a file, not a socket.
EAGAIN Operation in progress. Application should call stun_bind() again when there is data available on the socket.

SOFIAPUBFUN int stun_discovery_get_address ( stun_discovery_t *  sd,
void *  addr,
socklen_t *  return_addrlen 
)

Returns the address of the public binding allocated by the NAT.

In case of multiple on path NATs, the binding allocated by the outermost NAT is returned.

This function returns the local address seen from outside. Note that the address is not valid until the event stun_clien_done is launched.

SOFIAPUBFUN stun_dns_lookup_t* stun_dns_lookup ( stun_magic_t magic,
su_root_t root,
stun_dns_lookup_f  func,
const char *  domain 
)

Performs a DNS-SRV check for STUN 'stun' (tcp) and 'stun' (udp) services for 'domain'.

The result will be delivered asynchronously in the 'func' callback. 'root' will be used as the event loop.

SOFIAPUBFUN int stun_dns_lookup_stp_addr ( stun_dns_lookup_t *  self,
const char **  target,
uint16_t *  port 
)

Fetches the results of a completed STUN DNS-SRV lookup for "_stun._udp" service (3489bis, "Short-Term Password").

Parameters:
self context pointer
target location where to stored the 'target' SRV field for stun service
port location where to store port number
Returns:
0 on success, non-zero otherwise

SOFIAPUBFUN int stun_dns_lookup_tcp_addr ( stun_dns_lookup_t *  self,
const char **  target,
uint16_t *  port 
)

Fetches the results of a completed STUN DNS-SRV lookup for "_stun._tcp" service (RFC3489).

Parameters:
self context pointer
target location where to stored the 'target' SRV field for stun service
port location where to store port number
Returns:
0 on success, non-zero otherwise

SOFIAPUBFUN int stun_dns_lookup_udp_addr ( stun_dns_lookup_t *  self,
const char **  target,
uint16_t *  port 
)

Fetches the results of a completed STUN DNS-SRV lookup for "_stun._udp" service (RFC3489/3489bis).

Parameters:
self context pointer
target location where to stored the 'target' SRV field for stun service
port location where to store port number
Returns:
0 on success, non-zero otherwise

SOFIAPUBFUN stun_handle_t* stun_handle_init ( su_root_t root,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Creates a STUN handle.

The created handles can be used for STUN binding discovery, keepalives, and other STUN usages.

Parameters:
root eventloop to used by the stun state machine
tag,value,... tag-value list
Related Tags:
STUNTAG_DOMAIN() domain to use in DNS-SRV based STUN server
STUNTAG_SERVER() stun server hostname or dotted IPv4 address
STUNTAG_REQUIRE_INTEGRITY() true if msg integrity should be used enforced

SOFIAPUBFUN int stun_is_requested ( tag_type_t  tag,
tag_value_t  value,
  ... 
)

Check if a STUN handle should be created.

Return true if STUNTAG_SERVER() or STUNTAG_DOMAIN() tags have been specified, or otherwise if STUN_SERVER environment variable is set.

Related Tags:
STUNTAG_DOMAIN() domain to use in DNS-SRV based STUN server
STUNTAG_SERVER() stun server hostname or dotted IPv4 address
Parameters:
tag,value,... tag-value list

SOFIAPUBFUN stun_nattype_t stun_nattype ( stun_discovery_t *  sd  ) 

Returns the detected NAT type.

See also:
stun_nattype_str().

stun_test_nattype().

SOFIAPUBFUN char const* stun_nattype_str ( stun_discovery_t *  sd  ) 

Returns the NAT type attached to STUN discovery handle.

See also:
stun_nattype_str().

stun_test_nattype().

SOFIAPUBFUN int stun_obtain_shared_secret ( stun_handle_t *  sh,
stun_discovery_f  sdf,
stun_discovery_magic_t magic,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Performs shared secret request/response processing.

Result will be trigged in STUN handle callback (state one of stun_tls_*).

SOFIAPUBFUN su_root_t* stun_root ( stun_handle_t *  self  ) 

Return su_root_t assigned to stun_handle_t.

Parameters:
self stun_handle_t object
Returns:
su_root_t object, NULL if self not given.

SOFIAPUBFUN int stun_test_lifetime ( stun_handle_t *  sh,
stun_discovery_f  sdf,
stun_discovery_magic_t magic,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Initiates STUN discovery process to find out NAT binding life-time settings.

Related Tags:
STUNTAG_SOCKET Bind socket for STUN
STUNTAG_REGISTER_EVENTS Register socket for eventloop owned by STUN
STUNTAG_SERVER() stun server hostname or dotted IPv4 address
Returns:
0 on success, non-zero on error

SOFIAPUBFUN int stun_test_nattype ( stun_handle_t *  sh,
stun_discovery_f  sdf,
stun_discovery_magic_t magic,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Initiates STUN discovery process to find out NAT characteristics.

Process partly follows the algorithm defined in RFC3489 section 10.1. Due the known limitations of RFC3489, some of the tests are done.

Note: does not support STUNTAG_DOMAIN() even if specified to stun_handle_init().

Related Tags:
STUNTAG_SOCKET Bind socket for STUN
STUNTAG_REGISTER_SOCKET Register socket for eventloop owned by STUN
STUNTAG_SERVER() stun server hostname or dotted IPv4 address
Returns:
0 on success, non-zero on error


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