diff --git a/documentation/extensions/index.md b/documentation/extensions/index.md index 33bcd13da..bbcce3955 100644 --- a/documentation/extensions/index.md +++ b/documentation/extensions/index.md @@ -26,7 +26,6 @@ Smack Extensions and currently supported XEPs by Smack (smack-extensions) | Last Activity | [XEP-0012](http://xmpp.org/extensions/xep-0012.html) | Communicating information about the last activity associated with an XMPP entity. | | Flexible Offline Message Retrieval | [XEP-0013](http://xmpp.org/extensions/xep-0013.html) | Extension for flexible, POP3-like handling of offline messages. | | [Privacy Lists](privacy.html) | [XEP-0016](http://xmpp.org/extensions/xep-0016.html) | Enabling or disabling communication with other entities. | -| [Message Events](messageevents.html) | [XEP-0022](http://xmpp.org/extensions/xep-0022.html) | Requests and responds to message events. | | [Service Discovery](disco.html) | [XEP-0030](http://xmpp.org/extensions/xep-0030.html) | Allows to discover services in XMPP entities. | | Extended Stanza Addressing | [XEP-0033](http://xmpp.org/extensions/xep-0033.html) | Allows to include headers in stanzas in order to specifiy multiple recipients or sub-addresses. | | [Multi User Chat](muc.html) | [XEP-0045](http://xmpp.org/extensions/xep-0045.html) | Allows configuration of, participation in, and administration of individual text-based conference rooms. | @@ -79,4 +78,6 @@ If a XEP becomes 'Deprecated' or 'Obsolete' the code will be moved to the *smack | Name | XEP | Description | |---------------------------------------------|----------------------------------------------------------|----------------------------------------------------------------------------------------------------------| +| [Message Events](messageevents.html) | [XEP-0022](http://xmpp.org/extensions/xep-0022.html) | Requests and responds to message events. | + | [Roster Item Exchange](rosterexchange.html) | [XEP-0093](http://xmpp.org/extensions/xep-0093.html) | Allows roster data to be shared between users. | diff --git a/documentation/extensions/messageevents.md b/documentation/extensions/messageevents.md deleted file mode 100644 index 9665ecddf..000000000 --- a/documentation/extensions/messageevents.md +++ /dev/null @@ -1,205 +0,0 @@ -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](http://www.xmpp.org/extensions/xep-0022.html) - -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); -```