From cb97e13b9045d79f3533a3fc63007f2b73faf09a Mon Sep 17 00:00:00 2001 From: Matt Tucker Date: Tue, 19 Aug 2003 13:20:42 +0000 Subject: [PATCH] Adding extensions documentation that was written by Gato. git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@2037 b35dd754-fafc-0310-a699-88a17e54d16e --- documentation/extensions/index.html | 15 ++ documentation/extensions/intro.html | 16 ++ documentation/extensions/messageevents.html | 224 +++++++++++++++++++ documentation/extensions/privatedata.html | 15 ++ documentation/extensions/rosterexchange.html | 144 ++++++++++++ documentation/extensions/time.html | 15 ++ documentation/extensions/toc.html | 20 ++ 7 files changed, 449 insertions(+) create mode 100644 documentation/extensions/index.html create mode 100644 documentation/extensions/intro.html create mode 100644 documentation/extensions/messageevents.html create mode 100644 documentation/extensions/privatedata.html create mode 100644 documentation/extensions/rosterexchange.html create mode 100644 documentation/extensions/time.html create mode 100644 documentation/extensions/toc.html diff --git a/documentation/extensions/index.html b/documentation/extensions/index.html new file mode 100644 index 000000000..b6a6805d6 --- /dev/null +++ b/documentation/extensions/index.html @@ -0,0 +1,15 @@ + + + + +Smack Extensions User Manual + + + + + + + +<H2>Smack Extensions User Manual</H2> + +<a href="toc.html">Smack Extensions User Manual</a> \ No newline at end of file diff --git a/documentation/extensions/intro.html b/documentation/extensions/intro.html new file mode 100644 index 000000000..0a8c789d2 --- /dev/null +++ b/documentation/extensions/intro.html @@ -0,0 +1,16 @@ + + +Smack Extensions User Manual + + + +

Smack Extensions Manual

+

The XMPP protocol includes a base protocol and many optional extensions. Smack provides the + org.jivesoftware.smack package for the core XMPP protocol, and the org.jivesoftware.smackx package for + many of the protocol extensions.

+ +

This manual provides details about each of the "smackx" extensions, including what + it is, how to use it, and some simple example code. + + + \ No newline at end of file diff --git a/documentation/extensions/messageevents.html b/documentation/extensions/messageevents.html new file mode 100644 index 000000000..5b3851111 --- /dev/null +++ b/documentation/extensions/messageevents.html @@ -0,0 +1,224 @@ + + + + +Message Events + + + + +

Message Events Support

+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. +

For more information on each stage please follow these links:

+ +JEP related: JEP-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, delivered, displayed,
+      // 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.

+ +

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 request
+              System.out.println("Delivered Notification Requested (" + from + ", " + packetID + ")");
+          }
+
+          public void displayedNotificationRequested(
+              String from,
+              String packetID,
+              MessageEventManager messageEventManager) {
+              super.displayedNotificationRequested(from, packetID, messageEventManager);
+              // Send to the message's sender that the message was displayed
+              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. + +

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);
+
+
+ + + + \ No newline at end of file diff --git a/documentation/extensions/privatedata.html b/documentation/extensions/privatedata.html new file mode 100644 index 000000000..633f081cb --- /dev/null +++ b/documentation/extensions/privatedata.html @@ -0,0 +1,15 @@ + + + + +Private Data + + + + +

Private Data Support

+Comming soon + + + + \ No newline at end of file diff --git a/documentation/extensions/rosterexchange.html b/documentation/extensions/rosterexchange.html new file mode 100644 index 000000000..1751159c2 --- /dev/null +++ b/documentation/extensions/rosterexchange.html @@ -0,0 +1,144 @@ + + + + +Roster Item Exchange + + + + +

Roster Item Exchange Support

+This extension is used to send rosters, roster groups and roster entries from one XMPP +Entity to another. It also provides an easy way to hook up custom logic when entries +are received from other XMPP clients. +

Follow these links to learn how to send and receive roster items:

+ +JEP related: JEP-93 +
+

Send a complete roster

+

Description

+Sometimes it is useful to send a whole roster to another user. Smack provides a +very easy way to send a complete roster to another XMPP client. +

Usage

+Create an instance of RosterExchangeManager and use the #send(Roster, String) +message to send a roster to a given user. The first parameter is the roster to send and +the second parameter is the id of the user that will receive the roster entries. +

Example

+In this example we can see how user1 sends his roster to user2. +
+
      // Connect to the server and log in
+      conn1 = new XMPPConnection(host);
+      conn1.login(server_user1, pass1);
+    
+      // Create a new roster exchange manager on conn1
+      RosterExchangeManager rosterExchangeManager = new RosterExchangeManager(conn1);
+      // Send user1's roster to user2
+      rosterExchangeManager.send(conn1.getRoster(), user2);
+
+
+
+

