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

Added privacy list support and improved error handling from Francisco (SMACK-121, SMACK-31).

Browse source 
git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@4603 b35dd754-fafc-0310-a699-88a17e54d16e
This commit is contained in:
Matt Tucker 2006-07-19 19:24:00 +00:00 • committed by matt
parent 1716c6ed22
commit 47abf627b7
20 changed files with 2099 additions and 81 deletions
Download patch file Download diff file Expand all files Collapse all files

3
documentation/index.html
View file

@ -25,12 +25,13 @@
<li><a href="providers.html">Provider Architecture</a>
<li><a href="properties.html">Packet Properties</a>
<li><a href="debugging.html">Debugging with Smack</a>
<li><a href="privacy.html">Privacy</a>
<p>
<li><a href="extensions/index.html">Smack Extensions Manual</a>
</ul>
<div class="footer">
Copyright &copy; Jive Software 2002-2005
Copyright &copy; Jive Software 2002-2006
</div>
</body>

167
documentation/privacy.html Normal file
View file

@ -0,0 +1,167 @@
<html>
<head>
<title>Smack: Privacy - Jive Software</title>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>
<body>
<div class="header">
Privacy
</div>
<div class="nav">
&laquo; <a href="index.html">Table of Contents</a>
</div>
<p class="subheader">What is?</p>
<p>
<tt>Privacy</tt> is a method for users to block communications from particular other users. In XMPP this is done by managing one's privacy lists.<br />
Server-side privacy lists enable successful completion of the following use cases:
<ul>
<li>Retrieving one's privacy lists.
<li>Adding, removing, and editing one's privacy lists.
<li>Setting, changing, or declining active lists.
<li>Setting, changing, or declining the default list (i.e., the list that is active by default).
<li>Allowing or blocking messages based on JID, group, or subscription type (or globally).
<li>Allowing or blocking inbound presence notifications based on JID, group, or subscription type (or globally).
<li>Allowing or blocking outbound presence notifications based on JID, group, or subscription type (or globally).
<li>Allowing or blocking IQ stanzas based on JID, group, or subscription type (or globally).
<li>Allowing or blocking all communications based on JID, group, or subscription type (or globally).
</ul>
<p>
<p class="subheader">How can I use it?</p>
<p>
The API implementation releases three main public classes:
<ul>
<li><tt>PrivacyListManager</tt>: this is the main API class to retrieve and handle server privacy lists.
<li><tt>PrivacyList</tt>: witch represents one privacy list, with a name, a set of privacy items. For example, the list with visible or invisible.
<li><tt>PrivacyItem</tt>: block or allow one aspect of privacy. For example, to allow my friend to see my presence.
</ul>
<ol>
<li> Right from the start, a client MAY <b>get his/her privacy list</b> that is stored in the server:<br />
<div class="code">
<pre>
<font color="gray"><i>// Create a privacy manager for the current connection.</i></font>
PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
<font color="gray"><i>// Retrieve server privacy lists</i></font>
PrivacyList[] lists = privacyManager.getPrivacyLists();
</pre>
</div>
Now the client is able to show every <tt>PrivacyItem</tt> of the server and also for every list if it is active, default or none of them. The client is a listener of privacy changes.<br />
<br />
<li> In order to <b>add a new list in the server</b>, the client MAY implement something like:
<div class="code">
<pre>
<font color="gray"><i>// Set the name of the list</i></font>
String listName = <font color="green">"newList"</font>;
<font color="gray"><i>// Create the list of <tt>PrivacyItem</tt> that will allow or deny some privacy aspect</i></font>
String user = <font color="green">"tybalt@example.com"</font>;
String groupName = <font color="green">"enemies"</font>;
ArrayList privacyItems = new ArrayList();
PrivacyItem item = new PrivacyItem(PrivacyRule.<font color="navy"><i>JID</i></font>, <font color="navy">true</font>, 1);
item.setValue(user);
privacyItems.add(item);
item = new PrivacyItem(PrivacyRule.<font color="navy"><i>SUBSCRIPTION</i></font>, <font color="navy">true</font>, 2);
item.setValue(PrivacyRule.<font color="navy"><i>SUBSCRIPTION_BOTH</i></font>);
privacyItems.add(item);
item = new PrivacyItem(PrivacyRule.<font color="navy"><i>GROUP</i></font>, <font color="navy">false</font>, 3);
item.setValue(groupName);
item.setFilterMessage(<font color="navy">true</font>);
privacyItems.add(item);
<font color="gray"><i>// Get the privacy manager for the current connection.</i></font>
PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
<font color="gray"><i>// Create the new list.</i></font>
privacyManager.createPrivacyList(listName, Arrays.<i>asList</i>(privacyItems));
</pre>
</div>
<li> To <b>modify an existent list</b>, the client code MAY be like:
<div class="code">
<pre>
<font color="gray"><i>// Set the name of the list</i></font>
String listName = <font color="green">"existingList"</font>;
<font color="gray"><i>// Get the privacy manager for the current connection.</i></font>
PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
<font color="gray"><i>// Sent the new list to the server.</i></font>
privacyManager.updatePrivacyList(listName, items);
</pre>
</div>
Notice <tt>items</tt> was defined at the example 2 and MUST contain all the elements in the list (not the "delta").
<li> In order to <b>delete an existing list</b>, the client MAY perform something like:
<div class="code">
<pre>
<font color="gray"><i>// Set the name of the list</i></font>
String listName = <font color="green">"existingList"</font>;
<font color="gray"><i>// Get the privacy manager for the current connection.</i></font>
PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
<font color="gray"><i>// Remove the list.</i></font>
privacyManager.deletePrivacyList(listName);
</pre>
</div>
<li> In order to <b>decline the use of an active list</b>, the client MAY perform something like:
<div class="code">
<pre>
<font color="gray"><i>// Get the privacy manager for the current connection.</i></font>
PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
<font color="gray"><i>// Decline the use of the active list.</i></font>
privacyManager.declineActiveList();
</pre>
</div>
<li> In order to <b>decline the use of a default list</b>, the client MAY perform something like:
<div class="code">
<pre>
<font color="gray"><i>// Get the privacy manager for the current connection.</i></font>
PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
<font color="gray"><i>// Decline the use of the default list.</i></font>
privacyManager.declineDefaultList();
</pre>
</div>
</ol>
<p class="subheader">Listening for Privacy Changes</p>
<p>
In order to handle privacy changes, clients SHOULD listen manager's updates.
When a list is changed the manager notifies every added listener. Listeners MUST implement the <tt>PrivacyListListener</tt> interface.
Clients may need to react when a privacy list is modified. The <tt>PrivacyListManager</tt> lets you add listerners that will be notified when a list has been changed. Listeners should implement the <tt>PrivacyListListener</tt> interface.<br />
The most important notification is <tt>updatedPrivacyList</tt> that is performed when a privacy list changes its privacy items.<br />
The listener becomes notified after performing:
<div class="code">
<pre>
<font color="gray"><i>// Get the privacy manager for the current connection.</i></font>
PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
<font color="gray"><i>// Add the listener (this) to get notified</i></font>
privacyManager.addListener(<font color="navy">this</font>);
</pre>
</div>
</p>
<p class="subheader">References</p>
<ul>
<li><a href="http://www.xmpp.org/specs/rfc3921.html#privacy">Blocking communication</a> from the RFC3921.
</ul>
</p>
<br clear="all" /><br><br>
<div class="footer">
Copyright &copy; Jive Software 2002-2006
</div>
</body>
</html>