Mercurial > libervia-backend

annotate doc/jp/roster.rst @ 3350:cc6164a4973b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
plugin list of interests: normalize item ID + added `get` method
author Goffi <goffi@goffi.org>
date Sat, 05 Sep 2020 20:22:23 +0200
parents 7b58b15bd121
children ffe7a6d6018a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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