Profanity Illustration

User Guide

Advanced presence, resources and priorities

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.