Changeset 5969 for pjproject/trunk/pjsip/include/pjsua2/presence.hpp

Timestamp:

Apr 15, 2019 10:52:16 AM (5 years ago)

Author:

nanang

Message:

Close #2189: fixed PJSUA2 thread safety issue in list of objects manipulation.

File:

• pjproject/trunk/pjsip/include/pjsua2/presence.hpp (modified) (5 diffs)

pjproject/trunk/pjsip/include/pjsua2/presence.hpp

@@ -169 +169 @@
      */
     PresenceStatus       presStatus;
-    
+
 public:
     /** Import from pjsip structure */
@@ -189 +189 @@
 
 /**
- * Buddy.
+ * Buddy. This is a lite wrapper class for PJSUA-LIB buddy, i.e: this class
+ * only maintains one data member, PJSUA-LIB buddy ID, and the methods are
+ * simply proxies for PJSUA-LIB buddy operations.
+ *
+ * Application can use create() to register a buddy to PJSUA-LIB, and
+ * the destructor of the original instance (i.e: the instance that calls
+ * create()) will unregister and delete the buddy from PJSUA-LIB. Application
+ * must delete all Buddy instances belong to an account before shutting down
+ * the account (via Account::shutdown()).
+ *
+ * The library will not keep a list of Buddy instances, so any Buddy (or
+ * descendant) instances instantiated by application must be maintained
+ * and destroyed by the application itself. Any PJSUA2 APIs that return Buddy
+ * instance(s) such as Account::enumBuddies2() or Account::findBuddy2() will
+ * just return generated copy. All Buddy methods should work normally on this
+ * generated copy instance.
  */
 class Buddy
@@ -200 +215 @@
     
     /**
-     * Destructor. Note that if the Buddy instance is deleted, it will also
-     * delete the corresponding buddy in the PJSUA-LIB.
+     * Destructor. Note that if the Buddy original instance (i.e: the instance
+     * that calls Buddy::create()) is destroyed, it will also delete the
+     * corresponding buddy in the PJSUA-LIB. While the destructor of
+     * a generated copy (i.e: Buddy instance returned by PJSUA2 APIs such as
+     * Account::enumBuddies2() or Account::findBuddy2()) will do nothing.
      */
     virtual ~Buddy();
@@ -207 +225 @@
     /**
      * Create buddy and register the buddy to PJSUA-LIB.
+     *
+     * Note that application should maintain the Buddy original instance, i.e:
+     * the instance that calls this create() method as it is only the original
+     * instance destructor that will delete the underlying Buddy in PJSUA-LIB.
      *
      * @param acc               The account for this buddy.
@@ -298 +320 @@
       * Buddy ID.
       */
-     pjsua_buddy_id      id;
-     
-     /**
-      * Account.
-      */
-     Account            *acc;
-};
-
+    pjsua_buddy_id       id;
+
+private:
+    friend class Endpoint;
+    friend class Account;
+
+    /* Internal constructor/methods used by Endpoint and Account */
+    Buddy(pjsua_buddy_id buddy_id);
+    Buddy *getOriginalInstance();
+};
+
+
+/**
+ * Warning: deprecated, use BuddyVector2 instead.
+ *
+ * Array of buddies.
+ */
+typedef std::vector<Buddy*> BuddyVector;
 
 /** Array of buddies */
-typedef std::vector<Buddy*> BuddyVector;
+typedef std::vector<Buddy> BuddyVector2;