From 47abf627b7aba2a19b1e98466f7f6a6e5eda9994 Mon Sep 17 00:00:00 2001
From: Matt Tucker
Date: Wed, 19 Jul 2006 19:24:00 +0000
Subject: [PATCH] Added privacy list support and improved error handling from
Francisco (SMACK-121, SMACK-31).
git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@4603 b35dd754-fafc-0310-a699-88a17e54d16e
---
build/resources/META-INF/smack-config.xml | 1 +
build/resources/META-INF/smack.providers | 7 +
documentation/index.html | 3 +-
documentation/privacy.html | 167 +++++++
.../org/jivesoftware/smack/PacketReader.java | 2 +-
.../org/jivesoftware/smack/PrivacyList.java | 57 +++
.../smack/PrivacyListListener.java | 30 ++
.../smack/PrivacyListManager.java | 442 +++++++++++++++++
.../jivesoftware/smack/XMPPConnection.java | 23 +-
.../jivesoftware/smack/packet/Privacy.java | 315 ++++++++++++
.../smack/packet/PrivacyItem.java | 454 ++++++++++++++++++
.../jivesoftware/smack/packet/XMPPError.java | 434 ++++++++++++++++-
.../smack/provider/PrivacyProvider.java | 134 ++++++
.../smack/util/PacketParserUtils.java | 77 +--
.../smackx/ServiceDiscoveryManager.java | 4 +-
.../filetransfer/FileTransferManager.java | 2 +-
.../filetransfer/FileTransferNegotiator.java | 17 +-
.../filetransfer/IBBTransferNegotiator.java | 2 +-
.../Socks5TransferNegotiator.java | 5 +-
.../org/jivesoftware/smackx/packet/VCard.java | 4 +-
20 files changed, 2099 insertions(+), 81 deletions(-)
create mode 100644 documentation/privacy.html
create mode 100644 source/org/jivesoftware/smack/PrivacyList.java
create mode 100644 source/org/jivesoftware/smack/PrivacyListListener.java
create mode 100644 source/org/jivesoftware/smack/PrivacyListManager.java
create mode 100644 source/org/jivesoftware/smack/packet/Privacy.java
create mode 100644 source/org/jivesoftware/smack/packet/PrivacyItem.java
create mode 100644 source/org/jivesoftware/smack/provider/PrivacyProvider.java
diff --git a/build/resources/META-INF/smack-config.xml b/build/resources/META-INF/smack-config.xml
index eb0ea25ce..09068ad76 100644
--- a/build/resources/META-INF/smack-config.xml
+++ b/build/resources/META-INF/smack-config.xml
@@ -5,6 +5,7 @@
org.jivesoftware.smackx.ServiceDiscoveryManager
+ org.jivesoftware.smack.PrivacyListManager
org.jivesoftware.smackx.XHTMLManager
org.jivesoftware.smackx.muc.MultiUserChat
org.jivesoftware.smackx.filetransfer.FileTransferManager
diff --git a/build/resources/META-INF/smack.providers b/build/resources/META-INF/smack.providers
index 98867a4fa..3e3a66f00 100644
--- a/build/resources/META-INF/smack.providers
+++ b/build/resources/META-INF/smack.providers
@@ -180,4 +180,11 @@
org.jivesoftware.smackx.provider.IBBProviders$Data
+
+
+ query
+ jabber:iq:privacy
+ org.jivesoftware.smack.provider.PrivacyProvider
+
+
\ No newline at end of file
diff --git a/documentation/index.html b/documentation/index.html
index 282a3f745..b7e6afb7a 100644
--- a/documentation/index.html
+++ b/documentation/index.html
@@ -25,12 +25,13 @@
Provider Architecture
Packet Properties
Debugging with Smack
+ Privacy
Smack Extensions Manual
+
+
+
+
+
+
+
+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:
+
+- Retrieving one's privacy lists.
+
- Adding, removing, and editing one's privacy lists.
+
- Setting, changing, or declining active lists.
+
- Setting, changing, or declining the default list (i.e., the list that is active by default).
+
- Allowing or blocking messages based on JID, group, or subscription type (or globally).
+
- Allowing or blocking inbound presence notifications based on JID, group, or subscription type (or globally).
+
- Allowing or blocking outbound presence notifications based on JID, group, or subscription type (or globally).
+
- Allowing or blocking IQ stanzas based on JID, group, or subscription type (or globally).
+
- Allowing or blocking all communications based on JID, group, or subscription type (or globally).
+
+
+
+
+
+
+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.
+
+
+- Right from the start, a client MAY get his/her privacy list that is stored in the server:
+
+
+ // 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.
+
+ - In order to add a new list in the server, the client MAY implement something like:
+
+
+ // 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(PrivacyRule.JID, true, 1);
+ item.setValue(user);
+ privacyItems.add(item);
+
+ item = new PrivacyItem(PrivacyRule.SUBSCRIPTION, true, 2);
+ item.setValue(PrivacyRule.SUBSCRIPTION_BOTH);
+ privacyItems.add(item);
+
+ item = new PrivacyItem(PrivacyRule.GROUP, false, 3);
+ item.setValue(groupName);
+ 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, Arrays.asList(privacyItems));
+
+
+
+ - To modify an existent list, the client code MAY be like:
+
+
+ // 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").
+
+ - In order to delete an existing list, the client MAY perform something like:
+
+
+ // 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);
+
+
+
+ - In order to decline the use of an active list, the client MAY perform something like:
+
+
+ // Get the privacy manager for the current connection.
+ PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
+ // Decline the use of the active list.
+ privacyManager.declineActiveList();
+
+
+
+ - In order to decline the use of a default list, the client MAY perform something like:
+
+
+ // Get the privacy manager for the current connection.
+ PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
+ // Decline the use of the default list.
+ privacyManager.declineDefaultList();
+
+
+
+
+
+
+
+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);
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/documentation/privacy.html b/documentation/privacy.html
new file mode 100644
index 000000000..0d6d2335e
--- /dev/null
+++ b/documentation/privacy.html
@@ -0,0 +1,167 @@
+
+