Mercurial > libervia-backend
comparison doc/jp/roster.rst @ 3041:72583524cfd3
doc (jp): jp commands are now fully documented:
rel 232
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Tue, 01 Oct 2019 22:49:06 +0200 |
| parents | |
| children | 012e89fb2dd1 |
comparison
equal
deleted
inserted
replaced
| 3040:fee60f17ebac | 3041:72583524cfd3 |
|---|---|
| 1 ================================ | |
| 2 roster: manager an entity roster | |
| 3 ================================ | |
| 4 | |
| 5 "Roster" is the name used in XMPP for the contact list. In addition to list of contacts, | |
| 6 you have also data like subscription information or groups associated to a contact. | |
| 7 | |
| 8 Groups are simple strings associated to one or more contacts (e.g. "friends" or "family"). | |
| 9 | |
| 10 Subscription is the mechanism to get presence information of an entity. When you add a | |
| 11 contact to your roster, most XMPP clients also do a presence subscription request, than | |
| 12 the entity may accept or deny. If a presence subscription is accepted, the subscribed user | |
| 13 can see when the other entity is online, and its presence status. | |
| 14 | |
| 15 get | |
| 16 === | |
| 17 | |
| 18 Show the current roster. By default only a display name and JIDs are displayed, but you | |
| 19 can increase verbosity to also display groups, or all other metadata. | |
| 20 | |
| 21 The short name shown next to jid is either the ``name`` specified in roster, or the node | |
| 22 part of the jid. If none of them exist, only the entity JID is shown. | |
| 23 | |
| 24 The following metadata may be displayed: | |
| 25 | |
| 26 groups | |
| 27 group the entity belong too | |
| 28 ask | |
| 29 true if a presence subscription request has been sent (but not answered yet) | |
| 30 from | |
| 31 the contact has a subscription to user presence (i.e. your contact can see when you're | |
| 32 online and your presence status) | |
| 33 to | |
| 34 the user has a subscription to the contact presence (i.e. you can see when you're | |
| 35 contact is online and his/her presence status) | |
| 36 | |
| 37 examples | |
| 38 -------- | |
| 39 | |
| 40 Get roster of default profile and display groups:: | |
| 41 | |
| 42 $ jp roster get -v | |
| 43 | |
| 44 Get roster of default profile and display all metadata:: | |
| 45 | |
| 46 $ jp roster get -vv | |
| 47 | |
| 48 Get roster or default profile and show the result in JSON:: | |
| 49 | |
| 50 $ jp roster get -O json | |
| 51 | |
| 52 stats | |
| 53 ===== | |
| 54 | |
| 55 Show some statistics about the profile roster. The number of contacts per server is shown, | |
| 56 with a percentage of contacts on this server compared to the total number of contacts. | |
| 57 This can notably be helpful to see if there is a concentration of your contacts in a | |
| 58 specific server or gateway. | |
| 59 | |
| 60 Other more or less useful numbers are shown, they are self explaining. | |
| 61 | |
| 62 example | |
| 63 ------- | |
| 64 | |
| 65 Get statistic for the default profile:: | |
| 66 | |
| 67 $ jp roster stats | |
| 68 | |
| 69 purge | |
| 70 ===== | |
| 71 | |
| 72 This command is used to remove from the roster all contacts which have no subscription or | |
| 73 only partial subscription. | |
| 74 | |
| 75 By default, only contacts without subscription at all are removed. With ``--no_from`` you | |
| 76 also remove contacts which have no subscription to you (but you have a subscription to | |
| 77 them), and with ``--no_to`` you also remove contacts that you are not subscribed to (but | |
| 78 who are subscribed to you). | |
| 79 | |
| 80 example | |
| 81 ------- | |
| 82 | |
| 83 Remove all contacts from default profile which have no subscription at all or from which | |
| 84 the default profile is not subscribed to:: | |
| 85 | |
| 86 $ jp roster purge --no_to | |
| 87 | |
| 88 resync | |
| 89 ====== | |
| 90 | |
| 91 SàT uses `roster versioning`_ to optimize the synchronisation of roster with server on | |
| 92 client connection. This means that once the roster has been retrieved, on each following | |
| 93 connection, only the difference of contacts (i.e. which new or removed contacts) is | |
| 94 received. | |
| 95 | |
| 96 This command does a full resynchronisation of the roster, or in other words it requests | |
| 97 the whole roster and save it, replacing the list built with versioning. ``resync`` is | |
| 98 mostly useful for developers and end-user should not need this command, as roster | |
| 99 versioning is supposed to work fine and the roster should be synchronised correctly on | |
| 100 startup. But if for any reason you suspect that your current roster list is corrupted, you | |
| 101 may use it to be sure that a full resynchronisation is done. | |
| 102 | |
| 103 .. _roster versioning: https://tools.ietf.org/html/rfc6121#section-2.6 | |
| 104 | |
| 105 exemple | |
| 106 ------- | |
| 107 | |
| 108 Do a full resynchronisation of default profile's roster:: | |
| 109 | |
| 110 $ jp roster resync |