232 lines
8.9 KiB
Objective-C
232 lines
8.9 KiB
Objective-C
#import <Foundation/Foundation.h>
|
|
#import "XMPPModule.h"
|
|
|
|
#if TARGET_OS_IPHONE
|
|
#import <KissXML/DDXML.h>
|
|
#endif
|
|
|
|
#define _XMPP_PRIVACY_H
|
|
|
|
@class XMPPIQ;
|
|
|
|
extern NSString *const XMPPPrivacyErrorDomain;
|
|
|
|
typedef enum XMPPPrivacyErrorCode
|
|
{
|
|
XMPPPrivacyQueryTimeout, // No response from server
|
|
XMPPPrivacyDisconnect, // XMPP disconnection
|
|
|
|
} XMPPPrivacyErrorCode;
|
|
|
|
|
|
|
|
@interface XMPPPrivacy : XMPPModule
|
|
{
|
|
BOOL autoRetrievePrivacyListNames;
|
|
BOOL autoRetrievePrivacyListItems;
|
|
BOOL autoClearPrivacyListInfo;
|
|
|
|
NSMutableDictionary *privacyDict;
|
|
NSString *activeListName;
|
|
NSString *defaultListName;
|
|
|
|
NSMutableDictionary *pendingQueries;
|
|
}
|
|
|
|
/**
|
|
* Whether or not the module should automatically retrieve the privacy list names.
|
|
* If this property is enabled, then the list is automatically fetched when the client signs in.
|
|
*
|
|
* The default value is YES.
|
|
**/
|
|
@property (readwrite, assign) BOOL autoRetrievePrivacyListNames;
|
|
|
|
/**
|
|
* Whether or not the module should automatically retrieve the privacy list rules.
|
|
* If this property is enabled, then the rules for each privacy list are automatically fetched.
|
|
*
|
|
* In other words, if the privacy list names are fetched (either automatically, or via retrieveListNames),
|
|
* then the module will automatically fetch the associated rules.
|
|
* It will also update the set of rules if we receive a "privacy list push"
|
|
* from the server that another resource has changed one of the privacy lists.
|
|
*
|
|
* The default value is YES.
|
|
**/
|
|
@property (readwrite, assign) BOOL autoRetrievePrivacyListItems;
|
|
|
|
/**
|
|
* Whether the module should automatically clear the privacy list info when the client disconnects.
|
|
*
|
|
* As per the XEP, if there are multiple resources signed in for the user,
|
|
* and one resource makes changes to a privacy list, all other resources are "pushed" a notification.
|
|
* However, if our client is disconnected when another resource makes the changes,
|
|
* then the only way we can find out about the changes are to redownload the privacy lists.
|
|
*
|
|
* It is recommended to clear the privacy list to assure we have the correct info.
|
|
* However, there may be specific situations in which an xmpp client can be sure the privacy list won't change.
|
|
*
|
|
* The default value is YES.
|
|
**/
|
|
@property (readwrite, assign) BOOL autoClearPrivacyListInfo;
|
|
|
|
/**
|
|
* Manual fetch of list names and rules, and manual control over when to clear stored info.
|
|
**/
|
|
- (void)retrieveListNames;
|
|
- (void)retrieveListWithName:(NSString *)privacyListName;
|
|
- (void)clearPrivacyListInfo;
|
|
|
|
/**
|
|
* Returns the privacy list names.
|
|
* This is an array of strings.
|
|
**/
|
|
- (NSArray *)listNames;
|
|
|
|
/**
|
|
* Returns the privacy list rules/items for the given list name.
|
|
*
|
|
* The result is an array or privacy items (NSXMLElement's).
|
|
* The array is sorted according to order, where the item with the smallest 'order' is first in the array.
|
|
**/
|
|
- (NSArray *)listWithName:(NSString *)privacyListName;
|
|
|
|
/**
|
|
* Returns information about the active list.
|
|
* If there is no active list, the methods return nil.
|
|
*
|
|
* The activeList method is a convenience method for [modPriv listWithName:[modPriv activeListName]]
|
|
**/
|
|
- (NSString *)activeListName;
|
|
- (NSArray *)activeList;
|
|
|
|
/**
|
|
* Returns information about the default list.
|
|
* If there is no default list, the methods return nil.
|
|
*
|
|
* The defaultList method is a convenience method for [modPriv listWithName:[modPriv defaultListName]]
|
|
**/
|
|
- (NSString *)defaultListName;
|
|
- (NSArray *)defaultList;
|
|
|
|
/**
|
|
* Changes the client's active privacy list to the list with the given name.
|
|
* The privacy list name must match the name of an existing privacy list.
|
|
*
|
|
* To decline the use of an active list simply pass nil to this method.
|
|
*
|
|
* Once the server has acknowledged the change,
|
|
* the delegate method xmppPrivacy:didSetActiveListName: will be invoked.
|
|
* If the server is unable to process the change (e.g. invalid list name),
|
|
* the delegate method xmppPrivacy:didNotSetActiveListName:error: will be invoked.
|
|
*
|
|
* The methods activeListName and activeList will update after the server acknowledges the change.
|
|
**/
|
|
- (void)setActiveListName:(NSString *)privacyListName;
|
|
|
|
/**
|
|
* Changes the client's default privacy list to the list with the given name.
|
|
* The privacy list name must match the name of an existing privacy list.
|
|
*
|
|
* To decline the use of a default list simply pass nil to this method.
|
|
*
|
|
* Once the server has acknowledged the change,
|
|
* the delegate method xmppPrivacy:didSetDefaultListName: will be invoked.
|
|
* If the server is unable to process the change (e.g. invalid list name, in use by another resource),
|
|
* the delegate method xmppPrivacy:didNotSetDefaultListName:error: will be invoked.
|
|
*
|
|
* The methods defaultListName and defaultList will update after the server acknowledges the change.
|
|
**/
|
|
- (void)setDefaultListName:(NSString *)privacyListName;
|
|
|
|
/**
|
|
* Adds/Edits/Removes a privacy list with the given name.
|
|
* The given array should contain only privacy items (NSXMLElement's).
|
|
*
|
|
* To remove a privacy list, invoke this method will a nil or empty items parameter.
|
|
**/
|
|
- (void)setListWithName:(NSString *)privacyListName items:(NSArray *)items;
|
|
|
|
/**
|
|
* The following are convenience methods to create privacy item rules.
|
|
* A quick refresher from the XEP-0016 documentation is provided below.
|
|
*
|
|
* The 'type' attribute is OPTIONAL, and must be one of: jid|group|subscription
|
|
*
|
|
* If the 'type' is 'jid', then the 'value' must contain a valid JID.
|
|
* JIDs are to be matched in the following order:
|
|
*
|
|
* - <user@domain/resource> (only that resource matches)
|
|
* - <user@domain> (any resource matches)
|
|
* - <domain/resource> (only that resource matches)
|
|
* - <domain> (the domain itself matches, as does any user@domain or domain/resource)
|
|
*
|
|
* If the 'type' is 'group', then the 'value' should contain the name of a group in the user's roster.
|
|
*
|
|
* If the 'type' is 'subscription', then the 'value' must be one of: both|to|from|none
|
|
*
|
|
* The 'action' attribute is MANDATORY and must be one of: allow|deny
|
|
*
|
|
* The 'order' attribute is MANDATORY and must be a non-negative integer that is unique among all items in the list.
|
|
* List items are processed by the server according to the 'order' attribute in ascending order. (0 before 1, etc)
|
|
* Once the server matches a privacy item in the list, it obeys the item and ceases processing.
|
|
*
|
|
* The privacy item may contain one or more child elements that specify more granular blocking control:
|
|
*
|
|
* - <message/> (blocks incoming message stanzas)
|
|
* - <iq/> (blocks incoming IQ stanzas)
|
|
* - <presence-in/> (blocks incoming presence notifications)
|
|
* - <presence-out/> (blocks outgoing presence notifications)
|
|
**/
|
|
+ (NSXMLElement *)privacyItemWithAction:(NSString *)action order:(NSUInteger)order;
|
|
+ (NSXMLElement *)privacyItemWithType:(NSString *)type
|
|
value:(NSString *)value
|
|
action:(NSString *)action
|
|
order:(NSUInteger)order;
|
|
|
|
+ (void)blockIQs:(NSXMLElement *)privacyItem;
|
|
+ (void)blockMessages:(NSXMLElement *)privacyItem;
|
|
+ (void)blockPresenceIn:(NSXMLElement *)privacyItem;
|
|
+ (void)blockPresenceOut:(NSXMLElement *)privacyItem;
|
|
|
|
@end
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
#pragma mark -
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
@protocol XMPPPrivacyDelegate
|
|
@optional
|
|
|
|
/**
|
|
* The following delegate methods correspond almost exactly with the action methods of the class.
|
|
* There are a few possible ways in which an action could fail:
|
|
*
|
|
* 1. We receive an error response from the server.
|
|
* 2. We receive no response from the server, and the query times out.
|
|
* 3. We get disconnected before we receive the response.
|
|
*
|
|
* In case number 1, the error will be an XMPPIQ of type='error'.
|
|
*
|
|
* In case number 2 or 3, the error will be an NSError
|
|
* with domain=XMPPPrivacyErrorDomain and code from the XMPPPrivacyErrorCode enumeration.
|
|
**/
|
|
|
|
- (void)xmppPrivacy:(XMPPPrivacy *)sender didReceiveListNames:(NSArray *)listNames;
|
|
- (void)xmppPrivacy:(XMPPPrivacy *)sender didNotReceiveListNamesDueToError:(id)error;
|
|
|
|
- (void)xmppPrivacy:(XMPPPrivacy *)sender didReceiveListWithName:(NSString *)name items:(NSArray *)items;
|
|
- (void)xmppPrivacy:(XMPPPrivacy *)sender didNotReceiveListWithName:(NSString *)name error:(id)error;
|
|
|
|
- (void)xmppPrivacy:(XMPPPrivacy *)sender didReceivePushWithListName:(NSString *)name;
|
|
|
|
- (void)xmppPrivacy:(XMPPPrivacy *)sender didSetActiveListName:(NSString *)name;
|
|
- (void)xmppPrivacy:(XMPPPrivacy *)sender didNotSetActiveListName:(NSString *)name error:(id)error;
|
|
|
|
- (void)xmppPrivacy:(XMPPPrivacy *)sender didSetDefaultListName:(NSString *)name;
|
|
- (void)xmppPrivacy:(XMPPPrivacy *)sender didNotSetDefaultListName:(NSString *)name error:(id)error;
|
|
|
|
- (void)xmppPrivacy:(XMPPPrivacy *)sender didSetListWithName:(NSString *)name;
|
|
- (void)xmppPrivacy:(XMPPPrivacy *)sender didNotSetListWithName:(NSString *)name error:(id)error;
|
|
|
|
@end
|