vanitasvitae/Smack
1
0
Fork 0
mirror of https://github.com/vanitasvitae/Smack.git synced 2025-09-10 09:39:39 +02:00
Code Issues Releases Wiki Activity

Adding extensions documentation that was written by Gato.

Browse source 
git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@2037 b35dd754-fafc-0310-a699-88a17e54d16e
This commit is contained in:
Matt Tucker 2003-08-19 13:20:42 +00:00 • committed by mtucker
parent c817d02351
commit cb97e13b90
7 changed files with 449 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

144
documentation/extensions/rosterexchange.html Normal file
View file

@ -0,0 +1,144 @@
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Roster Item Exchange</title>
</head>
<body>
<h1>Roster Item Exchange Support</h1>
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.
<p>Follow these links to learn how to send and receive roster items:</p>
<ul>
<li><a href="#riesendroster">Send a complete roster</a></li>
<li><a href="#riesendgroup">Send a roster's group</a></li>
<li><a href="#riesendentry">Send a roster's entry</a></li>
<li><a href="#riercventry">Receive roster entries</a></li>
</ul>
<b>JEP related:</b> <a href="http://www.jabber.org/jeps/jep-0093.html">JEP-93</a>
<hr>
<h2><a name="riesendroster">Send a complete roster</a></h2>
<h3>Description</h3>
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.
<h3>Usage</h3>
Create an instance of <i><b>RosterExchangeManager</b></i> and use the <b>#send(Roster, String)</b>
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.
<h3>Example</h3>
In this example we can see how user1 sends his roster to user2.
<blockquote>
<pre> <font color="#3f7f5f">// Connect to the server and log in</font>
conn1 = new XMPPConnection(host);
conn1.login(server_user1, pass1);
<font color="#3f7f5f">// Create a new roster exchange manager on conn1</font>
RosterExchangeManager rosterExchangeManager = new RosterExchangeManager(conn1);
<font color="#3f7f5f">// Send user1's roster to user2</font>
rosterExchangeManager.send(conn1.getRoster(), user2);
</pre>
</blockquote>
<hr>
<h2><a name="riesendgroup">Send a roster's group</a></h2>
<h3>Description</h3>
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.
<h3>Usage</h3>
Create an instance of <i><b>RosterExchangeManager</b></i> and use the <b>#send(RosterGroup, String)</b>
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.
<h3>Example</h3>
In this example we can see how user1 sends his roster groups to user2.
<blockquote>
<pre> <font color="#3f7f5f">// Connect to the server and log in</font>
conn1 = new XMPPConnection(host);
conn1.login(server_user1, pass1);
<font color="#3f7f5f">// Create a new roster exchange manager on conn1</font>
RosterExchangeManager rosterExchangeManager = new RosterExchangeManager(conn1);
<font color="#3f7f5f">// Send user1's RosterGroups to user2</font>
for (Iterator it = conn1.getRoster().getGroups(); it.hasNext(); )
rosterExchangeManager.send((RosterGroup)it.next(), user2);
</pre>
</blockquote>
<hr>
<h2><a name="riesendentry">Send a roster's entry</a></h2>
<h3>Description</h3>
Sometimes you may need to send a single roster entry to another XMPP client. Smack also lets you send
items at this granularity level.
<h3>Usage</h3>
Create an instance of <i><b>RosterExchangeManager</b></i> and use the <b>#send(RosterEntry, String)</b>
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.
<h3>Example</h3>
In this example we can see how user1 sends a roster entry to user2.
<blockquote>
<pre> <font color="#3f7f5f">// Connect to the server and log in</font>
conn1 = new XMPPConnection(host);
conn1.login(server_user1, pass1);
<font color="#3f7f5f">// Create a new roster exchange manager on conn1</font>
RosterExchangeManager rosterExchangeManager = new RosterExchangeManager(conn1);
<font color="#3f7f5f">// Send a roster entry (any) to user2</font>
rosterExchangeManager1.send((RosterEntry)conn1.getRoster().getEntries().next(), user2);
</pre>
</blockquote>
<hr><h2><a name="riercventry">Receive roster entries</a></h2>
<h3>Description</h3>
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.
<h3>Usage</h3>
<ol>
<li>Create a class that implements the <i><b>RosterExchangeListener</b></i> interface.</li>
<li>Implement the method <b>entriesReceived(String, Iterator)</b> that will be called when new entries
are received with custom logic.</li>
<li>Add the listener to the <i>RosterExchangeManager</i> that works on the desired <i>XMPPConnection</i>.</li>
</ol>
<h3>Example</h3>
In this example we can see how user1 sends a roster entry to user2 and user2 adds the received
entries to his roster.
<blockquote>
<pre> <font color="#3f7f5f">// Connect to the server and log in the users</font>
conn1 = new XMPPConnection(host);
conn1.login(server_user1, pass1);
conn2 = new XMPPConnection(host);
conn2.login(server_user2, pass2);
final Roster user2_roster = conn2.getRoster();
<font color="#3f7f5f">// Create a RosterExchangeManager that will help user2 to listen and accept
the entries received</font>
RosterExchangeManager rosterExchangeManager2 = new RosterExchangeManager(conn2);
<font color="#3f7f5f">// Create a RosterExchangeListener that will iterate over the received roster entries</font>
RosterExchangeListener rosterExchangeListener = new RosterExchangeListener() {
public void entriesReceived(String from, Iterator rosterEntries) {
for (Iterator it = rosterEntries; it.hasNext();) {
try {
<font color="#3f7f5f">// Get the received entry</font>
RosterEntry entry = (RosterEntry) it.next();
<font color="#3f7f5f">// Display the entry on the console</font>
System.out.println(entry);
<font color="#3f7f5f">// Add the entry to the user2's roster</font>
user2_roster.createEntry(entry);
}
catch (XMPPException e) {
e.printStackTrace();
}
}
}
};
<font color="#3f7f5f">// Add the RosterExchangeListener to the RosterExchangeManager that user2 is using</font>
rosterExchangeManager2.addRosterListener(rosterExchangeListener);
<font color="#3f7f5f">// Create a RosterExchangeManager that will help user1 to send his roster</font>
RosterExchangeManager rosterExchangeManager1 = new RosterExchangeManager(conn1);
<font color="#3f7f5f">// Send user1's roster to user2</font>
rosterExchangeManager1.send(conn1.getRoster(), user2);
</pre>
</blockquote>
</body>
</html>