2006-07-19 21:24:00 +02:00
< 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" >
2008-11-03 17:28:57 +01:00
Copyright © Jive Software 2002-2008
2006-07-19 21:24:00 +02:00
< / div >
< / body >
< / html >
