mirror of
https://codeberg.org/Mercury-IM/Smack
synced 2024-12-22 20:47:57 +01:00
Message Evenents is in smack-legacy and documentation/legacy
This commit is contained in:
parent
9e797c1b17
commit
6168fca288
2 changed files with 2 additions and 206 deletions
|
@ -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. |
|
||||
|
|
|
@ -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);
|
||||
```
|
Loading…
Reference in a new issue