Changes between Version 1 and Version 2 of pjsip-doc/presence

Timestamp:

Dec 4, 2013 5:54:11 AM (11 years ago)

Author:

ming

Comment:

--

pjsip-doc/presence

@@ -5 +5 @@
 ================
 This class represents a remote buddy (a person, or a SIP endpoint).
-To use the Buddy class, application DOES NOT need to subclass it unless application wants to get the notifications on buddy state change.
 
-Subscribe to Buddy's Presence Status
----------------------------------------------------------
-To subscribe to buddy's presence status, you need to add a buddy object, install callback to handle buddy's event, and start subscribing to buddy's presence status. The snippet below shows a sample code to achieve these::
+Subclassing the Buddy class
+----------------------------
+To use the Buddy class, normally application SHOULD create its own subclass, such as::
 
-  class MyBuddyCallback(pjsua.BuddyCallback):
-    def __init__(self, buddy=None):
-        pjsua.BuddyCallback.__init__(self, buddy)
+    class MyBuddy : public Buddy
+    {
+    public:
+        MyBuddy() {}
+        ~MyBuddy() {}
 
-    def on_state(self):
-        print "Buddy", self.buddy.info().uri, "is",
-        print self.buddy.info().online_text
+        virtual void onBuddyState();
+    };
 
-  try:
-    uri = '"Alice" <sip:alice@example.com>'
-    buddy = acc.add_buddy(uri, cb=MyBuddyCallback())
-    buddy.subscribe()
+In its subclass, application can implement the buddy callback to get the notifications on buddy state change.
 
-  except pjsua.Error, err:
-    print 'Error adding buddy:', err
+Subscribing to Buddy's Presence Status
+---------------------------------------
+To subscribe to buddy's presence status, you need to add a buddy object and subscribe to buddy's presence status. The snippet below shows a sample code to achieve these::
 
-For more information please see ​Buddy class and ​BuddyCallback class reference documentation.
+    BuddyConfig cfg;
+    cfg.uri = "sip:alice@example.com";
+    MyBuddy buddy;
+    try {
+        buddy.create(*acc, cfg);
+        buddy.subscribePresence(true);
+    } catch(Error& err) {
+    }
+
+Then you can get the buddy's presence state change inside the onBuddyState() callback::
+
+    void MyBuddy::onBuddyState()
+    {
+        BuddyInfo bi = getInfo();
+        cout << "Buddy " << bi.uri << " is " << bi.presStatus.statusText << endl;
+    }
+
+For more information, please see ​Buddy class reference documentation.
 
 Responding to Presence Subscription Request
-
+-------------------------------------------
 By default, incoming presence subscription to an account will be accepted automatically. You will probably want to change this behavior, for example only to automatically accept subscription if it comes from one of the buddy in the buddy list, and for anything else prompt the user if he/she wants to accept the request.
 
-This can be done by implementing the ​on_incoming_subscribe() method of the ​AccountCallback class.
+This can be done by overriding the ​onIncomingSubscribe() method of the ​Account class.
 
 Changing Account's Presence Status
+----------------------------------
+To change account's presence status, you can use the function Account.setOnlineStatus() to set basic account's presence status (i.e. available or not available) and optionally, some extended information (e.g. busy, away, on the phone, etc), such as::
 
-The ​Account class provides two methods to change account's presence status:
+    try {
+        PresenceStatus ps;
+        ps.status = PJSUA_BUDDY_STATUS_ONLINE;
+        // Optional, set the activity and some note
+        ps.activity = PJRPID_ACTIVITY_BUSY;
+        ps.note = "On the phone";
+        acc->setOnlineStatus(ps);
+    }
 
-​set_basic_status() can be used to set basic account's presence status (i.e. available or not available).
-​set_presence_status() can be used to set both the basic presence status and some extended information (e.g. busy, away, on the phone, etc.).
 When the presence status is changed, the account will publish the new status to all of its presence subscriber, either with PUBLISH request or SUBSCRIBE request, or both, depending on account configuration.