Presence Notification¶

One of the most differentiating features of SPADE agents is their ability to maintain a roster or list of contacts (friends) and to receive notifications in real time about their contacts. This is a feature inherited from instant messaging technology and that, thanks to XMPP, SPADE powers to the maximum for its agents.

Presence Manager¶

Every SPADE agent has a property to manage its presence. This manager is called presence and implements all the methods and attributes to manage an agent’s presence notification.

A presence object has three attributes: the state, the status and the priority. Let’s see every one of them:

State¶

The state of a presence message shows if the agent is Available or Unavailable. This means that the agent is connected to an XMPP server or not. This is very useful to know, before contacting an agent, if it is available to receive a message in real time or not. The availability state is a boolean attribute.

Besides, the State has also an attribute to give additional information about how available the contact is. This is the Show attribute. The Show attribute belongs to the class aioxmpp.PresenceShow and can take the following values:

PresenceShow.CHAT: The entity or resource is actively interested in chatting (i.e. receiving messages).

PresenceShow.AWAY: The entity or resource is temporarily away, however it can receive messages (they will probably be attended later)

PresenceShow.XA: The entity or resource is away for an extended period (xa = “eXtended Away”).

PresenceShow.DND: The entity or resource is busy (dnd = “Do Not Disturb”).

PresenceShow.NONE: Signifies absence of the Show element. Used for unavailable states.

An agent can set its availability and show property:

agent.presence.set_available(availability=True, show=PresenceShow.CHAT)

Warning

If you set your presence to unavailable the only possible show state is PresenceShow.NONE.

A short method to set unavailability is:

agent.presence.set_unavailable()

To get your presence state:

my_state = agent.presence.state  # Gets your current PresenceState instance.

agent.presence.is_available()  # Returns a boolean to report wether the agent is available or not

my_show = agent.presence.state.show  # Gets your current PresenceShow info.

Tip

If no Show element is provided, the entity is assumed to be online and available.

Status¶

The status is used to set a textual status to your presence information. It is used to explain with natural language your current status which is broadcasted when the client connects and when the presence is re-emitted.

An agent can get its status as follows:

>> agent.presence.status
{None: "Working..."}

Warning

