Changeset 1988 for pjproject/trunk/pjnath/include/pjnath/stun_session.h

Timestamp:

Jun 6, 2008 2:47:10 PM (16 years ago)

Author:

bennylp

Message:

Major major modifications related to ticket #485 (support for TURN-07):

• Added STUN socket transport pj_stun_sock
• Integration of TURN-07 to ICE
• Major refactoring in ICE stream transport to make it simpler
• Major modification (i.e. API change) in almost everywhere else
• Much more elaborate STUN, TURN, and ICE tests in pjnath-test

File:

• pjproject/trunk/pjnath/include/pjnath/stun_session.h (modified) (11 diffs)

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

@@ -214 +214 @@
 struct pj_stun_tx_data
 {
+    /** PJLIB list interface */
     PJ_DECL_LIST_MEMBER(struct pj_stun_tx_data);
 
@@ -238 +239 @@
     pj_timer_entry       res_timer;     /**< Response cache timer.          */
 };
+
+
+/**
+ * These are the flags to control the message logging in the STUN session.
+ */
+typedef enum pj_stun_sess_msg_log_flag
+{
+    PJ_STUN_SESS_LOG_TX_REQ=1,  /**< Log outgoing STUN requests.    */
+    PJ_STUN_SESS_LOG_TX_RES=2,  /**< Log outgoing STUN responses.   */
+    PJ_STUN_SESS_LOG_TX_IND=4,  /**< Log outgoing STUN indications. */
+
+    PJ_STUN_SESS_LOG_RX_REQ=8,  /**< Log incoming STUN requests.    */
+    PJ_STUN_SESS_LOG_RX_RES=16, /**< Log incoming STUN responses    */
+    PJ_STUN_SESS_LOG_RX_IND=32  /**< Log incoming STUN indications  */
+} pj_stun_sess_msg_log_flag;
 
 
@@ -259 +275 @@
 
 /**
- * Destroy the STUN session.
- *
- * @param sess      The STUN session instance.
- *
- * @return          PJ_SUCCESS on success, or the appropriate error code.
+ * Destroy the STUN session and all objects created in the context of
+ * this session.
+ *
+ * @param sess      The STUN session instance.
+ *
+ * @return          PJ_SUCCESS on success, or the appropriate error code.
+ *                  This function will return PJ_EPENDING if the operation
+ *                  cannot be performed immediately because callbacks are
+ *                  being called; in this case the session will be destroyed
+ *                  as soon as the last callback returns.
  */
 PJ_DECL(pj_status_t) pj_stun_session_destroy(pj_stun_session *sess);
@@ -334 +355 @@
                                                 pj_stun_auth_type auth_type,
                                                 const pj_stun_auth_cred *cred);
+/**
+ * Configure message logging. By default all flags are enabled.
+ *
+ * @param sess      The STUN session instance.
+ * @param flags     Bitmask combination of #pj_stun_sess_msg_log_flag
+ */
+PJ_DECL(void) pj_stun_session_set_log(pj_stun_session *sess,
+                                      unsigned flags);
 
 /**
@@ -382 +411 @@
  *
  * @param sess      The STUN session instance.
- * @param req       The STUN request where the response is to be created.
+ * @param rdata     The STUN request where the response is to be created.
  * @param err_code  Error code to be set in the response, if error response
  *                  is to be created, according to pj_stun_status enumeration.
@@ -433 +462 @@
  *
  * @return          PJ_SUCCESS on success, or the appropriate error code.
+ *                  This function will return PJNATH_ESTUNDESTROYED if 
+ *                  application has destroyed the session in 
+ *                  \a on_send_msg() callback.
  */
 PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess,
@@ -450 +482 @@
  * @param sess      The STUN session instance.
  * @param rdata     The STUN request message to be responded.
- * @param err_code  Error code to be set in the response, if error response
+ * @param code      Error code to be set in the response, if error response
  *                  is to be created, according to pj_stun_status enumeration.
  *                  This argument MUST be zero if successful response is
@@ -473 +505 @@
  *
  * @return          PJ_SUCCESS on success, or the appropriate error code.
+ *                  This function will return PJNATH_ESTUNDESTROYED if 
+ *                  application has destroyed the session in 
+ *                  \a on_send_msg() callback.
  */
 PJ_DECL(pj_status_t) pj_stun_session_respond(pj_stun_session *sess, 
@@ -497 +532 @@
  *
  * @return          PJ_SUCCESS if transaction is successfully cancelled.
+ *                  This function will return PJNATH_ESTUNDESTROYED if 
+ *                  application has destroyed the session in 
+ *                  \a on_request_complete() callback.
  */
 PJ_DECL(pj_status_t) pj_stun_session_cancel_req(pj_stun_session *sess,
@@ -512 +550 @@
  *
  * @return          PJ_SUCCESS on success, or the appropriate error.
+ *                  This function will return PJNATH_ESTUNDESTROYED if 
+ *                  application has destroyed the session in \a on_send_msg()
+ *                  callback.
  */
 PJ_DECL(pj_status_t) pj_stun_session_retransmit_req(pj_stun_session *sess,
@@ -549 +590 @@
  *
  * @return              PJ_SUCCESS on success, or the appropriate error code.
+ *                      This function will return PJNATH_ESTUNDESTROYED if 
+ *                      application has destroyed the session in one of the
+ *                      callback.
  */
 PJ_DECL(pj_status_t) pj_stun_session_on_rx_pkt(pj_stun_session *sess,