Changeset 754 for pjproject/trunk/pjlib-util/include/pjlib-util/stun.h

Timestamp:

Oct 8, 2006 1:56:07 PM (18 years ago)

Author:

bennylp

Message:

Added pjlib-util/config.h and pjlib-util/types.h to put
together common settings, and updated Doxygen documentation
for PJLIB-UTIL.

File:

• pjproject/trunk/pjlib-util/include/pjlib-util/stun.h (modified) (7 diffs)

pjproject/trunk/pjlib-util/include/pjlib-util/stun.h

@@ -20 +20 @@
 #define __PJ_STUN_H__
 
-#include <pj/types.h>
+/**
+ * @file stun.h
+ * @brief STUN client.
+ */
+
+#include <pjlib-util/types.h>
 #include <pj/sock.h>
 
+/**
+ * @defgroup PJLIB_UTIL_STUN_CLIENT Mini/Tiny STUN Client
+ * @ingroup PJLIB_UTIL
+ * @{
+ */
+
 PJ_BEGIN_DECL
 
-#define PJ_STUN_MAX_ATTR    16
-
+/**
+ * This enumeration describes STUN message types.
+ */
 typedef enum pj_stun_msg_type
 {
@@ -37 +49 @@
 } pj_stun_msg_type;
 
+
+/**
+ * This enumeration describes STUN attribute types.
+ */
 typedef enum pj_stun_attr_type
 {
@@ -52 +68 @@
 } pj_stun_attr_type;
 
+
+/**
+ * This structre describes STUN message header.
+ */
 typedef struct pj_stun_msg_hdr
 {
@@ -59 +79 @@
 } pj_stun_msg_hdr;
 
+
+/**
+ * This structre describes STUN attribute header.
+ */
 typedef struct pj_stun_attr_hdr
 {
@@ -65 +89 @@
 } pj_stun_attr_hdr;
 
+
+/**
+ * This structre describes STUN MAPPED-ADDR attribute.
+ */
 typedef struct pj_stun_mapped_addr_attr
 {
@@ -119 +147 @@
 PJ_DECL(void*) pj_stun_msg_find_attr( pj_stun_msg *msg, pj_stun_attr_type t);
 
+
+/**
+ * This is the main function to request the mapped address of local sockets
+ * to multiple STUN servers. This function is able to find the mapped 
+ * addresses of multiple sockets simultaneously, and for each socket, two
+ * requests will be sent to two different STUN servers to see if both servers
+ * get the same public address for the same socket. (Note that application can
+ * specify the same address for the two servers, but still two requests will
+ * be sent for each server).
+ *
+ * This function will perform necessary retransmissions of the requests if
+ * response is not received within a predetermined period. When all responses
+ * have been received, the function will compare the mapped addresses returned
+ * by the servers, and when both are equal, the address will be returned in
+ * \a mapped_addr argument.
+ *
+ * @param pf            The pool factory where memory will be allocated from.
+ * @param sock_cnt      Number of sockets in the socket array.
+ * @param sock          Array of local UDP sockets which public addresses are
+ *                      to be queried from the STUN servers.
+ * @param srv1          Host name or IP address string of the first STUN
+ *                      server.
+ * @param port1         The port number of the first STUN server. 
+ * @param srv2          Host name or IP address string of the second STUN
+ *                      server.
+ * @param port2         The port number of the second STUN server. 
+ * @param mapped_addr   Array to receive the mapped public address of the local
+ *                      UDP sockets, when the function returns PJ_SUCCESS.
+ *
+ * @return              This functions returns PJ_SUCCESS if responses are
+ *                      received from all servers AND all servers returned the
+ *                      same mapped public address. Otherwise this function may
+ *                      return one of the following error codes:
+ *                      - PJLIB_UTIL_ESTUNNOTRESPOND: no respons from servers.
+ *                      - PJLIB_UTIL_ESTUNSYMMETRIC: different mapped addresses
+ *                        are returned by servers.
+ *                      - etc.
+ *
+ */
 PJ_DECL(pj_status_t) pj_stun_get_mapped_addr( pj_pool_factory *pf,
                                               int sock_cnt, pj_sock_t sock[],
@@ -127 +194 @@
 PJ_END_DECL
 
+/**
+ * @}
+ */
+
 #endif  /* __PJ_STUN_H__ */