Smack/documentation/extensions/messageevents.md

Message Events

This extension is used to request and respond to events relating to the delivery, display, and composition of messages. There are three stages in this extension:

1. Request for event notifications,
2. Receive the event notification requests and send event notifications, and
3. Receive the event notifications.

XEP related: XEP-22

Requesting Event Notifications

Description

In order to receive event notifications for a given message you first have to specify which events are you interested in. Each message that you send has to request its own event notifications. Therefore, every message that you send as part of a chat should request its own event notifications.

Usage

The class MessageEventManager provides an easy way for requesting event notifications. All you have to do is specify the message that requires the event notifications and the events that you are interested in.

Use the static method MessageEventManager.addNotificationsRequests(Message message, boolean offline, boolean delivered, boolean displayed, boolean composing) for requesting event notifications.

Example

Below you can find an example that logs in a user to the server, creates a message, adds the requests for notifications and sends the message.

// Connect to the server and log in
conn1 = new XMPPConnection(host);
conn1.login(server_user1, pass1);
// Create a chat with user2
Chat chat1 = conn1.createChat(user2);
// Create a message to send
Message msg = chat1.createMessage();
msg.setSubject("Any subject you want");
msg.setBody("An interesting body comes here...");
// Add to the message all the notifications requests (offline,
// composing)
MessageEventManager.addNotificationsRequests(msg, **true**, **true**, **true**, **true**);
// Send the message that contains the notifications request
chat1.sendMessage(msg);

Reacting to Event Notification Requests

Description

You can receive notification requests for the following events: delivered, displayed, composing and offline. You must listen for these requests and react accordingly.

Usage

The general idea is to create a new DefaultMessageEventRequestListener that will listen to the event notifications requests and react with custom logic. Then you will have to add the listener to the MessageEventManager that works on the desired XMPPConnection.

Note that DefaultMessageEventRequestListener is a default implementation of the MessageEventRequestListener interface. The class DefaultMessageEventRequestListener automatically sends a delivered notification to the sender of the message if the sender has requested to be notified when the message is delivered. If you decide to create a new class that implements the MessageEventRequestListener interface, please remember to send the delivered notification.

• To create a new MessageEventManager use the MessageEventManager(XMPPConnection) constructor.
• To create an event notification requests listener create a subclass of DefaultMessageEventRequestListener or create a class that implements the MessageEventRequestListener interface.
• To add a listener to the messageEventManager use the MessageEventManager's message addMessageEventRequestListener(MessageEventRequestListener).

Example

Below you can find an example that connects two users to the server. One user will create a message, add the requests for notifications and will send the message to the other user. The other user will add a DefaultMessageEventRequestListener to a MessageEventManager that will listen and react to the event notification requested by the other user.

// Connect to the server and log in the users
conn1 = new XMPPConnection(host);
conn1.login(server_user1, pass1);
conn2 = new XMPPConnection(host);
conn2.login(server_user2, pass2);
// User2 creates a MessageEventManager
MessageEventManager messageEventManager = new MessageEventManager(conn2);
// User2 adds the listener that will react to the event notifications requests
messageEventManager.addMessageEventRequestListener(new DefaultMessageEventRequestListener() {
public void deliveredNotificationRequested(
String from,
String packetID,
MessageEventManager messageEventManager) {
super.deliveredNotificationRequested(from, packetID, messageEventManager);
// DefaultMessageEventRequestListener automatically responds that the message was delivered when receives this r
System.out.println("Delivered Notification Requested (" + from + ", " + packetID + ")");
}
public void displayedNotificationRequested(String from, String packetID, MessageEventManager messageEventManager) {
super.displayedNotificationRequested(from, packetID,
// Send to the message's sender that the message was
messageEventManager.sendDisplayedNotification(from, packetID);
}
public void composingNotificationRequested(String from, String packetID, MessageEventManager messageEventManager) {
super.composingNotificationRequested(from, packetID, messageEventManager);
// Send to the message's sender that the message's receiver is composing a reply
messageEventManager.sendComposingNotification(from, packetID);
}
public void offlineNotificationRequested(String from, String packetID, MessageEventManager messageEventManager) {
super.offlineNotificationRequested(from, packetID, messageEventManager);
// The XMPP server should take care of this request. Do nothing.
System.out.println("Offline Notification Requested (" + from + ", " + packetID + ")");
}
});
// User1 creates a chat with user2
Chat chat1 = conn1.createChat(user2);
// User1 creates a message to send to user2
Message msg = chat1.createMessage();
msg.setSubject("Any subject you want");
msg.setBody("An interesting body comes here...");
// User1 adds to the message all the notifications requests (offline, delivered, displayed,
// composing)
MessageEventManager.addNotificationsRequests(msg, true, true, true, true);
// User1 sends the message that contains the notifications request
chat1.sendMessage(msg);
Thread.sleep(500);
// User2 sends to the message's sender that the message's receiver cancelled composing a reply
messageEventManager.sendCancelledNotification(user1, msg.getPacketID());

Reacting to Event Notifications

Description

Once you have requested for event notifications you will start to receive notifications of events. You can receive notifications of the following events: delivered, displayed, composing, offline and cancelled. You will probably want to react to some or all of these events.

Usage

The general idea is to create a new MessageEventNotificationListener that will listen to the event notifications and react with custom logic. Then you will have to add the listener to the MessageEventManager that works on the desired XMPPConnection.

• To create a new MessageEventManager use the MessageEventManager(XMPPConnection) constructor.
• To create an event notifications listener create a class that implements the MessageEventNotificationListener interface.
• To add a listener to the messageEventManager use the MessageEventManager's message addMessageEventNotificationListener(MessageEventNotificationListener).

Example

Below you can find an example that logs in a user to the server, adds a MessageEventNotificationListener to a MessageEventManager that will listen and react to the event notifications, creates a message, adds the requests for notifications and sends the message.

// Connect to the server and log in
conn1 = new XMPPConnection(host);
conn1.login(server_user1, pass1);
// Create a MessageEventManager
MessageEventManager messageEventManager = new MessageEventManager(conn1);
// Add the listener that will react to the event notifications
messageEventManager.addMessageEventNotificationListener(new MessageEventNotificationListener() {
	public void deliveredNotification(String from, String packetID) {
	System.out.println("The message has been delivered (" + from + ", " + packetID + ")");
}
public void displayedNotification(String from, String packetID) {
	System.out.println("The message has been displayed (" + from + ", " + packetID + ")");
}
public void composingNotification(String from, String packetID) {
	System.out.println("The message's receiver is composing a reply (" + from + ", " + packetID + ")");
}
public void offlineNotification(String from, String packetID) {
	System.out.println("The message's receiver is offline (" + from + ", " + packetID + ")");
}
public void cancelledNotification(String from, String packetID) {
	System.out.println("The message's receiver cancelled composing a reply (" + from + ", " + packetID + ")");
}
});
// Create a chat with user2
Chat chat1 = conn1.createChat(user2);
// Create a message to send
Message msg = chat1.createMessage();
msg.setSubject("Any subject you want");
msg.setBody("An interesting body comes here...");
// Add to the message all the notifications requests (offline, delivered, displayed,
// composing)
MessageEventManager.addNotificationsRequests(msg, **true**, **true**, **true**, **true**);
// Send the message that contains the notifications request
chat1.sendMessage(msg);