Mercurial > libervia-backend
annotate doc/jp/roster.rst @ 3331:b1e9f17fbb5a
comp file sharing: minor core re-organisation
author | Goffi <goffi@goffi.org> |
---|---|
date | Thu, 13 Aug 2020 23:46:18 +0200 |
parents | 7b58b15bd121 |
children | ffe7a6d6018a |
rev | line source |
---|---|
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
1 ================================ |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
2 roster: manager an entity roster |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
3 ================================ |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
4 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
5 "Roster" is the name used in XMPP for the contact list. In addition to list of contacts, |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
6 you have also data like subscription information or groups associated to a contact. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
7 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
8 Groups are simple strings associated to one or more contacts (e.g. "friends" or "family"). |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
9 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
10 Subscription is the mechanism to get presence information of an entity. When you add a |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
11 contact to your roster, most XMPP clients also do a presence subscription request, than |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
12 the entity may accept or deny. If a presence subscription is accepted, the subscribed user |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
13 can see when the other entity is online, and its presence status. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
14 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
15 get |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
16 === |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
17 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
18 Show the current roster. By default only a display name and JIDs are displayed, but you |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
19 can increase verbosity to also display groups, or all other metadata. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
20 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
21 The short name shown next to jid is either the ``name`` specified in roster, or the node |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
22 part of the jid. If none of them exist, only the entity JID is shown. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
23 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
24 The following metadata may be displayed: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
25 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
26 groups |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
27 group the entity belong too |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
28 ask |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
29 true if a presence subscription request has been sent (but not answered yet) |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
30 from |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
31 the contact has a subscription to user presence (i.e. your contact can see when you're |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
32 online and your presence status) |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
33 to |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
34 the user has a subscription to the contact presence (i.e. you can see when you're |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
35 contact is online and his/her presence status) |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
36 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
37 examples |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
38 -------- |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
39 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
40 Get roster of default profile and display groups:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
41 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
42 $ jp roster get -v |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
43 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
44 Get roster of default profile and display all metadata:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
45 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
46 $ jp roster get -vv |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
47 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
48 Get roster or default profile and show the result in JSON:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
49 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
50 $ jp roster get -O json |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
51 |
3255
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
52 set |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
53 === |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
54 |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
55 Set metadata for a roster entity. Only ``name`` and ``groups`` can be set, ``name`` being |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
56 the user chosed name to use with a contact. |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
57 |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
58 By default, values are appended, i.e. if ``name`` is not set it won't delete existing one, |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
59 and ``groups`` are appended to existing one. However, if you use the ``-R, --replace`` |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
60 option, former values will be entirely replaced by given ones (i.e. if you don't use ``-n |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
61 NAME, --name NAME`` option, the former one will be deleted, and any former group no added |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
62 using ``-g GROUP, --group GROUP`` will be removed). |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
63 |
3283
7b58b15bd121
doc (jp/roster): fixed example for `jp roster set`
Goffi <goffi@goffi.org>
parents:
3255
diff
changeset
|
64 examples |
7b58b15bd121
doc (jp/roster): fixed example for `jp roster set`
Goffi <goffi@goffi.org>
parents:
3255
diff
changeset
|
65 -------- |
3255
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
66 |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
67 Set a name used to privately identify your contact Louise:: |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
68 |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
69 $ jp roster set -n Enjolras louise@example.net |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
70 |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
71 Replace all groups of Pierre, to add him only to ``friends`` and ``housemates``:: |
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
72 |
3283
7b58b15bd121
doc (jp/roster): fixed example for `jp roster set`
Goffi <goffi@goffi.org>
parents:
3255
diff
changeset
|
73 $ jp roster set --replace -g friends -g housemates pierre@example.net |
3255
012e89fb2dd1
jp (roster): new roster/set command
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
74 |
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
75 stats |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
76 ===== |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
77 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
78 Show some statistics about the profile roster. The number of contacts per server is shown, |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
79 with a percentage of contacts on this server compared to the total number of contacts. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
80 This can notably be helpful to see if there is a concentration of your contacts in a |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
81 specific server or gateway. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
82 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
83 Other more or less useful numbers are shown, they are self explaining. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
84 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
85 example |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
86 ------- |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
87 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
88 Get statistic for the default profile:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
89 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
90 $ jp roster stats |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
91 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
92 purge |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
93 ===== |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
94 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
95 This command is used to remove from the roster all contacts which have no subscription or |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
96 only partial subscription. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
97 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
98 By default, only contacts without subscription at all are removed. With ``--no_from`` you |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
99 also remove contacts which have no subscription to you (but you have a subscription to |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
100 them), and with ``--no_to`` you also remove contacts that you are not subscribed to (but |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
101 who are subscribed to you). |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
102 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
103 example |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
104 ------- |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
105 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
106 Remove all contacts from default profile which have no subscription at all or from which |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
107 the default profile is not subscribed to:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
108 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
109 $ jp roster purge --no_to |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
110 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
111 resync |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
112 ====== |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
113 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
114 SàT uses `roster versioning`_ to optimize the synchronisation of roster with server on |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
115 client connection. This means that once the roster has been retrieved, on each following |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
116 connection, only the difference of contacts (i.e. which new or removed contacts) is |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
117 received. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
118 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
119 This command does a full resynchronisation of the roster, or in other words it requests |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
120 the whole roster and save it, replacing the list built with versioning. ``resync`` is |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
121 mostly useful for developers and end-user should not need this command, as roster |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
122 versioning is supposed to work fine and the roster should be synchronised correctly on |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
123 startup. But if for any reason you suspect that your current roster list is corrupted, you |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
124 may use it to be sure that a full resynchronisation is done. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
125 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
126 .. _roster versioning: https://tools.ietf.org/html/rfc6121#section-2.6 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
127 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
128 exemple |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
129 ------- |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
130 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
131 Do a full resynchronisation of default profile's roster:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
132 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
133 $ jp roster resync |