mirror of
https://codeberg.org/Mercury-IM/Smack
synced 2024-11-14 11:42:04 +01:00
6110872062
Use Type enum instead of String for PrivacyItem's constructor. Add getName() to PrivacyList. Remove PrivacyRule, as it just adds unnecessary complexity spliting PrivacyItem and PrivacyRule, they belong together. Don't mix camel-case and c-style method names. Some minor improvements. Add parser test.
164 lines
7.1 KiB
HTML
164 lines
7.1 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(PrivacyItem.Type.jid, user, <font color="navy">true</font>, 1);
|
|
privacyItems.add(item);
|
|
|
|
item = new PrivacyItem(PrivacyItem.Type.subscription, PrivacyItem.SUBSCRIPTION_BOTH, <font color="navy">true</font>, 2);
|
|
privacyItems.add(item);
|
|
|
|
item = new PrivacyItem(PrivacyItem.Type.group, groupName, <font color="navy">false</font>, 3);
|
|
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, 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://xmpp.org/extensions/xep-0016.html">XEP-0016: Privacy Lists</a>
|
|
</ul>
|
|
</p>
|
|
|
|
<br clear="all" /><br><br>
|
|
|
|
<div class="footer">
|
|
Copyright © Jive Software 2002-2008
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|