Changeset 1110 for pjproject

pjproject/trunk/pjlib/src/pj/ip_helper_win32.c

-                      r1104
+                      r1110
     /* Now fill out the entries */
     count = (pTab->dwNumEntries < *p_cnt) ? pTab->dwNumEntries : *p_cnt;
+    *p_cnt = 0;
     for (i=0; i<count; ++i) {
+        ifs[i].s_addr = pTab->table[i].dwAddr;
+        /* Some Windows returns 0.0.0.0! */
+        if (pTab->table[i].dwAddr == 0)
+            continue;
+        ifs[*p_cnt].s_addr = pTab->table[i].dwAddr;
+        (*p_cnt)++;
+    }
-    *p_cnt = count;
     return PJ_SUCCESS;

pjproject/trunk/pjnath/build/pjnath.dsp

-                      r1101
+                      r1110
 # ADD BASE CPP /nologo /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_MBCS" /D "_LIB" /YX /FD /c
 # ADD CPP /nologo /MD /W4 /GX /O1 /Ob2 /I "../include" /I "../../pjlib/include" /I "../../pjlib-util/include" /D "NDEBUG" /D "WIN32" /D "_MBCS" /D "_LIB" /D PJ_WIN32=1 /D PJ_M_I386=1 /FR /FD /c
 # SUBTRACT CPP /Z<none> /YX
+# SUBTRACT CPP /YX
 # ADD BASE RSC /l 0x409 /d "NDEBUG"
 # ADD RSC /l 0x409 /d "NDEBUG"
 …
 # Begin Source File
-SOURCE=..\include\pjnath\stun_doc.h
-# End Source File
-# Begin Source File
 SOURCE=..\include\pjnath\stun_msg.h
 # End Source File
 …
 # Begin Source File
-SOURCE=..\include\pjnath\turn_client.h
-# End Source File
-# Begin Source File
 SOURCE=..\include\pjnath\types.h
 # End Source File

pjproject/trunk/pjnath/docs

Property svn:ignore set to
html
latex

pjproject/trunk/pjnath/include/pjnath/config.h

-                      r1080
+                      r1110
 /**
  * @defgroup PJNATH_CONFIG Configuration
  * @ingroup PJNATH
+ * @brief Various compile time settings
  * @{
  */
 …
  * STUN CLIENT CONFIGURATION
  */
-/**
- * Maximum number of attributes in the STUN packet (for the old STUN
- * library).
+ *
- * Default: 16
- */
-#ifndef PJSTUN_MAX_ATTR
-#   define PJSTUN_MAX_ATTR                          16
-#endif
 /**
 …
 #endif
+/**
+ * The default initial STUN round-trip time estimation (the RTO value
+ * in RFC 3489-bis), in miliseconds.
+ * This value is used to control the STUN request
+ * retransmit time. The initial value of retransmission interval
+ * would be set to this value, and will be doubled after each
+ * retransmission.
+ */
+#ifndef PJ_STUN_RTO_VALUE
+#   define PJ_STUN_RTO_VALUE                        100
+#endif
+/**
+ * The STUN transaction timeout value, in miliseconds.
+ * After the last retransmission is sent and if no response is received
+ * after this time, the STUN transaction will be considered to have failed.
+ *
+ * The default value is 1600 miliseconds (as per RFC 3489-bis).
+ */
+#ifndef PJ_STUN_TIMEOUT_VALUE
+#   define PJ_STUN_TIMEOUT_VALUE                    1600
+#endif
+/**
+ * Maximum number of STUN retransmission count.
+ *
+ * Default: 7 (as per RFC 3489-bis)
+ */
+#ifndef PJ_STUN_MAX_RETRANSMIT_COUNT
+#   define PJ_STUN_MAX_RETRANSMIT_COUNT             7
+#endif
+/**
+ * Maximum size of STUN message.
+ */
+#ifndef PJ_STUN_MAX_PKT_LEN
+#   define PJ_STUN_MAX_PKT_LEN                      512
+#endif
+/**
+ * Default STUN port as defined by RFC 3489.
+ */
+#define PJ_STUN_PORT                                3478
+/* **************************************************************************
+ * ICE CONFIGURATION
+ */
+/**
+ * Maximum number of ICE candidates.
+ *
+ * Default: 16
+ */
+#ifndef PJ_ICE_MAX_CAND
+#   define PJ_ICE_MAX_CAND                          16
+#endif
+/**
+ * Maximum number of candidates for each ICE stream transport component.
+ *
+ * Default: 8
+ */
+#ifndef PJ_ICE_ST_MAX_CAND
+#   define PJ_ICE_ST_MAX_CAND                       8
+#endif
+/**
+ * Maximum number of ICE components.
+ *
+ * Default: 8
+ */
+#ifndef PJ_ICE_MAX_COMP
+#   define PJ_ICE_MAX_COMP                          8
+#endif
+/**
+ * Maximum number of ICE checks.
+ *
+ * Default: 32
+ */
+#ifndef PJ_ICE_MAX_CHECKS
+#   define PJ_ICE_MAX_CHECKS                        32
+#endif
+/**
+ * Default timer interval (in miliseconds) for starting ICE periodic checks.
+ *
+ * Default: 20
+ */
+#ifndef PJ_ICE_TA_VAL
+#   define PJ_ICE_TA_VAL                            20
+#endif
 /**

pjproject/trunk/pjnath/include/pjnath/errno.h

-                      r1101
+                      r1110
 #define __PJNATH_ERRNO_H__
+/**
+ * @file errno.h
+ * @brief PJNATH specific error codes
+ */
 #include <pj/errno.h>
 …
 /**
  * @defgroup PJNATH_ERROR NAT Helper Library Error Codes
  * @ingroup PJNATH
+ * @brief PJNATH specific error code constants
  * @{
  */

pjproject/trunk/pjnath/include/pjnath/ice.h

-                      r1106
+                      r1110
 /**
  * @file ice.h
  * @brief ICE.
+ * @brief ICE session management
  */
 #include <pjnath/types.h>
 …
  * @defgroup PJNATH_ICE Interactive Connectivity Establishment (ICE)
  * @brief Interactive Connectivity Establishment (ICE)
- * @ingroup PJNATH
  */
 …
 /**
  * @defgroup PJNATH_ICE_STREAM Transport Independent ICE Media Stream
  * @brief Transport Independent ICE Media Stream
+ * @defgroup PJNATH_ICE_SESSION ICE Session
+ * @brief Transport Independent ICE Session
  * @ingroup PJNATH_ICE
  * @{
+ *
+ * This module describes #pj_ice, a transport independent ICE session,
+ * part of PJNATH - the Open Source NAT helper library.
+ *
+ * An ICE session, represented by #pj_ice structure, is the lowest
+ * abstraction of ICE in PJNATH, and it is used to perform and manage
+ * connectivity checks of transport address candidates <b>within a
+ * single media stream</b> (note: this differs from what is described
+ * in ICE draft, where an ICE session manages the whole media sessions
+ * rather than just a single stream).
+ *
+ * The ICE session described here is independent from any transports,
+ * meaning that the actual network I/O for this session would have to
+ * be performed by the application, or higher layer abstraction.
+ * Using this framework, application would give any incoming packets to
+ * the ICE session, and it would provide the ICE session with a callback
+ * to send outgoing message.
+ *
+ * For higher abstraction of ICE where transport is included, please
+ * see \ref PJNATH_ICE_STREAM_TRANSPORT.
  */
 …
 typedef enum pj_ice_cand_type
+{
     PJ_ICE_CAND_TYPE_HOST,
     PJ_ICE_CAND_TYPE_SRFLX,
     PJ_ICE_CAND_TYPE_PRFLX,
     PJ_ICE_CAND_TYPE_RELAYED
+    PJ_ICE_CAND_TYPE_HOST,      /**< ICE host candidate.                */
+    PJ_ICE_CAND_TYPE_SRFLX,     /**< ICE server reflexive candidate.    */
+    PJ_ICE_CAND_TYPE_PRFLX,     /**< ICE peer reflexive candidate.      */
+    PJ_ICE_CAND_TYPE_RELAYED    /**< ICE relayed candidate.             */
 } pj_ice_cand_type;
+/**
+ *
+/**
+ * This enumeration describes the default preference for the ICE
+ * candidate types as described by ICE standard.
  */
 enum pj_ice_type_pref
