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