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 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. +display, and composition of messages. There are three stages in this extension:
For more information on each stage please follow these links:
+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. -
+ 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.
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.
@@ -55,12 +60,18 @@ for notifications and sends the message. chat1.sendMessage(msg);
+ +Description
+ You can receive notification requests for the following events: delivered, displayed, composing and offline. You -must listen for these requests and react accordingly. -
+ 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 @@ -78,8 +89,10 @@ implements the MessageEventRequestListener interface, please remember to
+ 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 @@ -150,13 +163,19 @@ to a MessageEventManager that will listen and react to the event notifica messageEventManager.sendCancelledNotification(user1, msg.getPacketID()); +
+ 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. -
+ 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. @@ -168,8 +187,9 @@ the desired XMPPConnection.
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. diff --git a/documentation/extensions/privatedata.html b/documentation/extensions/privatedata.html index a00defc81..4d0f65887 100644 --- a/documentation/extensions/privatedata.html +++ b/documentation/extensions/privatedata.html @@ -1,14 +1,29 @@ -
+ +Manages private data, which is a mechanism to allow users to store arbitrary XML +data on an XMPP server. Each private data chunk is defined by a element name and +XML namespace. Example private data: + +
+<color xmlns="http://example.com/xmpp/color"> + <favorite>blue</blue> + <leastFavorite>puce</leastFavorite> +</color> +
+ +JEP related: JEP-49 + +
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. @@ -19,16 +18,24 @@ are received from other XMPP clients.
+ 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. -
+ 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. -
+ In this example we can see how user1 sends his roster to user2.
// Connect to the server and log in @@ -41,16 +48,24 @@ In this example we can see how user1 sends his roster to user2. rosterExchangeManager.send(conn1.getRoster(), user2);
+ 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. -
+ 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. -
+ In this example we can see how user1 sends his roster groups to user2.
// Connect to the server and log in @@ -64,16 +79,24 @@ In this example we can see how user1 sends his roster groups to user2. rosterExchangeManager.send((RosterGroup)it.next(), user2);
+ Sometimes you may need to send a single roster entry to another XMPP client. Smack also lets you send -items at this granularity level. -
+ 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. -
+ In this example we can see how user1 sends a roster entry to user2.
// Connect to the server and log in @@ -86,19 +109,28 @@ In this example we can see how user1 sends a roster entry to user2. rosterExchangeManager1.send((RosterEntry)conn1.getRoster().getEntries().next(), user2);
+ 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. -
+
+ In this example we can see how user1 sends a roster entry to user2 and user2 adds the received entries to his roster.
diff --git a/documentation/extensions/style.css b/documentation/extensions/style.css new file mode 100644 index 000000000..5fbf1a70f --- /dev/null +++ b/documentation/extensions/style.css @@ -0,0 +1,57 @@ +BODY { + font-size : 100%; + background-color : #fff; +} +BODY, TD, TH { + font-family : tahoma, arial, helvetica; + font-size : 0.8em; +} +PRE, TT, CODE { + font-family : courier new, monospaced; + font-size : 1.0em; +} +A:hover { + text-decoration : none; +} +LI { + padding-bottom : 4px; +} +.header { + font-size : 1.4em; + font-weight : bold; + width : 100%; + border-bottom : 1px #ccc solid; + padding-bottom : 2px; +} +.subheader { + font-size: 1.1em; + font-weight : bold; +} +.footer { + font-size : 0.8em; + color : #999; + text-align : center; + width : 100%; + border-top : 1px #ccc solid; + padding-top : 2px; +} +.code { + border : 1px #ccc solid; + padding : 0em 1.0em 0em 1.0em; + margin : 4px 0px 4px 0px; +} +.nav, .nav A { + font-family : verdana; + font-size : 0.85em; + color : #600; + text-decoration : none; + font-weight : bold; +} +.nav { + width : 100%; + border-bottom : 1px #ccc solid; + padding : 3px 3px 5px 1px; +} +.nav A:hover { + text-decoration : underline; +} \ No newline at end of file diff --git a/documentation/extensions/time.html b/documentation/extensions/time.html index 20bd5c13d..7c00efa77 100644 --- a/documentation/extensions/time.html +++ b/documentation/extensions/time.html @@ -1,14 +1,21 @@ - - - -Time + + Time + -Time Exchange Support -Coming soon +Entity Time Exchange + +Supports a protocol that XMPP clients use to exchange their respective local +times and time zones. + +JEP related: JEP-90 + + + +More coming soon. diff --git a/documentation/extensions/toc.html b/documentation/extensions/toc.html index 5a19e0097..aa23f0a94 100644 --- a/documentation/extensions/toc.html +++ b/documentation/extensions/toc.html @@ -1,15 +1,16 @@ - - Smack Extensions User Manual + -Introduction -Smack extensions +Introduction + +Smack Extensions + Private Data Message Events Roster Item Exchange
+ +Supports a protocol that XMPP clients use to exchange their respective local +times and time zones.
+ +JEP related: JEP-90 + +
+ +
+ Private Data Message Events Roster Item Exchange