Skip to content

GitLab

Commit 12b8a29a authored by Kai Vehmanen's avatar Kai Vehmanen
Browse files

STUN documentation update - no functional changes. 

darcs-hash:20060323230353-7659e-fc22204e3206c76e887a839a1fe88b36be2bc566.gz
parent 99c437eb
Hide whitespace changes
Inline Side-by-side
Showing with 61 additions and 65 deletions
libsofia-sip-ua/stun/sofia-sip/stun.h
View file @ 12b8a29a
......@@ -170,36 +170,38 @@ su_root_t *stun_root(stun_handle_t *sh);
int stun_is_requested(tag_type_t tag, tag_value_t value, ...);
char const *stun_str_state(stun_state_t state);
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);
/* -------------------------------------------------------------------
* Functions for 'Binding Discovery' usage (RFC3489/3489bis) */
int stun_request_shared_secret(stun_handle_t *sh);
int stun_bind(stun_handle_t *sh,
stun_discovery_f,
stun_discovery_magic_t *magic,
tag_type_t tag, tag_value_t value,
...);
int stun_get_nattype(stun_handle_t *sh,
stun_discovery_f,
stun_discovery_magic_t *magic,
tag_type_t tag, tag_value_t value,
...);
char const *stun_nattype(stun_discovery_t *sd);
stun_discovery_f, stun_discovery_magic_t *magic,
tag_type_t tag, tag_value_t value, ...);
su_sockaddr_t *stun_discovery_get_address(stun_discovery_t *sd);
su_socket_t stun_discovery_get_socket(stun_discovery_t *sd);
int stun_get_nattype(stun_handle_t *sh,
stun_discovery_f, stun_discovery_magic_t *magic,
tag_type_t tag, tag_value_t value, ...);
char const *stun_nattype(stun_discovery_t *sd);
int stun_get_lifetime(stun_handle_t *sh,
stun_discovery_f,
stun_discovery_magic_t *magic,
tag_type_t tag, tag_value_t value,
...);
stun_discovery_f, stun_discovery_magic_t *magic,
tag_type_t tag, tag_value_t value, ...);
int stun_lifetime(stun_discovery_t *sd);
/* -------------------------------------------------------------------
* Functions for 'Connectivity Check' and 'NAT Keepalives' usages (RFC3489bis) */
int stun_set_uname_pwd(stun_handle_t *sh,
const char *uname,
int len_uname,
......@@ -209,16 +211,6 @@ int stun_set_uname_pwd(stun_handle_t *sh,
int stun_msg_is_keepalive(uint16_t data);
int stun_message_length(void *data, int len, int end_of_message);
/* 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 */
int stun_keepalive(stun_handle_t *sh,
......@@ -232,6 +224,20 @@ int stun_keepalive_destroy(stun_handle_t *sh, su_socket_t s);
/* (not implemented, see stun_request_shared_secret()) */
/* -------------------------------------------------------------------
* 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);
/* --------------------------------------------------------------------
* Deprecated functions. These are supported with limited
* compatibility. */
......@@ -269,20 +275,6 @@ int stun_handle_set_uname_pwd(stun_handle_t *sh,
const char *pwd,
int len_pwd);
/* -------------------------------------------------------------------
* 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);
SOFIA_END_DECLS
#endif /* !defined(STUN_H) */
libsofia-sip-ua/stun/stun.c
View file @ 12b8a29a
......@@ -381,8 +381,14 @@ int stun_is_requested(tag_type_t tag, tag_value_t value, ...)
}
/**
* Create a STUN handle
* Creates a STUN handle.
*
* The created handles can be used for STUN binding discovery,
* keepalives, and other STUN usages.
*
* @param context self pointer for callback 'cb'
* @param root eventloop to used by the stun state machine
* @param cb callback to signal state machine events
* @param tag,value,... tag-value list
*
* @TAGS
......@@ -490,11 +496,9 @@ int stun_handle_request_shared_secret(stun_handle_t *sh)
* Result will be trigged in STUN handle callback (state
* one of stun_tls_*).
**/
#if defined(HAVE_OPENSSL)
/** Shared secret request/response processing */
int stun_request_shared_secret(stun_handle_t *sh)
{
#if defined(HAVE_OPENSSL)
int events = -1;
int one, err = -1;
su_wait_t wait[1] = { SU_WAIT_INIT };
......@@ -588,13 +592,10 @@ int stun_request_shared_secret(stun_handle_t *sh)
su_timer_set(connect_timer, stun_tls_connect_timer_cb, (su_wakeup_arg_t *) sd);
return 0;
#else /* !HAVE_OPENSSL */
return -1;
#endif
}
#else
int stun_request_shared_secret(stun_handle_t *sh)
{
return 0;
}
#endif /* HAVE_OPENSSL */
static stun_request_t *stun_request_create(stun_discovery_t *sd)
{
......@@ -965,21 +966,24 @@ static int priv_stun_bind_send(stun_handle_t *sh, stun_request_t *req, stun_disc
return res;
}
/** Bind a socket using STUN client.
/**
* 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'.
*
* The function stun_bind() obtains a global address for a UDP socket using
* a STUN server.
* 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'.
*
* @param ss dpointer to a STUN client object (IN)
* @param my_addr public address for socket (IN/OUT)
* @param addrlen length of pub_addr (IN/OUT)
* @param lifetime return value pointer to lifetime of
* binding, -1 if no STUN not used (OUT)
* @param sh pointer to valid stun handle
* @param sdf callback to signal process progress
* @param magic context pointer attached to 'sdf'
*
* @TAGS
* @TAG STUNTAG_SOCKET Bind socket for STUN
* @TAG STUNTAG_REGISTER_SOCKET Register socket for eventloop owned by STUN
* @TAG STUNTAG_SOCKET Bind socket for STUN (socket handle).
* @TAG STUNTAG_REGISTER_SOCKET Register socket for eventloop owned by STUN (boolean)
* @return
* On success, zero is returned. Upon error, -1 is returned, and @e errno is
......@@ -995,7 +999,6 @@ static int priv_stun_bind_send(stun_handle_t *sh, stun_request_t *req, stun_disc
* @ERROR EAGAIN Operation in progress. Application should call
* stun_bind() again when there is data available on
* the socket.
*
*/
int stun_bind(stun_handle_t *sh,
stun_discovery_f sdf,
......@@ -1039,8 +1042,7 @@ int stun_bind(stun_handle_t *sh,
if (!sh->sh_pri_addr[0].su_port) {
/* no STUN server address, perform a DNS-SRV lookup */
SU_DEBUG_5(("Delaying STUN bind for DNS-SRV query.\n"));
priv_dns_queue_bind(sh, req, sd);
return 0;
return priv_dns_queue_bind(sh, req, sd);
}
/* note: we always report success if bind() succeeds */
......@@ -1140,7 +1142,8 @@ int stun_handle_get_nattype(stun_handle_t *sh,
* Initiates STUN discovery proces to find out NAT
* characteristics.
*
* Note: does not support STUNTAG_DOMAIN().
* Note: does not support STUNTAG_DOMAIN() even if specified to
* stun_handle_create().
*
* @TAGS
* @TAG STUNTAG_SOCKET Bind socket for STUN
......@@ -2559,7 +2562,8 @@ int stun_handle_get_lifetime(stun_handle_t *sh,
* Initiates STUN discovery proces to find out NAT
* binding life-time settings.
*
* Note: does not support STUNTAG_DOMAIN().
* Note: does not support STUNTAG_DOMAIN() even if specified to
* stun_handle_create().
*
* @TAGS
* @TAG STUNTAG_SOCKET Bind socket for STUN
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment