Changeset 4762 for pjproject/trunk/doc/pjsip-book/presence.rst
- Timestamp:
- Feb 24, 2014 11:00:15 AM (10 years ago)
- Location:
- pjproject/trunk/doc/pjsip-book
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
pjproject/trunk/doc/pjsip-book
-
Property
svn:ignore
set to
xml
-
Property
svn:ignore
set to
-
pjproject/trunk/doc/pjsip-book/presence.rst
r4704 r4762 1 2 1 3 2 Buddy (Presence) 4 3 ================ 5 This class represents a remote buddy (a person, or a SIP endpoint). 6 To use the Buddy class, application DOES NOT need to subclass it unless application wants to get the notifications on buddy state change. 4 Presence feature in PJSUA2 centers around Buddy class. This class represents a remote buddy (a person, or a SIP endpoint). 7 5 8 Sub scribe to Buddy's Presence Status9 ---------------------------- -----------------------------10 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::6 Subclassing the Buddy class 7 ---------------------------- 8 To use the Buddy class, normally application SHOULD create its own subclass, such as: 11 9 12 class MyBuddyCallback(pjsua.BuddyCallback): 13 def __init__(self, buddy=None): 14 pjsua.BuddyCallback.__init__(self, buddy) 10 .. code-block:: c++ 15 11 16 def on_state(self): 17 print "Buddy", self.buddy.info().uri, "is", 18 print self.buddy.info().online_text 12 class MyBuddy : public Buddy 13 { 14 public: 15 MyBuddy() {} 16 ~MyBuddy() {} 19 17 20 try: 21 uri = '"Alice" <sip:alice@example.com>' 22 buddy = acc.add_buddy(uri, cb=MyBuddyCallback()) 23 buddy.subscribe() 18 virtual void onBuddyState(); 19 }; 24 20 25 except pjsua.Error, err: 26 print 'Error adding buddy:', err 21 In its subclass, application can implement the buddy callback to get the notifications on buddy state change. 27 22 28 For more information please see âBuddy class and âBuddyCallback class reference documentation. 23 Subscribing to Buddy's Presence Status 24 --------------------------------------- 25 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: 26 27 .. code-block:: c++ 28 29 BuddyConfig cfg; 30 cfg.uri = "sip:alice@example.com"; 31 MyBuddy buddy; 32 try { 33 buddy.create(*acc, cfg); 34 buddy.subscribePresence(true); 35 } catch(Error& err) { 36 } 37 38 Then you can get the buddy's presence state change inside the onBuddyState() callback: 39 40 .. code-block:: c++ 41 42 void MyBuddy::onBuddyState() 43 { 44 BuddyInfo bi = getInfo(); 45 cout << "Buddy " << bi.uri << " is " << bi.presStatus.statusText << endl; 46 } 47 48 For more information, please see Buddy class reference documentation. 29 49 30 50 Responding to Presence Subscription Request 31 51 ------------------------------------------- 32 52 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. 33 53 34 This can be done by implementing the âon_incoming_subscribe() method of the âAccountCallback class.54 This can be done by overriding the onIncomingSubscribe() method of the Account class. Please see the documentation of this method for more info. 35 55 36 56 Changing Account's Presence Status 57 ---------------------------------- 58 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: 37 59 38 The âAccount class provides two methods to change account's presence status: 60 .. code-block:: c++ 39 61 40 âset_basic_status() can be used to set basic account's presence status (i.e. available or not available). 41 â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.). 42 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. 62 try { 63 PresenceStatus ps; 64 ps.status = PJSUA_BUDDY_STATUS_ONLINE; 65 // Optional, set the activity and some note 66 ps.activity = PJRPID_ACTIVITY_BUSY; 67 ps.note = "On the phone"; 68 acc->setOnlineStatus(ps); 69 } catch(Error& err) { 70 } 43 71 72 When the presence status is changed, the account will publish the new status to all of its presence subscriber, either with PUBLISH request or NOTIFY request, or both, depending on account configuration. 73 74 Instant Messaging(IM) 75 --------------------- 76 You can send IM using Buddy.sendInstantMessage(). The transmission status of outgoing instant messages is reported in Account.onInstantMessageStatus() callback method of Account class. 77 78 In addition to sending instant messages, you can also send typing indication to remote buddy using Buddy.sendTypingIndication(). 79 80 Incoming IM and typing indication received not within the scope of a call will be reported in the callback functions Account.onInstantMessage() and Account.onTypingIndication(). 81 82 Alternatively, you can send IM and typing indication within a call by using Call.sendInstantMessage() and Call.sendTypingIndication(). For more information, please see Call documentation. 83 84 85 Class Reference 86 --------------- 87 Buddy 88 +++++ 89 .. doxygenclass:: pj::Buddy 90 :path: xml 91 :members: 92 93 Status 94 ++++++ 95 .. doxygenstruct:: pj::PresenceStatus 96 :path: xml 97 98 Info 99 ++++ 100 .. doxygenstruct:: pj::BuddyInfo 101 :path: xml 102 103 Config 104 ++++++ 105 .. doxygenstruct:: pj::BuddyConfig 106 :path: xml 107 108
Note: See TracChangeset
for help on using the changeset viewer.