It should be noted that the status is returned as a dict with a None key. This is because the status supports different languages. If you set the status as a string it is set as the default status (and stored with the key None. If you want to set the status in different languages you can specify it using the keys:

>> agent.presence.status
{
  None: "Working...",
  "es": "Trabajando...",
  "fr": "Travailler..."
}

Priority¶

Since an agent (and indeed any XMPP user) can have multiple connections to an XMPP server, it can set the priority of each of those connections to establish the level of each one. The value must be an integer between -128 and +127.

Setting the Presence¶

There is a method that can be used to set the three presence attributes. Since they are all optional, you can change any of the attribute values with every call:

agent.presence.set_presence(
                             state=PresenceState(True, PresenceShow.CHAT),  # available and interested in chatting
                             status="Lunch",
                             priority=2
                            )

Availability handlers¶

To get notified when a contact gets available or unavailable you can override the on_available and on_unavailable handlers. As you can see in the next example, these handlers receive the peer jid of the contact and the stanza of the XMPP Presence message (class aioxmpp.Presence) which contains all its presence information (availability, show, state, priority, …):

def my_on_available_handler(peer_jid, stanza):
    print(f"My friend {peer_jid} is now available with show {stanza.show}")

agent.presence.on_available =  my_on_available_handler

Contact List¶

Every contact to whom you are subscribed to appears in your contact list. You can use the get_contacts() method to get the full list of your contacts. This method returns a dict where the keys are the JID of your contacts and the values are an dict that show the information you have about each of your contacts (presence, name, approved, groups, ask, subscription, …). Note that the “presence” value is an aioxmpp.Presence object with the latest updated information about the contact’s presence.

Example:

>>> contacts = agent.presence.get_contacts()
>>> contacts[myfriend_jid]
      {
        'presence': Presence(type_=PresenceType.AVAILABLE),
        'subscription': 'both',
        'name': 'My Friend',
        'approved': True
      }

Warning

An empty contact list will return an empty dictionary.

Subscribing and unsubscribing to contacts¶

To subscribe and unsubscribe to/from a contact you have to send a special presence message asking for that subscription. SPADE helps you by providing some methods that send these special messages:

# Send a subscription request to a peer_jid
agent.presence.subscribe(peer_jid)

# Send an unsubscribe request to a peer_jid
agent.presence.unsubscribe(peer_jid)

Subscription handlers¶

The way you have to get notified when someone wants to subscribe/unsubscribe to you or when you want to get notified if a subscription/unsubscription process has succeed is by means of handlers. There are four handlers that you can override to manage these kind of messages: on_subscribe, on_unsubscribe, on_subscribed and on_unsubscribed:

def my_on_subscribe_callback(peer_jid):
    if i_want_to_approve_request:
        self.approve(peer_jid)

agent.presence.on_subscribe = my_on_subscribe_callback

Note

In the previous example you can see also how to approve a subscription request by using the approve method.

Tip

If you want to automatically approve all subscription requests you can set the PresenceManager.approve_all flag to True.

Example¶

This is an example that shows in a practical way the presence module:

import getpass
import asyncio

import spade
from spade.agent import Agent
from spade.behaviour import OneShotBehaviour


class Agent1(Agent):
    async def setup(self):
        print("Agent {} running".format(self.name))
        self.add_behaviour(self.Behav1())

    class Behav1(OneShotBehaviour):
        def on_available(self, jid, stanza):
            print("[{}] Agent {} is available.".format(self.agent.name, jid.split("@")[0]))

        def on_subscribed(self, jid):
            print("[{}] Agent {} has accepted the subscription.".format(self.agent.name, jid.split("@")[0]))
            print("[{}] Contacts List: {}".format(self.agent.name, self.agent.presence.get_contacts()))

        def on_subscribe(self, jid):
            print("[{}] Agent {} asked for subscription. Let's aprove it.".format(self.agent.name, jid.split("@")[0]))
            self.presence.approve(jid)

        async def run(self):
            self.presence.on_subscribe = self.on_subscribe
            self.presence.on_subscribed = self.on_subscribed
            self.presence.on_available = self.on_available

            self.presence.set_available()
            self.presence.subscribe(self.agent.jid2)


class Agent2(Agent):
    async def setup(self):
        print("Agent {} running".format(self.name))
        self.add_behaviour(self.Behav2())

    class Behav2(OneShotBehaviour):
        def on_available(self, jid, stanza):
            print("[{}] Agent {} is available.".format(self.agent.name, jid.split("@")[0]))

        def on_subscribed(self, jid):
            print("[{}] Agent {} has accepted the subscription.".format(self.agent.name, jid.split("@")[0]))
            print("[{}] Contacts List: {}".format(self.agent.name, self.agent.presence.get_contacts()))

        def on_subscribe(self, jid):
            print("[{}] Agent {} asked for subscription. Let's aprove it.".format(self.agent.name, jid.split("@")[0]))
            self.presence.approve(jid)
            self.presence.subscribe(jid)

        async def run(self):
            self.presence.set_available()
            self.presence.on_subscribe = self.on_subscribe
            self.presence.on_subscribed = self.on_subscribed
            self.presence.on_available = self.on_available


async def main():
    jid1 = input("Agent1 JID> ")
    passwd1 = getpass.getpass()

    jid2 = input("Agent2 JID> ")
    passwd2 = getpass.getpass()

    agent2 = Agent2(jid2, passwd2)
    agent1 = Agent1(jid1, passwd1)
    agent1.jid2 = jid2
    agent2.jid1 = jid1
    await agent2.start()
    await agent1.start()

    while True:
        try:
            await asyncio.sleep(1)
        except KeyboardInterrupt:
            break
    await agent1.stop()
    await agent2.stop()


if __name__ == "__main__":
    spade.run(main())