mirror of
https://codeberg.org/Mercury-IM/Smack
synced 2024-11-19 21:12:05 +01:00
168 lines
7.3 KiB
HTML
168 lines
7.3 KiB
HTML
|
<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">
|
||
|
|
« <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 © Jive Software 2002-2006
|
||
|
|
</div>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|