Send a roster's group

+

Description

+It is also possible to send a roster group to another XMPP client. A roster group groups +a set of roster entries under a name. +

Usage

+Create an instance of RosterExchangeManager and use the #send(RosterGroup, String) +message to send a roster group to a given user. The first parameter is the roster group to send and +the second parameter is the id of the user that will receive the roster entries. +

Example

+In this example we can see how user1 sends his roster groups to user2. +
+
      // Connect to the server and log in
+      conn1 = new XMPPConnection(host);
+      conn1.login(server_user1, pass1);
+    
+      // Create a new roster exchange manager on conn1
+      RosterExchangeManager rosterExchangeManager = new RosterExchangeManager(conn1);
+      // Send user1's RosterGroups to user2
+      for (Iterator it = conn1.getRoster().getGroups(); it.hasNext(); )
+          rosterExchangeManager.send((RosterGroup)it.next(), user2);
+
+
+
+

Send a roster's entry

+

Description

+Sometimes you may need to send a single roster entry to another XMPP client. Smack also lets you send +items at this granularity level. +

Usage

+Create an instance of RosterExchangeManager and use the #send(RosterEntry, String) +message to send a roster entry to a given user. The first parameter is the roster entry to send and +the second parameter is the id of the user that will receive the roster entries. +

Example

+In this example we can see how user1 sends a roster entry to user2. +
+
      // Connect to the server and log in
+      conn1 = new XMPPConnection(host);
+      conn1.login(server_user1, pass1);
+    
+      // Create a new roster exchange manager on conn1
+      RosterExchangeManager rosterExchangeManager = new RosterExchangeManager(conn1);
+      // Send a roster entry (any) to user2
+      rosterExchangeManager1.send((RosterEntry)conn1.getRoster().getEntries().next(), user2);
+
+
+

Receive roster entries

+

Description

+Since roster items are sent between XMPP clients, it is necessary to listen to possible roster entries +receptions. Smack provides a mechanism that you can use to execute custom logic when roster entries are +received. +

Usage

+
    +
  1. Create a class that implements the RosterExchangeListener interface.
    2. +
  2. Implement the method entriesReceived(String, Iterator) that will be called when new entries + are received with custom logic.
    3. +
  3. Add the listener to the RosterExchangeManager that works on the desired XMPPConnection.
    4. +
+

Example

+In this example we can see how user1 sends a roster entry to user2 and user2 adds the received +entries to his roster. +
+
      // 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);
+      final Roster user2_roster = conn2.getRoster();
+    
+      // Create a RosterExchangeManager that will help user2 to listen and accept
+      the entries received
+      RosterExchangeManager rosterExchangeManager2 = new RosterExchangeManager(conn2);
+      // Create a RosterExchangeListener that will iterate over the received roster entries
+      RosterExchangeListener rosterExchangeListener = new RosterExchangeListener() {
+          public void entriesReceived(String from, Iterator rosterEntries) {
+              for (Iterator it = rosterEntries; it.hasNext();) {
+                  try {
+                      // Get the received entry
+                      RosterEntry entry = (RosterEntry) it.next();
+                      // Display the entry on the console
+                      System.out.println(entry);
+                      // Add the entry to the user2's roster
+                      user2_roster.createEntry(entry);
+                  }
+                  catch (XMPPException e) {
+                      e.printStackTrace();
+                  }
+              }
+          }
+      };
+      // Add the RosterExchangeListener to the RosterExchangeManager that user2 is using
+      rosterExchangeManager2.addRosterListener(rosterExchangeListener);
+    
+      // Create a RosterExchangeManager that will help user1 to send his roster
+      RosterExchangeManager rosterExchangeManager1 = new RosterExchangeManager(conn1);
+      // Send user1's roster to user2
+      rosterExchangeManager1.send(conn1.getRoster(), user2);
+
+
+ + + \ No newline at end of file diff --git a/documentation/extensions/time.html b/documentation/extensions/time.html new file mode 100644 index 000000000..1cabc6fd8 --- /dev/null +++ b/documentation/extensions/time.html @@ -0,0 +1,15 @@ + + + + +Time + + + + +

Time Exchange Support

+Comming soon + + + + \ No newline at end of file diff --git a/documentation/extensions/toc.html b/documentation/extensions/toc.html new file mode 100644 index 000000000..5a19e0097 --- /dev/null +++ b/documentation/extensions/toc.html @@ -0,0 +1,20 @@ + + + + +Smack Extensions User Manual + + + + + +Introduction +

Smack extensions

+Private Data
+Message Events
+Roster Item Exchange
+Time Exchange
+

+ + + \ No newline at end of file