Contents
Overview
Since version 0.2.0, Profanity allows more flexible handling of resource and priority settings.
If you only ever connect to a chat service using the same computer (for example, you log on at work on your desktop, and never from anywhere else), you probably need not be concerned with these settings.
If you already know about resources and priorities and want to use them in Profanity, you can skip this overview and go straight to the settings section.
If you often connect from many devices, and want to ensure that messages are routed to the right place, but don't know how, this brief overview should help before moving on to the settings sections below.
Resources
The XMPP protocol allows users to connect from more than one place at a time. For example, I might connect from my laptop, my desktop, my tablet and my phone. Or, unlikely but still possible, from two Jabber clients on my desktop, Profanity and Miranda.
Contact's identifiers are called JIDs (Jabber IDentifiers). A JID is of the form:
localpart@domainpart
E.g.:
friends.name@ourserver.org
localpart = friends.name
domainpart = ourserver.org
This is enough to identify a contact. However, when a contact connects to a chat service using a Jabber client, that client is represented as a resource
So whilst a contact can be identified as localpart@domainpart
(known as a bare jid),
their connection using a specific client is identified as localpart@domainpart/resourcepart
(known as a full jid).
For example, a contact some.friend@chat.server.org
logs in using both their laptop and their phone. The software on their laptop uses the resource name laptop
and the phone phone
.
Our contact can be identified as:
some.friend@chat.server.org
And they have two connected resources:
some.friend@chat.server.org/laptop
some.friend@chat.server.org/phone
When we receive a message, it will be from a full jid, i.e. from a specific client the contact is using.
You might be unaware of the resource most of the time, most client software uses a default (often the name of the software) which you can find in it's settings.
Even if the client software provides no default, the chat service will generate a unique resource name, which is why you might see long numbers appear after a contacts name in your client:
someone@theserver.com/b2be5700-73ed-4922-91be-f4bd5ae1526a
Priorities
Since a user may be connected using more than one client, the server needs to know where to route messages, therefore resources are given a priority
A priority is a number between -128 and 127.
The exact rules to determine which resource (laptop or phone, for example) gets a message, vary between server implementations, but most follow something like the following:
Find the resource with the highest priority
Send the message to that resource
If two resources have the same priority, send to both
If the only resources available have a negative number, store the message until a resource connects with a priority of 0 or higher
If we go back to the example above, adding a priority to each resource:
Contact:
some.friend@chat.server.org
Connected Resources:
some.friend@chat.server.org/laptop, priority = 5
some.friend@chat.server.org/phone, priority = 20
If we send a message to our contact:
/msg some.friend@chat.server.org Hi there!
The message will be delivered to the contact's phone
The following sections show how to set the resource name, and priority for Profanity.
Setting the resource
To set the resource for a particular account in Profanity, use the /account command:
For example to set the resource for the account work
to laptop
:
/account set work resource laptop
To find out what resource name is being used at any time:
/account show work
Or, if you are logged in:
/account
Will show the settings for the current account.
Setting priority
To set the priority for an account whilst logged in use the /priority command:
/priority 10
This will set the priority to 10 for this account. Whether you are online, away, dnd etc, the priority will always be 10.
For more flexible priority settings per presence, see the next section.
Setting priority per presence
You may set a different priority for each presence for an account. This is useful, for example, if you want messages to be routed to your phone, when your desktop client becomes away
.
To set the priority for a particular presence for an account, use the /account command.
/account set work away 0
/account set work online 20
Whenever your work account becomes away
including autoaway the priority will be set to 0.
When the account is online
the priority will be 20.
To find out the priority associated with each presence for an account at any time:
/account show work
Or, if you are logged in:
/account
Will show the settings for the current account.