Changeset 6037 for pjproject/trunk/pjsip/include/pjsip/sip_dialog.h

Timestamp:

Jul 10, 2019 7:15:08 AM (5 years ago)

Author:

riza

Message:

Close #2211: Use group lock for SIP dialog.

File:

• pjproject/trunk/pjsip/include/pjsip/sip_dialog.h (modified) (4 diffs)

pjproject/trunk/pjsip/include/pjsip/sip_dialog.h

@@ -142 +142 @@
     char                obj_name[PJ_MAX_OBJ_NAME];  /**< Standard id.       */
     pj_pool_t          *pool;       /**< Dialog's pool.                     */
-    pj_mutex_t         *mutex_;     /**< Dialog's mutex. Do not call!!
-                                         Use pjsip_dlg_inc_lock() instead!  */
     pjsip_user_agent   *ua;         /**< User agent instance.               */
     pjsip_endpoint     *endpt;      /**< Endpoint instance.                 */
+    pj_grp_lock_t      *grp_lock_;  /**< Dialog's grp lock. Do not call!!
+                                         Use pjsip_dlg_inc_lock() instead!  */
 
     /** The dialog set which this dialog belongs (opaque type). */
@@ -192 +192 @@
     const void         *via_tp;     /**< Via transport.                     */
 };
+
+/**
+ * The parameter for \a pjsip_dlg_create_uac2().
+ */
+typedef struct pjsip_dlg_create_uac_param {
+    /**
+     * The user agent module instance.
+     */
+    pjsip_user_agent *ua;
+
+    /**
+     * Dialog local URI (i.e. From header).
+     */
+    pj_str_t local_uri;
+
+    /**
+     * Optional dialog local Contact to be put as Contact header value,
+     * hence the format must follow RFC 3261 Section 20.10:
+     * When the header field value contains a display name, the URI including
+     * all URI parameters is enclosed in "<" and ">".  If no "<" and ">" are
+     * present, all parameters after the URI are header parameters, not
+     * URI parameters.  The display name can be tokens, or a quoted string,
+     * if a larger character set is desired. If this argument is NULL,
+     * the Contact will be taken from the local URI.
+     */
+    pj_str_t local_contact;
+
+    /**
+     * Dialog remote URI (i.e. To header).
+     */
+    pj_str_t remote_uri;
+
+    /**
+     * Optional initial remote target. If this argument is NULL, the initial 
+     * target will be set to remote URI.
+     */
+    pj_str_t target;
+
+    /**
+     * Optional group lock to use by this dialog. If the value is NULL, 
+     * the dialog will create its own group lock.
+     */
+    pj_grp_lock_t *grp_lock;
+
+} pjsip_dlg_create_uac_param;
 
 
@@ -249 +294 @@
                                            pjsip_dialog **p_dlg);
 
+/**
+ * Variant of pjsip_dlg_create_uac() with additional parameter to specify
+ * the group lock to use. Group lock can be used to synchronize locking
+ * among several objects to prevent deadlock, and to synchronize the
+ * lifetime of objects sharing the same group lock.
+ *
+ * See \a pjsip_dlg_create_uac() for general info about this function.
+ *
+ * @param param             The parameter, refer to
+ *                          \a pjsip_dlg_create_uac_param
+ * @param p_dlg             Pointer to receive the dialog.
+ *
+ * @return                  PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjsip_dlg_create_uac2(
+                                const pjsip_dlg_create_uac_param *create_param,
+                                pjsip_dialog **p_dlg);
+
 
 #if !DEPRECATED_FOR_TICKET_1902
@@ -539 +602 @@
 PJ_DECL(void) pjsip_dlg_dec_lock( pjsip_dialog *dlg );
 
+/**
+ * Get the group lock for the SIP dialog. Note that prior to calling this
+ * method, it is recommended to hold reference to the dialog
+ * (e.g: call #pjsip_dlg_inc_session() or #pjsip_dlg_inc_lock()).
+ *
+ * @param dlg               The dialog.
+ *
+ * @return                  The group lock.
+ */
+PJ_DECL(pj_grp_lock_t *) pjsip_dlg_get_lock( pjsip_dialog *dlg );
+
 
 /**