+{
     PJ_ICE_HOST_PREF        = 126,
     PJ_ICE_SRFLX_PREF       = 100,
     PJ_ICE_PRFLX_PREF       = 110,
     PJ_ICE_RELAYED_PREF     = 0
+    PJ_ICE_HOST_PREF        = 126,  /**< Preference value for host.     */
+    PJ_ICE_SRFLX_PREF       = 100,  /**< Preference value for SRFLX.    */
+    PJ_ICE_PRFLX_PREF       = 110,  /**< Preference value for PRFLX     */
+    PJ_ICE_RELAYED_PREF     = 0     /**< Preference value for relay     */
 };
+/** Forward declaration for pj_ice */
 typedef struct pj_ice pj_ice;
+/** Forward declaration for pj_ice_check */
 typedef struct pj_ice_check pj_ice_check;
+#define PJ_ICE_MAX_CAND     16
+#define PJ_ICE_MAX_COMP     8
+#define PJ_ICE_MAX_CHECKS   32
+#define PJ_ICE_TA_VAL       20
+/**
  * ICE component
+/**
+ * This structure describes ICE component.
+ * A media stream may require multiple components, each of which has
+ * to work for the media stream as a whole to work.  For media streams
+ * based on RTP, there are two components per media stream - one for RTP,
+ * and one for RTCP.
  */
 typedef struct pj_ice_comp
+{
+    /**
+     * The pointer to ICE check which was nominated for this component.
+     * The value will be NULL if a nominated check has not been found
+     * for this component.
+     */
     pj_ice_check        *valid_check;
 } pj_ice_comp;
 …
 /**
  * This structure describes an ICE candidate.
+ * ICE candidate is a transport address that is to be tested by ICE
+ * procedures in order to determine its suitability for usage for
+ * receipt of media.  Candidates also have properties - their type
+ * (server reflexive, relayed or host), priority, foundation, and
+ * base.
  */
 typedef struct pj_ice_cand
+{
+    /**
+     * The component ID of this candidate. Note that component IDs starts
+     * with one for RTP and two for RTCP. In other words, it's not zero
+     * based.
+     */
     pj_uint32_t          comp_id;
+    /**
+     * The candidate type, as described in #pj_ice_cand_type enumeration.
+     */
     pj_ice_cand_type     type;
+    /**
+     * The foundation string, which is an identifier which value will be
+     * equivalent for two candidates that are of the same type, share the
+     * same base, and come from the same STUN server. The foundation is
+     * used to optimize ICE performance in the Frozen algorithm.
+     */
     pj_str_t             foundation;
+    /**
+     * The candidate's priority, a 32-bit unsigned value which value will be
+     * calculated by the ICE session when a candidate is registered to the
+     * ICE session.
+     */
     pj_uint32_t          prio;
+    /**
+     * IP address of this candidate. For host candidates, this represents
+     * the local address of the socket. For reflexive candidates, the value
+     * will be the public address allocated in NAT router for the host
+     * candidate and as reported in MAPPED-ADDRESS or XOR-MAPPED-ADDRESS
+     * attribute of STUN Binding request. For relayed candidate, the value
+     * will be the address allocated in the TURN server by STUN Allocate
+     * request.
+     */
     pj_sockaddr          addr;
+    /**
+     * Base address of this candidate. "Base" refers to the address an agent
+     * sends from for a particular candidate.  For host candidates, the base
+     * is the same as the host candidate itself. For reflexive candidates,
+     * the base is the local IP address of the socket. For relayed candidates,
+     * the base address is the transport address allocated in the TURN server
+     * for this candidate.
+     */
     pj_sockaddr          base_addr;
+    /**
+     * Related address, which is used for informational only and is not used
+     * in any way by the ICE session.
+     */
     pj_sockaddr          rel_addr;
+    /**
+     * The STUN session to be used to send and receive STUN messages for this
+     * candidate.
+     */
     pj_stun_session     *stun_sess;
 } pj_ice_cand;
+/**
+ * This enumeration describes the state of ICE check.
+ */
 typedef enum pj_ice_check_state
+{
+    /**
+     * A check for this pair hasn't been performed, and it can't
+     * yet be performed until some other check succeeds, allowing this
+     * pair to unfreeze and move into the Waiting state.
+     */
     PJ_ICE_CHECK_STATE_FROZEN,
+    /**
+     * A check has not been performed for this pair, and can be
+     * performed as soon as it is the highest priority Waiting pair on
+     * the check list.
+     */
     PJ_ICE_CHECK_STATE_WAITING,
+    /**
+     * A check has not been performed for this pair, and can be
+     * performed as soon as it is the highest priority Waiting pair on
+     * the check list.
+     */
     PJ_ICE_CHECK_STATE_IN_PROGRESS,
+    /**
+     * A check has not been performed for this pair, and can be
+     * performed as soon as it is the highest priority Waiting pair on
+     * the check list.
+     */
     PJ_ICE_CHECK_STATE_SUCCEEDED,
+    /**
+     * A check for this pair was already done and failed, either
+     * never producing any response or producing an unrecoverable failure
+     * response.
+     */
     PJ_ICE_CHECK_STATE_FAILED
 } pj_ice_check_state;
+/**
+ * This structure describes an ICE connectivity check. An ICE check
+ * contains a candidate pair, and will involve sending STUN Binding
+ * Request transaction for the purposes of verifying connectivity.
+ * A check is sent from the local candidate to the remote candidate
+ * of a candidate pair.
+ */
 struct pj_ice_check
+{
+    /**
+     * Pointer to local candidate entry of this check.
+     */
     pj_ice_cand         *lcand;
+    /**
+     * Pointer to remote candidate entry of this check.
+     */
     pj_ice_cand         *rcand;
+    /**
+     * Check priority.
+     */
     pj_uint64_t          prio;
+    /**
+     * Connectivity check state.
+     */
     pj_ice_check_state   state;
+    /**
+     * STUN transmit data containing STUN Binding request that was sent
+     * as part of this check. The value will only be set when this check
+     * has a pending transaction, and is used to cancel the transaction
+     * when other check has succeeded.
+     */
     pj_stun_tx_data     *tdata;
+    /**
+     * Flag to indicate whether this check is nominated. A nominated check
+     * contains USE-CANDIDATE attribute in its STUN Binding request.
+     */
     pj_bool_t            nominated;
+    /**
+     * When the check failed, this will contain the failure status of the
+     * STUN transaction.
+     */
     pj_status_t          err_code;
 };
+/**
+ * This enumeration describes ICE checklist state.
+ */
 typedef enum pj_ice_checklist_state
+{
+    /**
+     * The checklist is not yet running.
+     */
     PJ_ICE_CHECKLIST_ST_IDLE,
+    /**
+     * In this state, ICE checks are still in progress for this
+     * media stream.
+     */
     PJ_ICE_CHECKLIST_ST_RUNNING,
+    /**
+     * In this state, ICE checks have completed for this media stream,
+     * either successfully or with failure.
+     */
     PJ_ICE_CHECKLIST_ST_COMPLETED
 } pj_ice_checklist_state;
+/**
+ * This structure represents ICE check list, that is an ordered set of
+ * candidate pairs that an agent will use to generate checks.
+ */
 typedef struct pj_ice_checklist
+{
+    /**
+     * The checklist state.
+     */
     pj_ice_checklist_state   state;
+    /**
+     * Number of candidate pairs (checks).
+     */
     unsigned                 count;
+    /**
+     * Array of candidate pairs (checks).
+     */
     pj_ice_check             checks[PJ_ICE_MAX_CHECKS];
+    /**
+     * A timer used to perform periodic check for this checklist.
+     */
     pj_timer_entry           timer;
 } pj_ice_checklist;
 /**
+ * ICE sock callback.
+ * This structure contains callbacks that will be called by the ICE
+ * session.
  */
 typedef struct pj_ice_cb
