STUN documentation update - no functional changes.

darcs-hash:20060323230353-7659e-fc22204e3206c76e887a839a1fe88b36be2bc566.gz

libsofia-sip-ua/stun/sofia-sip/stun.h

@@ -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

@@ -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