← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.2.1/doc/pjsip-book/presence.rst

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2015-01-07 14:51:16 UTC
  • mfrom: (4.3.5 sid)
  • Revision ID: package-import@ubuntu.com-20150107145116-yxnafinf4lrdvrmx
Tags: 1.4.1-0.1ubuntu1
* Merge with Debian, remaining changes:
 - Drop soprano, nepomuk build-dep
* Drop ubuntu patches, now upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.2.1/doc/pjsip-book/presence.rst
 
1
 
 
2
Buddy (Presence)
 
3
================
 
4
Presence feature in PJSUA2 centers around Buddy class. This class represents a remote buddy (a person, or a SIP endpoint).
 
5
 
 
6
Subclassing the Buddy class
 
7
----------------------------
 
8
To use the Buddy class, normally application SHOULD create its own subclass, such as:
 
9
 
 
10
.. code-block:: c++
 
11
 
 
12
    class MyBuddy : public Buddy
 
13
    {
 
14
    public:
 
15
        MyBuddy() {}
 
16
        ~MyBuddy() {}
 
17
 
 
18
        virtual void onBuddyState();
 
19
    };
 
20
 
 
21
In its subclass, application can implement the buddy callback to get the notifications on buddy state change.
 
22
 
 
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.
 
49
 
 
50
Responding to Presence Subscription Request
 
51
-------------------------------------------
 
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.
 
53
 
 
54
This can be done by overriding the onIncomingSubscribe() method of the Account class. Please see the documentation of this method for more info.
 
55
 
 
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:
 
59
 
 
60
.. code-block:: c++
 
61
 
 
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
    }
 
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