+{
+    /**
+     * An optional callback that will be called by the ICE session when
+     * ICE negotiation has completed, successfully or with failure.
+     *
+     * @param ice           The ICE session.
+     * @param status        Will contain PJ_SUCCESS if ICE negotiation is
+     *                      successful, or some error code.
+     */
     void        (*on_ice_complete)(pj_ice *ice, pj_status_t status);
+    /**
+     * A mandatory callback which will be called by the ICE session when
+     * it needs to send outgoing STUN packet.
+     *
+     * @param ice           The ICE session.
+     * @param comp_id       ICE component ID.
+     * @param cand_id       ICE candidate ID.
+     * @param pkt           The STUN packet.
+     * @param size          The size of the packet.
+     * @param dst_addr      Packet destination address.
+     * @param dst_addr_len  Length of destination address.
+     */
     pj_status_t (*on_tx_pkt)(pj_ice *ice, unsigned comp_id,
                              unsigned cand_id,
 …
                              const pj_sockaddr_t *dst_addr,
                              unsigned dst_addr_len);
+    /**
+     * A mandatory callback which will be called by the ICE session when
+     * it receives packet which is not part of ICE negotiation.
+     *
+     * @param ice           The ICE session.
+     * @param comp_id       ICE component ID.
+     * @param pkt           The whole packet.
+     * @param size          Size of the packet.
+     * @param src_addr      Source address where this packet was received
+     *                      from.
+     * @param src_addr_len  The length of source address.
+     */
     void        (*on_rx_data)(pj_ice *ice, unsigned comp_id,
                               void *pkt, pj_size_t size,
 …
+/**
+ * This enumeration describes ICE role.
+ */
 typedef enum pj_ice_role
+{
+    /**
+     * The ICE agent is in controlled role.
+     */
     PJ_ICE_ROLE_CONTROLLED,
+    /**
+     * The ICE agent is in controlling role.
+     */
     PJ_ICE_ROLE_CONTROLLING
 } pj_ice_role;
+/**
+ * ICE structure.
+/**
+ * This structure describes the ICE session. For this version of PJNATH,
+ * an ICE session corresponds to a single media stream (unlike the ICE
+ * session described in the ICE standard where an ICE session covers the
+ * whole media and may consist of multiple media streams). The decision
+ * to support only a single media session was chosen for simplicity,
+ * while still allowing application to utilize multiple media streams by
+ * creating multiple ICE sessions, one for each media stream.
  */
 struct pj_ice
+{
     char                obj_name[PJ_MAX_OBJ_NAME];
     pj_pool_t           *pool;
     void                *user_data;
     pj_mutex_t          *mutex;
     pj_ice_role          role;
     pj_bool_t            is_complete;
     pj_status_t          ice_status;
     pj_ice_cb            cb;
     pj_stun_config       stun_cfg;
+    char                obj_name[PJ_MAX_OBJ_NAME];  /**< Object name.       */
+    pj_pool_t           *pool;                      /**< Pool instance.     */
+    void                *user_data;                 /**< App. data.         */
+    pj_mutex_t          *mutex;                     /**< Mutex.             */
+    pj_ice_role          role;                      /**< ICE role.          */
+    pj_bool_t            is_complete;               /**< Complete?          */
+    pj_status_t          ice_status;                /**< Error status.      */
+    pj_ice_cb            cb;                        /**< Callback.          */
+    pj_stun_config       stun_cfg;                  /**< STUN settings.     */
     /* STUN credentials */
     pj_str_t             tx_ufrag;
     pj_str_t             tx_uname;
     pj_str_t             tx_pass;
     pj_str_t             rx_ufrag;
     pj_str_t             rx_uname;
     pj_str_t             rx_pass;
+    pj_str_t             tx_ufrag;                  /**< Remote ufrag.      */
+    pj_str_t             tx_uname;                  /**< Uname for TX.      */
+    pj_str_t             tx_pass;                   /**< Remote password.   */
+    pj_str_t             rx_ufrag;                  /**< Local ufrag.       */
+    pj_str_t             rx_uname;                  /**< Uname for RX       */
+    pj_str_t             rx_pass;                   /**< Local password.    */
     /* Components */
     unsigned             comp_cnt;
     pj_ice_comp          comp[PJ_ICE_MAX_COMP];
+    unsigned             comp_cnt;                  /**< # of components.   */
+    pj_ice_comp          comp[PJ_ICE_MAX_COMP];     /**< Component array    */
     /* Local candidates */
     unsigned             lcand_cnt;
     pj_ice_cand          lcand[PJ_ICE_MAX_CAND];
+    unsigned             lcand_cnt;                 /**< # of local cand.   */
+    pj_ice_cand          lcand[PJ_ICE_MAX_CAND];    /**< Array of cand.     */
     /* Remote candidates */
     unsigned             rcand_cnt;
     pj_ice_cand          rcand[PJ_ICE_MAX_CAND];
+    unsigned             rcand_cnt;                 /**< # of remote cand.  */
+    pj_ice_cand          rcand[PJ_ICE_MAX_CAND];    /**< Array of cand.     */
     /* Checklist */
     pj_ice_checklist     clist;
+    pj_ice_checklist     clist;                     /**< Active checklist   */
     /* Valid list */
     pj_ice_checklist     valid_list;
+    pj_ice_checklist     valid_list;                /**< Valid list.        */
 };
+/**
+ * This is a utility function to retrieve the string name for the
+ * particular candidate type.
+ *
+ * @param type      Candidate type.
+ *
+ * @return          The string representation of the candidate type.
+ */
 PJ_DECL(const char*) pj_ice_get_cand_type_name(pj_ice_cand_type type);
+/**
+ * Create ICE session with the specified role and number of components.
+ * Application would typically need to create an ICE session before
+ * sending an offer or upon receiving one. After the session is created,
+ * application can register candidates to the ICE session by calling
+ * #pj_ice_add_cand() function.
+ *
+ * @param stun_cfg      The STUN configuration settings, containing among
+ *                      other things the timer heap instance to be used
+ *                      by the ICE session.
+ * @param name          Optional name to identify this ICE instance in
+ *                      the log file.
+ * @param role          ICE role.
+ * @param comp_cnt      Number of components.
+ * @param cb            ICE callback.
+ * @param local_ufrag   Optional string to be used as local username to
+ *                      authenticate incoming STUN binding request. If
+ *                      the value is NULL, a random string will be
+ *                      generated.
+ * @param local_passwd  Optional string to be used as local password.
+ * @param p_ice         Pointer to receive the ICE session instance.
+ *
+ * @return              PJ_SUCCESS if ICE session is created successfully.
+ */
 PJ_DECL(pj_status_t) pj_ice_create(pj_stun_config *stun_cfg,
                                    const char *name,
 …
                                    const pj_str_t *local_passwd,
                                    pj_ice **p_ice);
+/**
+ * Destroy ICE session.
+ *
+ * @param ice           ICE session instance.
+ *
+ * @return              PJ_SUCCESS on success.
+ */
 PJ_DECL(pj_status_t) pj_ice_destroy(pj_ice *ice);
+/**
+ * Add a candidate to this ICE session.
+ *
+ * @param ice           ICE session instance.
+ * @param comp_id       Component ID of this candidate.
+ * @param type          Candidate type.
+ * @param local_pref    Local preference for this candidate, which
+ *                      normally should be set to 65535.
+ * @param foundation    Foundation identification.
+ * @param addr          The candidate address.
+ * @param base_addr     The candidate's base address.
+ * @param rel_addr      Optional related address.
+ * @param addr_len      Length of addresses.
+ * @param p_cand_id     Optional pointer to receive the candidate ID.
+ *
+ * @return              PJ_SUCCESS if candidate is successfully added.
+ */
 PJ_DECL(pj_status_t) pj_ice_add_cand(pj_ice *ice,
                                      unsigned comp_id,
 …
                                      const pj_sockaddr_t *rel_addr,
                                      int addr_len,
+                                     unsigned *cand_id);
+                                     unsigned *p_cand_id);
+/**
+ * Find default candidate for the specified component ID, using this
+ * rule:
+ *  - if the component has a successful candidate pair, then the
+ *    local candidate of this pair will be returned.
+ *  - otherwise a relay, reflexive, or host candidate will be selected
+ *    on that specified order.
+ *
+ * @param ice           The ICE session instance.
+ * @param comp_id       The component ID.
+ * @param p_cand_id     Pointer to receive the candidate ID.
+ *
+ * @return              PJ_SUCCESS if a candidate has been selected.
+ */
 PJ_DECL(pj_status_t) pj_ice_find_default_cand(pj_ice *ice,
                                               unsigned comp_id,
+                                              int *cand_id);
+                                              int *p_cand_id);
+/**
+ * Pair the local and remote candidates to create check list. Application
+ * typically would call this function after receiving SDP containing ICE
+ * candidates from the remote host (either upon receiving the initial
+ * offer, for UAS, or upon receiving the answer, for UAC).
+ *
+ * Note that ICE connectivity check will not start until application calls
+ * #pj_ice_start_check().
+ *
+ * @param ice           ICE session instance.
+ * @param rem_ufrag     Remote ufrag, as seen in the SDP received from
+ *                      the remote agent.
+ * @param rem_passwd    Remote password, as seen in the SDP received from
+ *                      the remote agent.
+ * @param rem_cand_cnt  Number of remote candidates.
+ * @param rem_cand      Remote candidate array. Remote candidates are
+ *                      gathered from the SDP received from the remote
+ *                      agent.
+ *
+ * @return              PJ_SUCCESS or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_ice_create_check_list(pj_ice *ice,
                                               const pj_str_t *rem_ufrag,
 …
                                               unsigned rem_cand_cnt,
                                               const pj_ice_cand rem_cand[]);
+/**
+ * Start ICE periodic check. This function will return immediately, and
+ * application will be notified about the connectivity check status in
+ * #pj_ice_cb callback.
+ *
+ * @param ice           The ICE session instance.
+ *
+ * @return              PJ_SUCCESS or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_ice_start_check(pj_ice *ice);
+/**
+ * Send data using this ICE session. If ICE checks have not produced a
+ * valid check for the specified component ID, this function will return
+ * with failure. Otherwise ICE session will send the packet to remote
+ * destination using the nominated local candidate for the specified
+ * component.
+ *
+ * @param ice           The ICE session.
+ * @param comp_id       Component ID.
+ * @param data          The data or packet to be sent.
+ * @param data_len      Size of data or packet, in bytes.
+ *
+ * @return              PJ_SUCCESS if data is sent successfully.
+ */
 PJ_DECL(pj_status_t) pj_ice_send_data(pj_ice *ice,
                                       unsigned comp_id,
                                       const void *data,
                                       pj_size_t data_len);
