Mercurial > libervia-backend

annotate doc/jp/roster.rst @ 3405:ecdb3728749e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
plugin XEP-0353: Jingle Message Initiation implementation: This plugin uses the new `XEP-0166_initiate` trigger to initiate a Jingle session with messages if the peer jid has no resource specified. On reception, if the sender is not in our roster, a confirmation is requested to user to avoid leaking presence and IP. If user refuses the session for somebody not in roster, nothing is sent at all (the request is just ignored).
author Goffi <goffi@goffi.org>
date Thu, 12 Nov 2020 14:53:15 +0100
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