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:

$ li roster get -v

Get roster of default profile and display all metadata:

$ li roster get -vv

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

$ li roster get -O json

set

Set metadata for a roster entity. Only name and groups can be set, name being the user chosed name to use with a contact.

By default, values are appended, i.e. if name is not set it won’t delete existing one, and groups are appended to existing one. However, if you use the -R, --replace option, former values will be entirely replaced by given ones (i.e. if you don’t use -n NAME, --name NAME option, the former one will be deleted, and any former group no added using -g GROUP, --group GROUP will be removed).

examples

Set a name used to privately identify your contact Louise:

$ li roster set -n Enjolras louise@example.net

Replace all groups of Pierre, to add him only to friends and housemates:

$ li roster set --replace -g friends -g housemates pierre@example.net

delete

Remove an entity from roster.

examples

Remove John from your roster:

$ li roster delete john@example.net

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:

$ li 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:

$ li roster purge --no-to

resync

Libervia 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.

exemple

Do a full resynchronisation of default profile’s roster:

$ li roster resync