Changeset 2705 for pjproject/branches/projects/sipit24/pjnath/include/pjnath/ice_session.h

Timestamp:

May 17, 2009 5:57:19 PM (15 years ago)

Author:

bennylp

Message:

Ticket #851: initial code to support regular nomination in ICE:

• Added option to change nomination strategy in ICE strans and session. Default is still aggressive.
• Added option to control nomination timer
• Renamed no_host_cand to max_host_cands in ICE config
• Updated icedemo
• Also added timer for controlled agent to wait for nomination from controlling agent

File:

• pjproject/branches/projects/sipit24/pjnath/include/pjnath/ice_session.h (modified) (5 diffs)

pjproject/branches/projects/sipit24/pjnath/include/pjnath/ice_session.h

@@ -177 +177 @@
 {
     /**
-     * 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.
+     * Pointer to ICE check with highest priority which connectivity check
+     * has been successful. The value will be NULL if a no successful check
+     * has not been found for this component.
      */
     pj_ice_sess_check   *valid_check;
+
+    /**
+     * Pointer to ICE check with highest priority which connectivity check
+     * has been successful and it has been nominated. The value may be NULL
+     * if there is no such check yet.
+     */
+    pj_ice_sess_check   *nominated_check;
 
     /**
@@ -554 +561 @@
 
 /**
+ * This structure describes various ICE session options. Application
+ * configure the ICE session with these options by calling 
+ * #pj_ice_sess_set_options().
+ */
+typedef struct pj_ice_sess_options
+{
+    /**
+     * Specify whether to use aggressive nomination.
+     */
+    pj_bool_t           aggressive;
+
+    /**
+     * For controlling agent if it uses regular nomination, specify the delay
+     * to perform nominated check (connectivity check with USE-CANDIDATE 
+     * attribute) after all components have a valid pair.
+     *
+     * Default value is PJ_ICE_NOMINATED_CHECK_DELAY.
+     */
+    unsigned            nominated_check_delay;
+
+    /**
+     * For a controlled agent, specify how long it wants to wait (in 
+     * milliseconds) for the controlling agent to complete sending 
+     * connectivity check with nominated flag set to true for all components
+     * after the controlled agent has found that all connectivity checks in
+     * its checklist have been completed and there is at least one successful
+     * (but not nominated) check for every component.
+     *
+     * Default value for this option is 
+     * ICE_CONTROLLED_AGENT_WAIT_NOMINATION_TIMEOUT. Specify -1 to disable
+     * this timer.
+     */
+    int                 controlled_agent_want_nom_timeout;
+
+} pj_ice_sess_options;
+
+
+/**
  * This structure describes the ICE session. For this version of PJNATH,
  * an ICE session corresponds to a single media stream (unlike the ICE
@@ -570 +615 @@
     pj_mutex_t          *mutex;                     /**< Mutex.             */
     pj_ice_sess_role     role;                      /**< ICE role.          */
+    pj_ice_sess_options  opt;                       /**< Options            */
     pj_timestamp         tie_breaker;               /**< Tie breaker value  */
     pj_uint8_t          *prefs;                     /**< Type preference.   */
+    pj_bool_t            is_nominating;             /**< Nominating stage   */
     pj_bool_t            is_complete;               /**< Complete?          */
     pj_status_t          ice_status;                /**< Error status.      */
-    pj_timer_entry       completion_timer;          /**< To call callback.  */
+    pj_timer_entry       timer;                     /**< ICE timer.         */
     pj_ice_sess_cb       cb;                        /**< Callback.          */
 
@@ -655 +702 @@
                                      const pj_sockaddr *base_addr);
 
+/**
+ * Initialize ICE session options with library default values.
+ *
+ * @param opt           ICE session options.
+ */
+PJ_DECL(void) pj_ice_sess_options_default(pj_ice_sess_options *opt);
 
 /**
@@ -690 +743 @@
 
 /**
+ * Get the value of various options of the ICE session.
+ *
+ * @param ice           The ICE session.
+ * @param opt           The options to be initialized with the values
+ *                      from the ICE session.
+ *
+ * @return              PJ_SUCCESS on success, or the appropriate error.
+ */
+PJ_DECL(pj_status_t) pj_ice_sess_get_options(pj_ice_sess *ice,
+                                             pj_ice_sess_options *opt);
+
+/**
+ * Specify various options for this ICE session. Application MUST only
+ * call this function after the ICE session has been created but before
+ * any connectivity check is started.
+ *
+ * Application should call #pj_ice_sess_get_options() to initialize the
+ * options with their default values.
+ *
+ * @param ice           The ICE session.
+ * @param opt           Options to be applied to the ICE session.
+ *
+ * @return              PJ_SUCCESS on success, or the appropriate error.
+ */
+PJ_DECL(pj_status_t) pj_ice_sess_set_options(pj_ice_sess *ice,
+                                             const pj_ice_sess_options *opt);
+
+/**
  * Destroy ICE session. This will cancel any connectivity checks currently
  * running, if any, and any other events scheduled by this session, as well