source: doc/xmppim.rst @ 238:a2a4310ded26

Last change on this file since 238:a2a4310ded26 was 174:c0f51d95bf0f, checked in by Ralph Meijer <ralphm@…>, 10 years ago

Add support for adding and updating roster items.

Roster items can be added or updated by sending a roster set request using the
new wokkel.xmppim.RosterClientProtocol.setItem. It takes a RosterItem as
the only argument. Note that changes in presence subscriptions for the contact
need to be done using presence as provided by
wokkel.xmppim.PresenceProtocol.

Author: ralphm.
Fixes: #56.

File size: 1.7 KB
RevLine 
[172]1XMPP IM protocol support
2========================
3
4Roster Management
5-----------------
6
7A roster holds a collection of contacts for a user. Typically a user has one
8roster kept by the user's server, but rosters may also be kept by other
9entities. Usually, a client requests a user's roster right after
10authentication, and is then notified of any changes to the roster. A client may
11also modify the roster, on behalf of the user, by setting or removing roster
12items.
13
14Requesting the roster
15^^^^^^^^^^^^^^^^^^^^^
16
17.. literalinclude:: listings/xmppim/roster_client_get.py
18   :language: python
19   :linenos:
20
21Receiving roster pushes
22^^^^^^^^^^^^^^^^^^^^^^^
23
24.. literalinclude:: listings/xmppim/roster_client_push.py
25   :language: python
26   :linenos:
27
[174]28Set the name of a contact
29^^^^^^^^^^^^^^^^^^^^^^^^^
30
31.. literalinclude:: listings/xmppim/roster_client_set_name.py
32   :language: python
33   :linenos:
34
[172]35Remove a contact
36^^^^^^^^^^^^^^^^
37
38.. literalinclude:: listings/xmppim/roster_client_remove.py
39   :language: python
40   :linenos:
[173]41
42Roster versioning
43^^^^^^^^^^^^^^^^^
44
45Some XMPP servers support roster versioning. A client can keep a cache of the
46roster by requesting it and applying changes as roster pushes come in. Each
47version of the roster is marked with a version identifier. This can be used
48to request the roster upon reconnect. The server can then choose to send the
49difference between the requested and current version as roster pushed,
50instead of returning the complete roster.
51
52When no roster was cached by the client, yet, a client passes the empty
53string (``''``) to ``getRoster`` to bootstrap the process.
54
55This example will force a reconnect 15 seconds after authentication.
56
57.. literalinclude:: listings/xmppim/roster_client_versioning.py
58   :language: python
59   :linenos:
Note: See TracBrowser for help on using the repository browser.