Mercurial > libervia-backend

view doc/jp/roster.rst @ 3254:6cf4bd6972c2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
core, frontends: avatar refactoring: /!\ huge commit Avatar logic has been reworked around the IDENTITY plugin: plugins able to handle avatar or other identity related metadata (like nicknames) register to IDENTITY plugin in the same way as for other features like download/upload. Once registered, IDENTITY plugin will call them when suitable in order of priority, and handle caching. Methods to manage those metadata from frontend now use serialised data. For now `avatar` and `nicknames` are handled: - `avatar` is now a dict with `path` + metadata like `media_type`, instead of just a string path - `nicknames` is now a list of nicknames in order of priority. This list is never empty, and `nicknames[0]` should be the preferred nickname to use by frontends in most cases. In addition to contact specified nicknames, user set nickname (the one set in roster) is used in priority when available. Among the side changes done with this commit, there are: - a new `contactGet` bridge method to get roster metadata for a single contact - SatPresenceProtocol.send returns a Deferred to check when it has actually been sent - memory's methods to handle entities data now use `client` as first argument - metadata filter can be specified with `getIdentity` - `getAvatar` and `setAvatar` are now part of the IDENTITY plugin instead of XEP-0054 (and there signature has changed) - `isRoom` and `getBareOrFull` are now part of XEP-0045 plugin - jp avatar/get command uses `xdg-open` first when available for `--show` flag - `--no-cache` has been added to jp avatar/get and identity/get - jp identity/set has been simplified, explicit options (`--nickname` only for now) are used instead of `--field`. `--field` may come back in the future if necessary for extra data. - QuickContactList `SetContact` now handle None as a value, and doesn't use it to delete the metadata anymore - improved cache handling for `metadata` and `nicknames` in quick frontend - new `default` argument in QuickContactList `getCache`
author Goffi <goffi@goffi.org>
date Tue, 14 Apr 2020 21:00:33 +0200
parents 72583524cfd3
children 012e89fb2dd1
line wrap: on
line source

================================
roster: manager an entity roster
================================

"Roster" is the name used in XMPP for the contact list. In addition to list of contacts,
you have also data like subscription information or groups associated to a contact.

Groups are simple strings associated to one or more contacts (e.g. "friends" or "family").

Subscription is the mechanism to get presence information of an entity. When you add a
contact to your roster, most XMPP clients also do a presence subscription request, than
the entity may accept or deny. If a presence subscription is accepted, the subscribed user
can see when the other entity is online, and its presence status.

get
===

Show the current roster. By default only a display name and JIDs are displayed, but you
can increase verbosity to also display groups, or all other metadata.

The short name shown next to jid is either the ``name`` specified in roster, or the node
part of the jid. If none of them exist, only the entity JID is shown.

The following metadata may be displayed:

groups
  group the entity belong too
ask
  true if a presence subscription request has been sent (but not answered yet)
from
  the contact has a subscription to user presence (i.e. your contact can see when you're
  online and your presence status)
to
  the user has a subscription to the contact presence (i.e. you can see when you're
  contact is online and his/her presence status)

examples
--------

Get roster of default profile and display groups::

  $ jp roster get -v

Get roster of default profile and display all metadata::

  $ jp roster get -vv

Get roster or default profile and show the result in JSON::

  $ jp roster get -O json

stats
=====

Show some statistics about the profile roster. The number of contacts per server is shown,
with a percentage of contacts on this server compared to the total number of contacts.
This can notably be helpful to see if there is a concentration of your contacts in a
specific server or gateway.

Other more or less useful numbers are shown, they are self explaining.

example
-------

Get statistic for the default profile::

  $ jp roster stats

purge
=====

This command is used to remove from the roster all contacts which have no subscription or
only partial subscription.

By default, only contacts without subscription at all are removed. With ``--no_from`` you
also remove contacts which have no subscription to you (but you have a subscription to
them), and with ``--no_to`` you also remove contacts that you are not subscribed to (but
who are subscribed to you).

example
-------

Remove all contacts from default profile which have no subscription at all or from which
the default profile is not subscribed to::

  $ jp roster purge --no_to

resync
======

SàT uses `roster versioning`_ to optimize the synchronisation of roster with server on
client connection. This means that once the roster has been retrieved, on each following
connection, only the difference of contacts (i.e. which new or removed contacts) is
received.

This command does a full resynchronisation of the roster, or in other words it requests
the whole roster and save it, replacing the list built with versioning. ``resync`` is
mostly useful for developers and end-user should not need this command, as roster
versioning is supposed to work fine and the roster should be synchronised correctly on
startup. But if for any reason you suspect that your current roster list is corrupted, you
may use it to be sure that a full resynchronisation is done.

.. _roster versioning: https://tools.ietf.org/html/rfc6121#section-2.6

exemple
-------

Do a full resynchronisation of default profile's roster::

  $ jp roster resync