Mercurial > libervia-backend

annotate doc/libervia-cli/roster.rst @ 3652:6e34307319c0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
plugin XEP-0353: fix jingle initiation on disco "Service Unavailable" error: When requesting disco info on a bare jid which is not in our roster, server may return "Service Unavailable" (to avoid leaking valid JIDs). In this case, the initiation was failing, this is now fixed by using empty categories in this case.
author Goffi <goffi@goffi.org>
date Wed, 08 Sep 2021 11:16:52 +0200
parents 267e4987b58b
children
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
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
42 $ li roster get -v
3041
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
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
46 $ li roster get -vv
3041
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
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
50 $ li roster get -O json
3041
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
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
69 $ li roster set -n Enjolras louise@example.net
3255
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
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
73 $ li 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
3414
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
75 delete
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
76 ======
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
77
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
78 Remove an entity from roster.
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
79
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
80 examples
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
81 --------
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
82
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
83 Remove John from your roster::
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
84
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
85 $ li roster delete john@example.net
3414
ffe7a6d6018a jp (roster): `delete` implementation
Goffi <goffi@goffi.org>
parents: 3283
diff changeset
86
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
87 stats
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
88 =====
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 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
91 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
92 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
93 specific server or gateway.
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 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
96
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
97 example
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
98 -------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
99
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
100 Get statistic for the default profile::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
101
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
102 $ li roster stats
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
103
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
104 purge
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
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
107 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
108 only partial subscription.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
109
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
110 By default, only contacts without subscription at all are removed. With ``--no-from`` you
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
111 also remove contacts which have no subscription to you (but you have a subscription to
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
112 them), and with ``--no-to`` you also remove contacts that you are not subscribed to (but
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
113 who are subscribed to you).
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
114
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
115 example
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
116 -------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
117
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
118 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
119 the default profile is not subscribed to::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
120
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
121 $ li roster purge --no-to
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
122
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
123 resync
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
124 ======
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
125
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
126 Libervia uses `roster versioning`_ to optimize the synchronisation of roster with server on
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
127 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
128 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
129 received.
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 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
132 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
133 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
134 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
135 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
136 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
137
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
138 .. _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
139
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
140 exemple
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
141 -------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
142
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
143 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
144
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3414
diff changeset
145 $ li roster resync