/** * * Copyright 2015 Florian Schmaus * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * Smacks implementation of XEP-0016: Privacy Lists. *
* Privacy
is a method for users to block communications from particular other users. In XMPP this is done
* by managing one’s privacy lists.
*
* Server-side privacy lists enable successful completion of the following use cases: *
** The API implementation releases three main public classes: *
*PrivacyListManager
: this is the main API class to retrieve and handle server privacy lists.PrivacyList
: witch represents one privacy list, with a name, a set of privacy items. For example,
* the list with visible or invisible.PrivacyItem
: block or allow one aspect of privacy. For example, to allow my friend to see my
* presence.
*
* // Create a privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Retrieve server privacy lists_
* PrivacyList[] lists = privacyManager.getPrivacyLists();
*
*
*
* Now the client is able to show every PrivacyItem
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.
*
*
* // Set the name of the list_
* String listName = "newList";
*
* // Create the list of PrivacyItem that will allow or deny some privacy aspect_
* String user = "tybalt@example.com";
* String groupName = "enemies";
* ArrayList privacyItems = new ArrayList();
*
* PrivacyItem item = new PrivacyItem(PrivacyItem.Type.jid, user, true, 1);
* privacyItems.add(item);
*
* item = new PrivacyItem(PrivacyItem.Type.subscription, PrivacyItem.SUBSCRIPTION_BOTH, true, 2);
* privacyItems.add(item);
*
* item = new PrivacyItem(PrivacyItem.Type.group, groupName, false, 3);
* item.setFilterMessage(true);
* privacyItems.add(item);
*
* // Get the privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Create the new list._
* privacyManager.createPrivacyList(listName, privacyItems);
*
*
*
*
* // Set the name of the list_
* String listName = "existingList";
* // Get the privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Sent the new list to the server._
* privacyManager.updatePrivacyList(listName, items);
*
*
*
* Notice items
was defined at the example 2 and MUST contain all the elements in the list (not the
* “delta”).
*
*
* // Set the name of the list_
* String listName = "existingList";
* // Get the privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Remove the list._
* privacyManager.deletePrivacyList(listName);
*
*
*
*
* // Get the privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Decline the use of the active list._
* privacyManager.declineActiveList();
*
*
*
*
* // Get the privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Decline the use of the default list._
* privacyManager.declineDefaultList();
*
*
* * Listening for Privacy Changes *
*
* 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 PrivacyListListener
interface. Clients may
* need to react when a privacy list is modified. The PrivacyListManager
lets you add listerners that will
* be notified when a list has been changed. Listeners should implement the PrivacyListListener
interface.
*
* The most important notification is updatedPrivacyList
that is performed when a privacy list changes its
* privacy items.
*
* The listener becomes notified after performing: *
* *
*
* // Get the privacy manager for the current connection._
* PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
* // Add the listener (this) to get notified_
* privacyManager.addListener(this);
*
*
*/
package org.jivesoftware.smackx.privacy;