+/**
+ * Report the arrival of packet to the ICE session. Since ICE session
+ * itself doesn't have any transports, it relies on application or
+ * higher layer component to give incoming packets to the ICE session.
+ * If the packet is not a STUN packet, this packet will be given back
+ * to application via \a on_rx_data() callback in #pj_ice_cb.
+ *
+ * @param ice           The ICE session.
+ * @param comp_id       Component ID.
+ * @param cand_id       Candidate ID.
+ * @param pkt           Incoming packet.
+ * @param pkt_size      Size of incoming packet.
+ * @param src_addr      Source address of the packet.
+ * @param src_addr_len  Length of the address.
+ *
+ * @return              PJ_SUCCESS or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_ice_on_rx_pkt(pj_ice *ice,
                                       unsigned comp_id,

pjproject/trunk/pjnath/include/pjnath/ice_stream_transport.h

-                      r1106
+                      r1110
 /**
  * @file ice_mt.h
  * @brief ICE Media Transport.
+ * @file ice_stream_transport.h
+ * @brief ICE Stream Transport
  */
 #include <pjnath/ice.h>
 …
  * @ingroup PJNATH_ICE
  * @{
+ */
+ *
+ * This module describes ICE stream transport, as represented by #pj_ice_st
+ * structure, and is part of PJNATH - the Open Source NAT traversal helper
+ * library.
+ *
+ * ICE stream transport, as represented by #pj_ice_st structure, is an ICE
+ * capable component for transporting media within a media stream.
+ * It consists of one or more transport sockets (typically two for RTP
+ * based communication - one for RTP and one for RTCP), and an
+ * \ref PJNATH_ICE_SESSION for performing connectivity checks among the.
+ * various candidates of the transport addresses.
+ *
+ * \section PJNATH_ICE_STREAM_TRANSPORT_USING Using the ICE Stream Transport
+ *
+ * Application may use the ICE stream transport in two ways:
+ *  - it can create the ICE stream transports once during application
+ *    initialization and keep them alive throughout application lifetime, or
+ *  - it can create and destroy the ICE stream transport as needed everytime
+ *     a call is made and destroyed.
+ *
+ * Keeping the ICE stream transport alive throughout
+ * application's lifetime is normally preferable, as initializing the
+ * ICE stream transport may incur delay because the ICE stream transport
+ * would need to communicate with the STUN/TURN server to get the
+ * server reflexive and relayed candidates for the transports.
+ *
+ * Regardless of which usage scenario is being used, the ICE stream
+ * transport is capable for restarting the ICE session being used and to
+ * send STUN keep-alives for its STUN server reflexive and relayed
+ * candidates.
+ *
+ * \subsection PJNATH_ICE_ST_TRA_INIT Stream Transport Initialization
+ *
+ * Application creates the ICE stream transport by calling
+ * #pj_ice_st_create() function.
+ *
+ * After the ICE stream transport is created, application may set up the
+ * STUN servers to be used to obtain STUN server reflexive and relayed
+ * candidate, by calling #pj_ice_st_set_stun_domain() or
+ * #pj_ice_st_set_stun_srv(). Then it has to create each component by
+ * calling #pj_ice_st_create_comp(); this would create an actual socket
+ * which listens to the specified local address, and it would also
+ * perform lookup to find various transport address candidates for this
+ * socket.
+ *
+ * \subsection PJNATH_ICE_ST_TRA_INIT_ICE ICE Session Initialization
+ *
+ * When application is about to send an offer containing ICE capability,
+ * or when it receives an offer containing ICE capability, it would
+ * create the ICE session by calling #pj_ice_st_init_ice(). This would
+ * register all transport address aliases for each component to the ICE
+ * session as candidates. After this application can enumerate all local
+ * candidates by calling #pj_ice_st_enum_cands(), and encode these
+ * candidates in the SDP to be sent to remote agent.
+ *
+ * \subsection PJNATH_ICE_ST_TRA_START Starting Connectivity Checks
+ *
+ * Once application receives the SDP from remote, it can start ICE
+ * connectivity checks by calling #pj_ice_st_start_ice(), specifying
+ * the username, password, and candidates of the remote agent. The ICE
+ * session/transport will then notify the application via the callback
+ * when ICE connectivity checks completes, either successfully or with
+ * failure.
+ *
+ * \subsection PJNATH_ICE_ST_TRA_STOP Stopping ICE Session
+ *
+ * Once the call is terminated, application no longer needs to keep the
+ * ICE session, so it should call #pj_ice_st_stop_ice() to destroy the
+ * ICE session within this ICE stream transport. Note that this WILL NOT
+ * destroy the sockets/transports, it only destroys the ICE session
+ * within this ICE stream transport.
+ *
+ * \subsection PJNATH_ICE_ST_TRA_RESTART Restarting ICE Session
+ *
+ * When a new call is made, application can repeat the above
+ * #pj_ice_st_init_ice() to #pj_ice_st_stop_ice() cycle for the new call,
+ * using this same ICE stream transport.
+ *
+ * \subsection PJNATH_ICE_ST_TRA_DESTROY Destroying ICE Stream Transport
+ *
+ * Finally, when the ICE stream transport itself is no longer needed,
+ * for example when the application quits, application should call
+ * #pj_ice_st_destroy() to release back all resources allocated by this
+ * ICE stream transport.
+ *
+ */
+/** Forward declaration for ICE stream transport. */
 typedef struct pj_ice_st pj_ice_st;
+/**
+ * This structure contains callbacks that will be called by the
+ * ICE stream transport.
+ */
 typedef struct pj_ice_st_cb
+{
+    /**
+     * This callback will be called when the ICE transport receives
+     * incoming packet from the sockets which is not related to ICE
+     * (for example, normal RTP/RTCP packet destined for application).
+     *
+     * @param ice_st        The ICE stream transport.
+     * @param comp_id       The component ID.
+     * @param pkt           The packet.
+     * @param size          Size of the packet.
+     * @param src_addr      Source address of the packet.
+     * @param src_addr_len  Length of the source address.
+     */
     void    (*on_rx_data)(pj_ice_st *ice_st,
                           unsigned comp_id,
 …
                           const pj_sockaddr_t *src_addr,
                           unsigned src_addr_len);
+    /**
+     * This callback will be called when ICE checks have completed.
+     * This callback is optional.
+     *
+     * @param ice_st        The ICE stream transport.
+     * @param status        The ICE connectivity check status.
+     */
     void    (*on_ice_complete)(pj_ice_st *ice_st,
                                pj_status_t status);
 …
+#ifndef PJ_ICE_ST_MAX_ALIASES
+#   define PJ_ICE_ST_MAX_ALIASES        8
+#endif
+/**
+ * Various flags that can be specified when creating a component with
+ * #pj_ice_st_create_comp(). These options may be combined together
+ * with bitmask operation.
+ */
 enum pj_ice_st_option
+{
+    /**
+     * If this option is specified, only a listening socket will be
+     * created for the component, and no candidate will be added to
+     * the component. Application must add the component manually
+     * by inspecting the socket and transport address of the component.
+     */
     PJ_ICE_ST_OPT_DONT_ADD_CAND = 1,
+    /**
+     * If this option is specified, then no STUN reflexive candidate
+     * will be added to the component.
+     */
     PJ_ICE_ST_OPT_DISABLE_STUN  = 2,
+    /**
+     * If this option is specified, then no STUN relay candidate
+     * will be added to the component.
+     */
     PJ_ICE_ST_OPT_DISABLE_RELAY = 4,
+    /**
+     * If this option is specified, then when the function fails to
+     * bind the socket to the specified port, it WILL NOT try to
+     * bind the socket to the next available port.
+     *
+     * If this option is NOT specified, then the function will try to
+     * bind the socket to next port+2, repetitively until the socket
+     * is bound successfully.
+     */
     PJ_ICE_ST_OPT_NO_PORT_RETRY = 8,
 };
+/**
+ * This structure describes ICE stream transport candidate. A "candidate"
+ * in ICE stream transport can be viewed as alias transport address
+ * for the socket.
+ */
 typedef struct pj_ice_st_cand
+{
+    /**
+     * Candidate type.
+     */
     pj_ice_cand_type    type;
+    /**
+     * Status of this candidate. This status is useful for ICE reflexive
+     * and relay candidate, where the address needs to be resolved
+     * asynchronously by sending STUN request to STUN server.
+     *
+     * The value will be PJ_SUCCESS if candidate address has been resolved
+     * successfully, PJ_EPENDING when the address resolution process is
+     * in progress, or other value when the address resolution has
+     * completed with failure.
+     */
     pj_status_t         status;
+    /**
+     * The candidate transport address.
+     */
     pj_sockaddr         addr;
+    int                 cand_id;
+    /**
+     * The ICE session candidate ID after this candidate has been registered
+     * to an ICE session. Before ICE session is created, or after ICE
+     * session has been destroyed, the value will be -1.
+     */
+    int                 ice_cand_id;
+    /**
+     * Local preference value, which typically is 65535.
+     */
     pj_uint16_t         local_pref;
+    /**
+     * Foundation associated with this candidate, which value normally will be
+     * calculated by the function.
+     */
     pj_str_t            foundation;
 } pj_ice_st_cand;
+/**
+ * This structure describes an ICE stream transport component. A component
+ * in ICE stream transport typically corresponds to a single socket created
+ * for this component, and bound to a specific transport address. This
+ * component may have multiple alias addresses, for example one alias
+ * address for each interfaces in multi-homed host, another for server
+ * reflexive alias, and another for relayed alias. For each transport
+ * address alias, an ICE stream transport candidate (#pj_ice_st_cand) will
+ * be created, and these candidates will eventually registered to the ICE
+ * session.
+ */
 typedef struct pj_ice_st_comp
+{
     pj_ice_st           *ice_st;
     unsigned             comp_id;
     pj_uint32_t          options;
     pj_sock_t            sock;
     pj_stun_session     *stun_sess;
     pj_sockaddr          local_addr;
     unsigned             pending_cnt;
     pj_status_t          last_status;
     unsigned             cand_cnt;
     pj_ice_st_cand       cand_list[PJ_ICE_ST_MAX_ALIASES];
     int                  default_cand;
     pj_ioqueue_key_t    *key;
     pj_uint8_t           pkt[1500];
     pj_ioqueue_op_key_t  read_op;
     pj_ioqueue_op_key_t  write_op;
     pj_sockaddr          src_addr;
     int                  src_addr_len;
+    pj_ice_st           *ice_st;        /**< ICE stream transport.      */
+    unsigned             comp_id;       /**< Component ID.              */
+    pj_uint32_t          options;       /**< Option flags.              */
+    pj_sock_t            sock;          /**< Socket descriptor.         */
+    pj_stun_session     *stun_sess;     /**< STUN session.              */
+    pj_sockaddr          local_addr;    /**< Local/base address.        */
+    unsigned             pending_cnt;   /**< Pending resolution cnt.    */
+    pj_status_t          last_status;   /**< Last status.               */
+    unsigned             cand_cnt;      /**< # of candidates/aliaes.    */
+    pj_ice_st_cand       cand_list[PJ_ICE_ST_MAX_CAND]; /**< Cand array */
+    int                  default_cand;  /**< Default candidate selected */
+    pj_ioqueue_key_t    *key;           /**< ioqueue key.               */
+    pj_uint8_t           pkt[1500];     /**< Incoming packet buffer.    */
+    pj_ioqueue_op_key_t  read_op;       /**< ioqueue read operation key */
+    pj_ioqueue_op_key_t  write_op;      /**< ioqueue write op. key      */
+    pj_sockaddr          src_addr;      /**< source packet address buf. */
+    int                  src_addr_len;  /**< length of src addr. buf.   */
 } pj_ice_st_comp;
+/**
+ * This structure represents the ICE stream transport.
+ */
 struct pj_ice_st
+{
+    char                     obj_name[PJ_MAX_OBJ_NAME];
+    pj_pool_t               *pool;
+    void                    *user_data;
+    pj_stun_config           stun_cfg;
+    pj_ice_st_cb             cb;
+    pj_ice                  *ice;
+    unsigned                 comp_cnt;
+    pj_ice_st_comp         **comp;
+    pj_dns_resolver         *resolver;
+    pj_bool_t                has_resolver_job;
+    pj_sockaddr_in           stun_srv;
+    pj_sockaddr_in           turn_srv;
+    char                     obj_name[PJ_MAX_OBJ_NAME]; /**< Log ID.    */
+    pj_pool_t               *pool;      /**< Pool used by this object.  */
+    void                    *user_data; /**< Application data.          */
+    pj_stun_config           stun_cfg;  /**< STUN settings.             */
+    pj_ice_st_cb             cb;        /**< Application callback.      */
+    pj_ice                  *ice;       /**< ICE session.               */
+    unsigned                 comp_cnt;  /**< Number of components.      */
+    pj_ice_st_comp         **comp;      /**< Components array.          */
+    pj_dns_resolver         *resolver;  /**< The resolver instance.     */
+    pj_bool_t                has_rjob;  /**< Has pending resolve?       */
+    pj_sockaddr_in           stun_srv;  /**< STUN server address.       */
+    pj_sockaddr_in           turn_srv;  /**< TURN server address.       */
 };
+/**
+ * Create the ICE stream transport containing the specified number of
+ * components. After the ICE stream transport is created, application
+ * may initialize the STUN server settings, and after that it has to
+ * initialize each components by calling #pj_ice_st_create_comp()
+ * function.
+ *
+ * @param stun_cfg      The STUN settings.
+ * @param name          Optional name for logging identification.
+ * @param comp_cnt      Number of components.
+ * @param user_data     Arbitrary user data to be associated with this
+ *                      ICE stream transport.
+ * @param cb            Callback.
+ * @param p_ice_st      Pointer to receive the ICE stream transport
+ *                      instance.
+ *
+ * @return              PJ_SUCCESS if ICE stream transport is created
+ *                      successfully.
+ */
 PJ_DECL(pj_status_t) pj_ice_st_create(pj_stun_config *stun_cfg,
                                       const char *name,
 …
                                       const pj_ice_st_cb *cb,
                                       pj_ice_st **p_ice_st);
+/**
+ * Destroy the ICE stream transport. This will destroy the ICE session
+ * inside the ICE stream transport, close all sockets and release all
+ * other resources.
+ *
+ * @param ice_st        The ICE stream transport.
+ *
+ * @return              PJ_SUCCESS, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_ice_st_destroy(pj_ice_st *ice_st);
+/**
+ * Set the domain to be used when resolving the STUN servers. If application
+ * wants to utillize STUN, then STUN server must be specified, either by
+ * calling this function or by calling #pj_ice_st_set_stun_srv().
+ *
+ * If application calls this function, then the STUN/TURN servers will
+ * be resolved by querying DNS SRV records for the specified domain.
+ *
+ * @param ice_st        The ICE stream transport.
+ * @param resolver      The resolver instance that will be used to
+ *                      resolve the STUN/TURN servers.
+ * @param domain        The target domain.
+ *
+ * @return              PJ_SUCCESS if DNS SRV resolution job can be
+ *                      started. The resolution process itself will
+ *                      complete asynchronously.
+ */
 PJ_DECL(pj_status_t) pj_ice_st_set_stun_domain(pj_ice_st *ice_st,
                                                pj_dns_resolver *resolver,
                                                const pj_str_t *domain);
+/**
+ * Set the STUN and TURN server addresses. If application
+ * wants to utillize STUN, then STUN server must be specified, either by
+ * calling this function or by calling #pj_ice_st_set_stun_domain().
+ *
+ * With this function, the STUN and TURN server addresses will be
+ * assigned immediately, that is no DNS resolution will need to be
+ * performed.
+ *
+ * @param ice_st        The ICE stream transport.
+ * @param stun_srv      The STUN server address, or NULL if STUN
+ *                      reflexive candidate is not to be used.
+ * @param turn_srv      The TURN server address, or NULL if STUN
+ *                      relay candidate is not to be used.
+ *
+ * @return              PJ_SUCCESS, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_ice_st_set_stun_srv(pj_ice_st *ice_st,
                                             const pj_sockaddr_in *stun_srv,
                                             const pj_sockaddr_in *turn_srv);
+/**
+ * Create and initialize the specified component. This function will
+ * instantiate the socket descriptor for this component, optionally
+ * bind the socket to the specified address (or bind to any address/port
+ * if the \a addr parameter is NULL), and start finding all alias
+ * addresses for this socket. For each alias addresses that if finds,
+ * it will add an ICE stream transport candidate for this component.
+ *
+ * After all components have been initialized, application should poll
+ * the #pj_ice_st_get_comps_status() peridically to check if STUN
+ * server reflexive and relayed candidates have been obtained
+ * successfully.
+ *
+ * @param ice_st        The ICE stream transport.
+ * @param comp_id       The component ID, which value must be greater than
+ *                      zero and less than or equal to the number of
+ *                      components in this ICE stream transport.
+ * @param options       Options, see #pj_ice_st_option.
+ * @param addr          Local address where socket will be bound to. This
+ *                      address will be used as follows:
+ *                      - if the value is NULL, then socket will be bound
+ *                        to any available port.
+ *                      - if the value is not NULL, then if the port number
+ *                        is not zero, it will used as the starting port
+ *                        where the socket will be bound to. If bind() to
+ *                        this port fails, this function will try to bind
+ *                        to port+2, repeatedly until it succeeded.
+ *                        If application doesn't want this function to
+ *                        retry binding the socket to other port, it can
+ *                        specify PJ_ICE_ST_OPT_NO_PORT_RETRY option.
+ *                      - if the value is not NULL, then if the address
+ *                        is not INADDR_ANY, this function will bind the
+ *                        socket to this particular interface only, and
+ *                        no other host candidates will be added for this
+ *                        socket.
+ *
+ *
+ * @return              PJ_SUCCESS, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_ice_st_create_comp(pj_ice_st *ice_st,
                                            unsigned comp_id,
                                            pj_uint32_t options,
                                            const pj_sockaddr_in *addr);
+/**
+ * Manually add a candidate (transport address alias) for the specified
+ * component. Normally application shouldn't need to use this function,
+ * as candidates will be added automatically when component is created
+ * with #pj_ice_st_create_comp().
+ *
+ * @param ice_st        ICE stream transport.
+ * @param comp_id       The component ID.
+ * @param type          The candidate type.
+ * @param local_pref    The local preference for this candidate
+ *                      (typically the value is 65535).
+ * @param addr          The candidate address.
+ * @param set_default   Set to non-zero to make this candidate the
+ *                      default candidate for this component.
+ *
+ * @return              PJ_SUCCESS, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_ice_st_add_cand(pj_ice_st *ice_st,
                                         unsigned comp_id,
 …
                                         pj_bool_t set_default);
+/**
+ * Get the status of components in the ICE stream transports. Since
+ * some IP address candidates have to be obtained asynchronously (for
+ * example, the STUN reflexive or relay candidate), application can
+ * use this function to know whether the address resolution has
+ * completed.
+ *
+ * @param ice_st        The ICE stream transport.
+ *
+ * @return              PJ_SUCCESS if all candidates have been resolved
+ *                      successfully, PJ_EPENDING if transport resolution
+ *                      is still in progress, or other status on failure.
+ */
 PJ_DECL(pj_status_t) pj_ice_st_get_comps_status(pj_ice_st *ice_st);
+/**
+ * Initialize the ICE session in the ICE stream transport.
+ *
+ * @param ice_st        The ICE stream transport.
+ * @param role          ICE role.
+ * @param local_ufrag   Optional local username fragment.
+ * @param local_passwd  Optional local password.
+ *
+ * @return              PJ_SUCCESS, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_ice_st_init_ice(pj_ice_st *ice_st,
                                         pj_ice_role role,
                                         const pj_str_t *local_ufrag,
                                         const pj_str_t *local_passwd);
+/**
+ * Enumerate the local candidates. This function can only be called
+ * after the ICE session has been created in the ICE stream transport.
+ *
+ * @param ice_st        The ICE stream transport.
+ * @param count         On input, it specifies the maximum number of
+ *                      elements. On output, it will be filled with
+ *                      the number of candidates copied to the
+ *                      array.
+ * @param cand          Array of candidates.
+ *
+ * @return              PJ_SUCCESS, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_ice_st_enum_cands(pj_ice_st *ice_st,
                                           unsigned *count,
                                           pj_ice_cand cand[]);
+/**
+ * Start ICE connectivity checks. This function can only be called
+ * after the ICE session has been created in the ICE stream transport.
+ *
+ * This function will pair the local and remote candidates to create
+ * check list. Once the check list is created and sorted based on the
+ * priority, ICE periodic checks will be started. This function will
+ * return immediately, and application will be notified about the
+ * connectivity check status in the callback.
+ *
+ * @param ice_st        The ICE stream transport.
+ * @param rem_ufrag     Remote ufrag, as seen in the SDP received from
+ *                      the remote agent.
+ * @param rem_passwd    Remote password, as seen in the SDP received from
+ *                      the remote agent.
+ * @param rem_cand_cnt  Number of remote candidates.
+ * @param rem_cand      Remote candidate array.
+ *
+ * @return              PJ_SUCCESS, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_ice_st_start_ice(pj_ice_st *ice_st,
                                          const pj_str_t *rem_ufrag,
 …
                                          unsigned rem_cand_cnt,
                                          const pj_ice_cand rem_cand[]);
+/**
+ * Stop and destroy the ICE session inside this media transport.
+ *
+ * @param ice_st        The ICE stream transport.
+ *
+ * @return              PJ_SUCCESS, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pj_ice_st_stop_ice(pj_ice_st *ice_st);
+/**
+ * Send outgoing packet using this transport. If ICE checks have not
+ * produced a valid check for the specified component ID, this function
+ * will return with failure. Otherwise it will send the packet to remote
+ * destination using the nominated local candidate as have been checked
+ * previously.
+ *
+ * @param ice_st        The ICE stream transport.
+ * @param comp_id       Component ID.
+ * @param data          The data or packet to be sent.
+ * @param data_len      Size of data or packet, in bytes.
+ * @param dst_addr      The destination address.
+ * @param dst_addr_len  Length of destination address.
+ *
+ * @return              PJ_SUCCESS if data is sent successfully.
+ */
 PJ_DECL(pj_status_t) pj_ice_st_sendto(pj_ice_st *ice_st,
                                       unsigned comp_id,

pjproject/trunk/pjnath/include/pjnath/stun_auth.h

-                      r1089
+                      r1110
 /**
  * @defgroup PJNATH_STUN_AUTH STUN Authentication
+ * @brief STUN authentication helper
  * @ingroup PJNATH_STUN
  * @{
 …
+/* Calculate HMAC-SHA1 key for long term credential, by getting
+/**
+ * Calculate HMAC-SHA1 key for long term credential, by getting
  * MD5 digest of username, realm, and password.
+ *
+ * @param digest    The buffer for the digest.
+ * @param realm     The realm of the credential, if long term credential
+ *                  is to be used.
+ * @param username  The username.
+ * @param passwd    The clear text password.
  */
 void pj_stun_calc_md5_key(pj_uint8_t digest[16],

pjproject/trunk/pjnath/include/pjnath/stun_msg.h

-                      r1101
+                      r1110
  */
-/**
- * The default initial STUN round-trip time estimation (the RTO value
- * in RFC 3489-bis), in miliseconds.
- * This value is used to control the STUN request
- * retransmit time. The initial value of retransmission interval
- * would be set to this value, and will be doubled after each
- * retransmission.
- */
-#ifndef PJ_STUN_RTO_VALUE
-#   define PJ_STUN_RTO_VALUE                100
-#endif
-/**
- * The STUN transaction timeout value, in miliseconds.
- * After the last retransmission is sent and if no response is received
- * after this time, the STUN transaction will be considered to have failed.
+ *
- * The default value is 1600 miliseconds (as per RFC 3489-bis).
- */
-#ifndef PJ_STUN_TIMEOUT_VALUE
-#   define PJ_STUN_TIMEOUT_VALUE            1600
-#endif
-/**
- * Maximum number of STUN retransmission count.
+ *
- * Default: 7 (as per RFC 3489-bis)
- */
-#ifndef PJ_STUN_MAX_RETRANSMIT_COUNT
-#   define PJ_STUN_MAX_RETRANSMIT_COUNT     7
-#endif
-/**
- * Maximum size of STUN message.
- */
-#ifndef PJ_STUN_MAX_PKT_LEN
-#   define PJ_STUN_MAX_PKT_LEN              512
-#endif
-/**
- * Default STUN port as defined by RFC 3489.
- */
-#define PJ_STUN_PORT                        3478
 /**

pjproject/trunk/pjnath/include/pjnath/stun_session.h

-                      r1106
+                      r1110
 #ifndef __PJNATH_STUN_SESSION_H__
 #define __PJNATH_STUN_SESSION_H__
+/**
+ * @file stun_session.h
+ * @brief STUN session management for client/server.
+ */
 #include <pjnath/stun_msg.h>
 …
+ *
  * @param sess      The STUN session instance.
+ * @param user_data The user data.
+ *
  * @return          PJ_SUCCESS on success, or the appropriate error code.
 …
  * the message via one of the pj_stun_session_cb callback.
+ *
+ * @param sess       The STUN session instance.
+ * @param packet     The packet containing STUN message.
+ * @param pkt_size   Size of the packet.
+ * @param options    Options, from #pj_stun_decode_options.
+ * @param parsed_len Optional pointer to receive the size of the parsed
+ *                   STUN message (useful if packet is received via a
+ *                   stream oriented protocol).
+ *
+ * @return           PJ_SUCCESS on success, or the appropriate error code.
+ * @param sess          The STUN session instance.
+ * @param packet        The packet containing STUN message.
+ * @param pkt_size      Size of the packet.
+ * @param options       Options, from #pj_stun_decode_options.
+ * @param parsed_len    Optional pointer to receive the size of the parsed
+ *                      STUN message (useful if packet is received via a
+ *                      stream oriented protocol).
+ * @param src_addr      The source address of the packet.
+ * @param src_addr_len  Length of the source address.
+ *
+ * @return              PJ_SUCCESS on success, or the appropriate error code.
  */
 PJ_DECL(pj_status_t) pj_stun_session_on_rx_pkt(pj_stun_session *sess,

pjproject/trunk/pjnath/include/pjnath/stun_transaction.h

-                      r1091
+                      r1110
+ *
  * @param tsx           The STUN client transaction instance.
+ * @param packet        The incoming packet.
+ * @param pkt_size      Size of the incoming packet.
+ * @param parsed_len    Optional pointer to receive the number of bytes
+ *                      that have been parsed from the incoming packet
+ *                      for the STUN message. This is useful if the
+ *                      STUN transaction is running over stream oriented
+ *                      socket such as TCP or TLS.
+ * @param msg           The incoming STUN message.
+ *
  * @return              PJ_SUCCESS on success or the appropriate error code.

pjproject/trunk/pjnath/include/pjnath/types.h

-                      r1101
+                      r1110
 /**
  * @defgroup PJNATH NAT Helper Library
+ * @defgroup PJNATH NAT Traversal Helper Library
  * @{
  */
 …
 /**
+ * @mainpage NAT Helper Library
+ *
+ * \n
+ * \n
+ * \n
+ * This is the documentation of PJNATH, an auxiliary library providing
+ * NAT helper functionalities such as STUN and ICE.
+ *
+ * Please go to the <A HREF="modules.htm"><B>Modules</B></A> page for list
+ * of modules.
+ *
+ * @mainpage PJNATH - Open Source STUN, TURN, and ICE Library
+ *
+ * \n
+ * This is the documentation of PJNATH, an Open Source library providing
+ * NAT traversal helper functionalities by using standard based protocols
+ * such as:
+ *  - <b>STUN</b> (Session Traversal Utilities),
+ *  - <b>TURN</b> (Obtaining Relay Addresses from STUN)
+ *  - <b>ICE</b> (Interactive Connectivity Establishment).
+ *
+ * The following sections will give a short overview about the protocols
+ * supported by this library, and how they are implemented in PJNATH.
+ *
+ * \n
+ * \section PJNATH_STUN STUN Protocol Library
+ *
+ * Session Traversal Utilities (STUN, or previously known as Simple
+ * Traversal of User Datagram Protocol (UDP) Through Network Address
+ * Translators (NAT)s), was previously released as IETF standard
+ * <A HREF="http://www.ietf.org/rfc/rfc3489.txt">RFC 3489</A>, but since
+ * then it has been revised into the following:
+ *  - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-rfc3489bis-06.txt">
+ *    <B>draft-ietf-behave-rfc3489bis-06</b></A> for the main STUN
+ *    specification,
+ *  - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-turn-03.txt">
+ *    <B>draft-ietf-behave-turn-03</B></A> for TURN usage of STUN,
+ *  - and several other drafts explaining other STUN usages.
+ *
+ * The PJNATH library provides facilities to support both the core
+ * <B>STUN-bis</B> specification and the <B>TURN</B> usage of STUN,
+ * as well as other STUN usages. Please see #pj_stun_attr_type for
+ * list of STUN attributes supported by this library.
+ *
+ *
+ * The following are some design principles that have been utilized
+ * when implementing the STUN library in PJNATH:
+ *
+ *  - layered architecture, with \ref PJNATH_STUN_MSG as the lowest
+ *    layer and \ref PJNATH_STUN_SESSION as the highest abstraction
+ *    layer, to accommodate various usage scenario of the library.
+ *
+ *  - no transport -- the STUN library is pretty much transport
+ *    independent and all sending and receiving functionalities will
+ *    have to be implemented by application or higher level
+ *    abstraction (such as ICE). This helps facilitating an even
+ *    more usage scenarios of the library.
+ *
+ *  - common functionalities for both STUN client and server
+ *    development. All STUN components can be used to develop both
+ *    STUN client and STUN server application, and in fact, in ICE,
+ *    both STUN client and server functionality exist in a single
+ *    ICE session.
+ *
+ * \n
+ *
+ * \subsection PJNATH_STUN_ARCH STUN Library Organization
+ *
+ \verbatim
+    +-----------------------------------------------------------------+
+    |                                                                 |
+    |                   A P P L I C A T I O N                         |
+    |                                                                 |
+    +-----------------------------------------------------------------+
+         ^                          ^
+         |                          |
+         v                          v
+    +--------+    +-----------------------------------+    +----------+
+    |        |    |                                   |    |          |
+    |  Appl- |<-->|      S T U N   S E S S I O N      |<-->| S T U N  |
+    | ication|    |                                   |    |  Authen- |
+    | Trans- |    +-----------------------------------+    | tication |
+    |  port  |    |                                   |    |          |
+    |        |<-->|  S T U N   T R A N S A C T I O N  |    +----------+
+    |        |    |                                   |
+    |        |    +-----------------------------------+
+    |        |    |                                   |
+    |        |    |    STUN MESSAGE REPRESENTATION    |
+    +--------+    |            AND PARSING            |
+                  +-----------------------------------+
+ \endverbatim
+ * The STUN library is organized as follows:
+ *
+ *  - the lowest layer of the library is \ref PJNATH_STUN_MSG. This layer
+ *    provides STUN message representation, validation, parsing, and
+ *    debugging (dump to log) of STUN messages.
+ *
+ *  - for client, the next higher layer is \ref PJNATH_STUN_TRANSACTION,
+ *    which manages retransmissions of STUN request.
+ *
+ *  - \ref PJNATH_STUN_AUTH provides mechanism to verify STUN
+ *    credential in incoming STUN messages.
+ *
+ *  - for both client and server, the next higher abstraction is
+ *    \ref PJNATH_STUN_SESSION, which provides management of incoming
+ *    and outgoing messages and association of STUN credential to
+ *    a STUN session.
+ *
+ * As mentioned previously, all STUN library components are independent
+ * of any transports. Application gives incoming packet
+ * to the STUN components for processing. and it must supply the STUN
+ * components with callback to send outgoing messages.
+ *
+ * \n
+ *
+ * \section PJNATH_ICE ICE Implementation
+ *
+ * Interactive Connectivity Establishment (ICE) is a standard based
+ * methodology for traversing Network Address Translator (NAT), and
+ * is described in
+ * <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-mmusic-ice-14.txt">
+ * <B>draft-ietf-mmusic-ice-14.txt</B></A> draft. The PJNATH ICE
+ * implementation is aimed to provide a usable and generic ICE transports
+ * for different types of application, including but not limited to
+ * the usage of ICE in SIP/SDP offer/answer.
+ *
+ * \subsection PJNATH_ICE_ARCH ICE Library Organization
+ *
+ * The ICE library is organized as follows:
+ *
+ *  - the lowest layer is \ref PJNATH_ICE_SESSION, which provides
+ *    ICE management and negotiation in a transport-independent way.
+ *    This layer contains the state machines to perform ICE
+ *    negotiation, and provides the most flexibility to control all
+ *    aspects of ICE session. This layer normally is only usable for
+ *    ICE implementors.
+ *
+ *  - higher in the hierarchy is \ref PJNATH_ICE_STREAM_TRANSPORT,
+ *    which binds ICE with UDP sockets, and provides STUN binding
+ *    and relay/TURN allocation for the sockets. This component can
+ *    be directly used by application, although normally application
+ *    should use the next higher abstraction below since it provides
+ *    SDP translations and better integration with other PJ libraries
+ *    such as PJSIP and PJMEDIA.
+ *
+ *  - the highest abstraction is ICE media transport, which maintains
+ *    ICE stream transport and provides SDP translations to be used
+ *    for SIP offer/answer exchanges.
+ */
+/**
+ * @defgroup PJNATH_STUN STUN Library
+ * @brief Open source STUN library
+ *
+ * This module contains implementation of STUN library in PJNATH -
+ * the open source NAT helper containing STUN and ICE.
  */

pjproject/trunk/pjnath/src/pjnath/ice.c

-                      r1106
+                      r1110
+    }
     /* If there's no relayed candidate, find server reflexive candidate */
+    /* If there's no relayed candidate, find reflexive candidate */
     for (i=0; i<ice->lcand_cnt; ++i) {
         pj_ice_cand *lcand = &ice->lcand[i];
         if (lcand->comp_id==comp_id &&
+            lcand->type == PJ_ICE_CAND_TYPE_SRFLX)
+            (lcand->type == PJ_ICE_CAND_TYPE_SRFLX ||
+             lcand->type == PJ_ICE_CAND_TYPE_PRFLX))
+        {
             *cand_id = GET_LCAND_ID(lcand);
 …
         /* Call callback */
+        (*ice->cb.on_ice_complete)(ice, status);
+        if (ice->cb.on_ice_complete) {
+            (*ice->cb.on_ice_complete)(ice, status);
+        }
+    }
+}

pjproject/trunk/pjnath/src/pjnath/ice_stream_transport.c

-                      r1106
+                      r1110
     PJ_ASSERT_RETURN(ice_st, PJ_EINVAL);
     /* Must not have pending resolver job */
     PJ_ASSERT_RETURN(ice_st->has_resolver_job==PJ_FALSE, PJ_EINVALIDOP);
+    PJ_ASSERT_RETURN(ice_st->has_rjob==PJ_FALSE, PJ_EINVALIDOP);
     if (stun_srv) {
 …
     PJ_ASSERT_RETURN(ice_st && comp && addr, PJ_EINVAL);
     PJ_ASSERT_RETURN(comp->cand_cnt < PJ_ICE_ST_MAX_ALIASES, PJ_ETOOMANY);
+    PJ_ASSERT_RETURN(comp->cand_cnt < PJ_ICE_ST_MAX_CAND, PJ_ETOOMANY);
     cand = &comp->cand_list[comp->cand_cnt];
 …
     cand->status = PJ_SUCCESS;
     pj_memcpy(&cand->addr, addr, sizeof(pj_sockaddr_in));
     cand->cand_id = -1;
+    cand->ice_cand_id = -1;
     cand->local_pref = local_pref;
     cand->foundation = calc_foundation(ice_st->pool, type, &addr->sin_addr);
 …
         /* Socket is bound to INADDR_ANY */
         unsigned i, ifs_cnt;
         pj_in_addr ifs[PJ_ICE_ST_MAX_ALIASES-2];
+        pj_in_addr ifs[PJ_ICE_ST_MAX_CAND-2];
         /* Reset default candidate */
 …
             PJ_TODO(DISTINGUISH_BETWEEN_LOCAL_AND_RELAY);
             status = pj_ice_on_rx_pkt(ice_st->ice, comp->comp_id,
                                       comp->cand_list[0].cand_id,
+                                      comp->cand_list[0].ice_cand_id,
                                       comp->pkt, bytes_read,
                                       &comp->src_addr, comp->src_addr_len);
 …
     /* Bail out if STUN server is still being resolved */
     if (ice_st->has_resolver_job)
+    if (ice_st->has_rjob)
         return PJ_EBUSY;
 …
     cand->type = PJ_ICE_CAND_TYPE_SRFLX;
     cand->status = PJ_EPENDING;
     cand->cand_id = -1;
+    cand->ice_cand_id = -1;
     cand->local_pref = 65535;
     cand->foundation = calc_foundation(ice_st->pool, PJ_ICE_CAND_TYPE_SRFLX,
 …
     /* Can't add new component while resolver is running */
     PJ_ASSERT_RETURN(ice_st->has_resolver_job == PJ_FALSE, PJ_EBUSY);
+    PJ_ASSERT_RETURN(ice_st->has_rjob == PJ_FALSE, PJ_EBUSY);
 …
                                      &cand->addr, &comp->local_addr, NULL,
                                      sizeof(pj_sockaddr_in),
                                      (unsigned*)&cand->cand_id);
+                                     (unsigned*)&cand->ice_cand_id);
             if (status != PJ_SUCCESS)
                 goto on_error;
 …
         unsigned j;
         for (j=0; j<ice_st->comp[i]->cand_cnt; ++j) {
             ice_st->comp[i]->cand_list[j].cand_id = -1;
+            ice_st->comp[i]->cand_list[j].ice_cand_id = -1;
+        }
+    }
 …
+    }
+#if 1
+    PJ_UNUSED_ARG(pkt_size);
+    PJ_UNUSED_ARG(status);
+    /* Otherwise return error */
+    return PJNATH_EICEINPROGRESS;
+#else
     /* Otherwise send direcly with the socket */
     pkt_size = data_len;
 …
     return (status==PJ_SUCCESS||status==PJ_EPENDING) ? PJ_SUCCESS : status;
+#endif
+}

Context Navigation

Legend:

pjproject/trunk/pjlib/src/pj/ip_helper_win32.c

pjproject/trunk/pjnath/build/pjnath.dsp

pjproject/trunk/pjnath/docs

pjproject/trunk/pjnath/include/pjnath/config.h

pjproject/trunk/pjnath/include/pjnath/errno.h

pjproject/trunk/pjnath/include/pjnath/ice.h

pjproject/trunk/pjnath/include/pjnath/ice_stream_transport.h

pjproject/trunk/pjnath/include/pjnath/stun_auth.h

pjproject/trunk/pjnath/include/pjnath/stun_msg.h

pjproject/trunk/pjnath/include/pjnath/stun_session.h

pjproject/trunk/pjnath/include/pjnath/stun_transaction.h

pjproject/trunk/pjnath/include/pjnath/types.h

pjproject/trunk/pjnath/src/pjnath/ice.c

pjproject/trunk/pjnath/src/pjnath/ice_stream_transport.c

Download in other formats: