Mercurial > libervia-backend

comparison doc/libervia-cli/roster.rst @ 3488:c80a0f864b5d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: updated doc following global renaming
author Goffi <goffi@goffi.org>
date Sun, 21 Mar 2021 18:23:58 +0100
parents doc/jp/roster.rst@ffe7a6d6018a
children 267e4987b58b
comparison
equal deleted inserted replaced
3487:75427f0a5445 3488:c80a0f864b5d
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 $ li roster get -v
43
44 Get roster of default profile and display all metadata::
45
46 $ li roster get -vv
47
48 Get roster or default profile and show the result in JSON::
49
50 $ li roster get -O json
51
52 set
53 ===
54
55 Set metadata for a roster entity. Only ``name`` and ``groups`` can be set, ``name`` being
56 the user chosed name to use with a contact.
57
58 By default, values are appended, i.e. if ``name`` is not set it won't delete existing one,
59 and ``groups`` are appended to existing one. However, if you use the ``-R, --replace``
60 option, former values will be entirely replaced by given ones (i.e. if you don't use ``-n
61 NAME, --name NAME`` option, the former one will be deleted, and any former group no added
62 using ``-g GROUP, --group GROUP`` will be removed).
63
64 examples
65 --------
66
67 Set a name used to privately identify your contact Louise::
68
69 $ li roster set -n Enjolras louise@example.net
70
71 Replace all groups of Pierre, to add him only to ``friends`` and ``housemates``::
72
73 $ li roster set --replace -g friends -g housemates pierre@example.net
74
75 delete
76 ======
77
78 Remove an entity from roster.
79
80 examples
81 --------
82
83 Remove John from your roster::
84
85 $ li roster delete john@example.net
86
87 stats
88 =====
89
90 Show some statistics about the profile roster. The number of contacts per server is shown,
91 with a percentage of contacts on this server compared to the total number of contacts.
92 This can notably be helpful to see if there is a concentration of your contacts in a
93 specific server or gateway.
94
95 Other more or less useful numbers are shown, they are self explaining.
96
97 example
98 -------
99
100 Get statistic for the default profile::
101
102 $ li roster stats
103
104 purge
105 =====
106
107 This command is used to remove from the roster all contacts which have no subscription or
108 only partial subscription.
109
110 By default, only contacts without subscription at all are removed. With ``--no_from`` you
111 also remove contacts which have no subscription to you (but you have a subscription to
112 them), and with ``--no_to`` you also remove contacts that you are not subscribed to (but
113 who are subscribed to you).
114
115 example
116 -------
117
118 Remove all contacts from default profile which have no subscription at all or from which
119 the default profile is not subscribed to::
120
121 $ li roster purge --no_to
122
123 resync
124 ======
125
126 SàT uses `roster versioning`_ to optimize the synchronisation of roster with server on
127 client connection. This means that once the roster has been retrieved, on each following
128 connection, only the difference of contacts (i.e. which new or removed contacts) is
129 received.
130
131 This command does a full resynchronisation of the roster, or in other words it requests
132 the whole roster and save it, replacing the list built with versioning. ``resync`` is
133 mostly useful for developers and end-user should not need this command, as roster
134 versioning is supposed to work fine and the roster should be synchronised correctly on
135 startup. But if for any reason you suspect that your current roster list is corrupted, you
136 may use it to be sure that a full resynchronisation is done.
137
138 .. _roster versioning: https://tools.ietf.org/html/rfc6121#section-2.6
139
140 exemple
141 -------
142
143 Do a full resynchronisation of default profile's roster::
144
145 $ li roster resync