ObjXMPP  Check-in [ae47288dc3]

PROJECT_NAME = "ObjXMPP"
OUTPUT_DIRECTORY = docs/
INPUT = src
FILE_PATTERNS = *.h *.m
HTML_OUTPUT = .
GENERATE_LATEX = NO
HIDE_UNDOC_CLASSES = YES
HIDE_UNDOC_MEMBERS = YES
PREDEFINED = OF_HAVE_PROPERTIES
PREDEFINED = OF_HAVE_PROPERTIES		\
	     OF_HAVE_BLOCKS		\
	     OF_HAVE_THREADS		\
	     OF_SENTINEL		\
	     OF_RETURNS_RETAINED	\
	     OF_RETURNS_NOT_RETAINED	\
	     OF_RETURNS_INNER_POINTER	\
	     OF_CONSUMED		\
	     OF_WEAK_UNAVAILABLE
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
IGNORE_PREFIX = XMPP

#import <ObjFW/ObjFW.h>

/**
 * \brief A base class for classes implementing authentication mechanisms
 */
@interface XMPPAuthenticator: OFObject
{
/// \cond internal
	OFString *_authzid;
	OFString *_authcid;
	OFString *_password;
/// \endcond
}

#ifdef OF_HAVE_PROPERTIES
/// \brief The authzid to get authorization for
@property (copy) OFString *authzid;
/// \brief The authcid to authenticate with
@property (copy) OFString *authcid;

/**
 * \brief This callback is called when the connection was closed.
 *
 * \param connection The connection that was closed
 */
- (void)connectionWasClosed: (XMPPConnection*)connection;

/**
 * \brief This callback is called when the connection threw an exception.
/*!
 * @brief This callback is called when the connection threw an exception.
 *
 * This is only called for connections on which \ref handleConnection: has been
 * called.
 * This is only called for connections on which
 * @ref XMPPConnection::handleConnection has been called.
 *
 * \param connection The connection which threw an exception
 * \param exception The exception the connection threw
 * @param connection The connection which threw an exception
 * @param exception The exception the connection threw
 */
-  (void)connection: (XMPPConnection*)connection
  didThrowException: (OFException*)exception;

/**
 * \brief This callback is called when the connection is about to upgrade to
 *	  TLS.

 * \brief A class which abstracts a connection to an XMPP service.
 */
@interface XMPPConnection: OFObject
#ifdef OF_HAVE_OPTONAL_PROTOCOLS
    <OFXMLParserDelegate, OFXMLElementBuilderDelegate>
#endif
{
/// \cond internal
	id _socket;
	OFXMLParser *_parser, *_oldParser;
	OFXMLElementBuilder *_elementBuilder, *_oldElementBuilder;
	OFString *_username, *_password, *_server, *_resource;
	OFString *_privateKeyFile, *_certificateFile;
	OFString *_domain, *_domainToASCII;
	XMPPJID *_JID;
	uint16_t _port;
	id <XMPPStorage> _dataStorage;
	OFString *_language;
	XMPPMulticastDelegate *_delegates;
	OFMutableDictionary *_callbacks;
	XMPPAuthenticator *_authModule;
	BOOL _streamOpen;
	BOOL _needsSession;
	BOOL _encryptionRequired, _encrypted;
	BOOL _supportsRosterVersioning;
	BOOL _supportsStreamManagement;
	unsigned int _lastID;
/// \endcond
}

#ifdef OF_HAVE_PROPERTIES
/// \brief The username to use for authentication
@property (copy) OFString *username;
/// \brief The password to use for authentication
@property (copy) OFString *password;

/**
 * \brief Sends an OFXMLElement, usually an XMPPStanza.
 *
 * \param element The element to send
 */
- (void)sendStanza: (OFXMLElement*)element;

/**
 * \brief Sends an XMPPIQ, registering a callback method.
/*!
 * @brief Sends an XMPPIQ, registering a callback method.
 *
 * @param IQ The IQ to send
 * \param target The object that contains the callback method
 * \param selector The selector of the callback method,
 * @param target The object that contains the callback method
 * @param selector The selector of the callback method,
 *		   must take exactly one parameter of type XMPPIQ*
 */
-   (void)sendIQ: (XMPPIQ*)iq
-   (void)sendIQ: (XMPPIQ*)IQ
  callbackTarget: (id)target
	selector: (SEL)selector;

#ifdef OF_HAVE_BLOCKS
/**
 * \brief Sends an XMPPIQ, registering a callback block.
/*!
 * @brief Sends an XMPPIQ, registering a callback block.
 *
 * @param IQ The IQ to send
 * \param block The callback block
 * @param block The callback block
 */
-  (void)sendIQ: (XMPPIQ*)iq
-  (void)sendIQ: (XMPPIQ*)IQ
  callbackBlock: (xmpp_callback_block_t)block;
#endif

/**
 * \brief Generates a new, unique stanza ID.
 *
 * \return A new, generated, unique stanza ID.

- (void)setDataStorage: (id <XMPPStorage>)dataStorage;
- (id <XMPPStorage>)dataStorage;
- (void)setLanguage: (OFString*)language;
- (OFString*)language;
- (BOOL)supportsRosterVersioning;
- (BOOL)supportsStreamManagement;

/// \cond internal
- (void)XMPP_startStream;
- (void)XMPP_handleStream: (OFXMLElement*)element;
- (void)XMPP_handleTLS: (OFXMLElement*)element;
- (void)XMPP_handleSASL: (OFXMLElement*)element;
- (void)XMPP_handleStanza: (OFXMLElement*)element;
- (void)XMPP_sendAuth: (OFString*)authName;
- (void)XMPP_sendResourceBind;
- (void)XMPP_sendStreamError: (OFString*)condition
			text: (OFString*)text;
- (void)XMPP_handleIQ: (XMPPIQ*)iq;
- (void)XMPP_handleMessage: (XMPPMessage*)message;
- (void)XMPP_handlePresence: (XMPPPresence*)presence;
- (void)XMPP_handleFeatures: (OFXMLElement*)element;
- (void)XMPP_handleResourceBindForConnection: (XMPPConnection*)connection
					  IQ: (XMPPIQ*)iq;
- (void)XMPP_sendSession;
- (void)XMPP_handleSessionForConnection: (XMPPConnection*)connection
				     IQ: (XMPPIQ*)iq;
- (OFString*)XMPP_IDNAToASCII: (OFString*)domain;
- (XMPPMulticastDelegate*)XMPP_delegates;
/// \endcond
@end

@interface OFObject (XMPPConnectionDelegate) <XMPPConnectionDelegate>
@end

	[_delegates broadcastSelector: @selector(connection:didSendElement:)
			   withObject: self
			   withObject: element];

	[_socket writeString: [element XMLString]];
}

-   (void)sendIQ: (XMPPIQ*)iq
-   (void)sendIQ: (XMPPIQ*)IQ
  callbackTarget: (id)target
	selector: (SEL)selector
{
	OFAutoreleasePool *pool;
	XMPPCallback *callback;

	if (![iq ID])
		[iq setID: [self generateStanzaID]];
	if (![IQ ID])
		[IQ setID: [self generateStanzaID]];

	pool = [[OFAutoreleasePool alloc] init];
	callback = [XMPPCallback callbackWithTarget: target
					   selector: selector];
	[_callbacks setObject: callback
		       forKey: [iq ID]];
		       forKey: [IQ ID]];
	[pool release];

	[self sendStanza: iq];
	[self sendStanza: IQ];
}

#ifdef OF_HAVE_BLOCKS
-  (void)sendIQ: (XMPPIQ*)iq
-  (void)sendIQ: (XMPPIQ*)IQ
  callbackBlock: (xmpp_callback_block_t)block
{
	OFAutoreleasePool *pool;
	XMPPCallback *callback;

	if (![iq ID])
		[iq setID: [self generateStanzaID]];
	if (![IQ ID])
		[IQ setID: [self generateStanzaID]];

	pool = [[OFAutoreleasePool alloc] init];
	callback = [XMPPCallback callbackWithBlock: block];
	[_callbacks setObject: callback
		       forKey: [iq ID]];
		       forKey: [IQ ID]];
	[pool release];

	[self sendStanza: iq];
	[self sendStanza: IQ];
}
#endif

- (OFString*)generateStanzaID
{
	return [OFString stringWithFormat: @"objxmpp_%u", _lastID++];
}

@class XMPPPresence;

/**
 * \brief A class describing a contact tracked by a XMPPContactManager
 */
@interface XMPPContact: OFObject
{
/// \cond internal
	XMPPRosterItem *_rosterItem;
	OFMutableDictionary *_presences;
	XMPPJID *_lockedOnJID;
/// \endcond
}

#ifdef OF_HAVE_PROPERTIES
/// \brief The XMPPRosterItem corresponding to this contact
@property (readonly) XMPPRosterItem *rosterItem;
/// \brief The XMPPPresences of this contact with the resources as keys
@property (readonly) OFDictionary *presences;
#endif

/**
 * \brief Sends a message to the contact honoring resource locking
 *
 * \param message The message to send
 * \param connection The connection to use for sending the message
 */
- (void)sendMessage: (XMPPMessage*)message
	 connection: (XMPPConnection*)connection;

/// \cond internal
- (void)XMPP_setRosterItem: (XMPPRosterItem*)rosterItem;
- (void)XMPP_setPresence: (XMPPPresence*)presence
		resource: (OFString*)resource;
- (void)XMPP_removePresenceForResource: (OFString*)resource;
- (void)XMPP_setLockedOnJID: (XMPPJID*)JID;
/// \endcond
@end

 * each contacts presences and the current XMPPRosterItem.
 */
@interface XMPPContactManager: OFObject
#ifdef OF_HAVE_OPTIONAL_PROTOCOLS
    <XMPPConnectionDelegate, XMPPRosterDelegate>
#endif
{
/// \cond internal
	OFMutableDictionary *_contacts;
	XMPPConnection *_connection;
	XMPPRoster *_roster;
	XMPPMulticastDelegate *_delegates;
/// \endcond
}

#ifdef OF_HAVE_PROPERTIES
/// \brief The tracked contacts, with their bare JID as key
@property (readonly) OFDictionary *contacts;
#endif

/**
 * \brief Initializes an already allocated XMPPContactManager.
/*!
 * @brief Initializes an already allocated XMPPContactManager.
 *
 * \param connection The connection to be used to track contacts
 * \return An initialized XMPPContactManager
 * @param connection The connection to be used to track contacts
 * @param roster The roster used by the contact manager
 * @return An initialized XMPPContactManager
 */
- initWithConnection: (XMPPConnection*)connection
	      roster: (XMPPRoster*)roster;

/**
 * \brief Adds the specified delegate.
 *

@class XMPPAuthenticator;

/**
 * \brief A base class for XMPP related exceptions
 */
@interface XMPPException: OFException
{
/// \cond internal
	XMPPConnection *_connection;
/// \endcond
}

#ifdef OF_HAVE_PROPERTIES
/// \brief The connection the exception relates to
@property (readonly, assign) XMPPConnection *connection;
#endif

@end

/**
 * \brief An exception indicating a stream error was received
 */
@interface XMPPStreamErrorException: XMPPException
{
/// \cond internal
	OFString *_condition;
	OFString *_reason;
/// \endcond
}

#ifdef OF_HAVE_PROPERTIES
/// \brief The defined error condition specified by the stream error
@property (readonly, assign) OFString *condition;
/// \brief The descriptive free-form text specified by the stream error
@property (readonly, assign) OFString *reason;

/**
 * \brief An exception indicating a stringprep profile
 *	  did not apply to a string
 */
@interface XMPPStringPrepFailedException: XMPPException
{
/// \cond internal
	OFString *_profile;
	OFString *_string;
/// \endcond
}

#ifdef OF_HAVE_PROPERTIES
/// \brief The name of the stringprep profile that did not apply
@property (readonly, assign) OFString *profile;
/// \brief The string that failed the stringprep profile
@property (readonly, assign) OFString *string;

@end

/**
 * \brief An exception indicating IDNA translation of a string failed
 */
@interface XMPPIDNATranslationFailedException: XMPPException
{
/// \cond internal
	OFString *_operation;
	OFString *_string;
/// \endcond
}

#ifdef OF_HAVE_PROPERTIES
/// \brief The IDNA translation operation which failed
@property (readonly, assign) OFString *operation;
/// \brief The string that could not be translated
@property (readonly, assign) OFString *string;

@end

/**
 * \brief An exception indicating authentication failed
 */
@interface XMPPAuthFailedException: XMPPException
{
/// \cond internal
	OFString *_reason;
/// \endcond
}

#ifdef OF_HAVE_PROPERTIES
/// \brief The reason the authentication failed
@property (readonly, assign) OFString *reason;
#endif

#import <ObjFW/ObjFW.h>

/**
 * \brief A class for easy handling of JIDs.
 */
@interface XMPPJID: OFObject <OFCopying>
{
/// \cond internal
	OFString *_node;
	OFString *_domain;
	OFString *_resource;
/// \endcond
}

#ifdef OF_HAVE_PROPERTIES
/// \brief The JID's localpart
@property (copy) OFString *node;
/// \brief The JID's domainpart
@property (copy) OFString *domain;

@class OFDataArray;

/**
 * \brief A class to provide multiple delegates in a single class
 */
@interface XMPPMulticastDelegate: OFObject
{
/// \cond internal
	OFDataArray *_delegates;
/// \endcond
}

/**
 * \brief Adds a delegate which should receive the broadcasts.
 *
 * \param delegate The delegate to add
 */

#import "XMPPStanza.h"

/**
 * \brief A class describing a presence stanza.
 */
@interface XMPPPresence: XMPPStanza <OFComparing>
{
/// \cond internal
	OFString *_status;
	OFString *_show;
	OFNumber *_priority;
/// \endcond
}
#ifdef OF_HAVE_PROPERTIES
@property (copy) OFString *status;
@property (copy) OFString *show;
@property (copy) OFNumber *priority;
#endif

 * \brief A class implementing roster related functionality.
 */
@interface XMPPRoster: OFObject
#ifdef OF_HAVE_OPTIONAL_PROTOCOLS
    <XMPPConnectionDelegate>
#endif
{
/// \cond internal
	XMPPConnection *_connection;
	OFMutableDictionary *_rosterItems;
	XMPPMulticastDelegate *_delegates;
	id <XMPPStorage> _dataStorage;
	BOOL _rosterRequested;
/// \endcond
}

#ifdef OF_HAVE_PROPERTIES
/**
 * \brief The connection to which the roster belongs
 */
@property (readonly, assign) XMPPConnection *connection;

- (void)removeDelegate: (id <XMPPRosterDelegate>)delegate;

- (XMPPConnection*)connection;

- (void)setDataStorage: (id <XMPPStorage>)dataStorage;
- (id <XMPPStorage>)dataStorage;

/// \cond internal
- (void)XMPP_updateRosterItem: (XMPPRosterItem*)rosterItem;
- (void)XMPP_handleInitialRosterForConnection: (XMPPConnection*)connection
					   IQ: (XMPPIQ*)iq;
- (XMPPRosterItem*)XMPP_rosterItemWithXMLElement: (OFXMLElement*)element;
/// \endcond
@end

@interface OFObject (XMPPRosterDelegate) <XMPPRosterDelegate>
@end

@class XMPPJID;

/**
 * \brief A class for representing an item in the roster.
 */
@interface XMPPRosterItem: OFObject
{
/// \cond internal
	XMPPJID *_JID;
	OFString *_name;
	OFString *_subscription;
	OFArray *_groups;
/// \endcond
}

#ifdef OF_HAVE_PROPERTIES
/// \brief The JID of the roster item
@property (copy) XMPPJID *JID;
/// \brief The name of the roster item to show to the user
@property (copy) OFString *name;

#import "XMPPConnection.h"

/**
 * \brief A class to authenticate using SCRAM
 */
@interface XMPPSCRAMAuth: XMPPAuthenticator
{
/// \cond internal
	Class _hashType;
	OFString *_cNonce;
	OFString *_GS2Header;
	OFString *_clientFirstMessageBare;
	OFDataArray *_serverSignature;
	XMPPConnection *_connection;
	BOOL _plusAvailable;
	BOOL _authenticated;
/// \endcond
}

/**
 * \brief Creates a new autoreleased XMPPSCRAMAuth with an authcid and password.
 *
 * \param authcid The authcid to authenticate with
 * \param password The password to authenticate with

#ifdef OF_HAVE_PROPERTIES
@property (readonly, copy) OFString *domain;
#endif

+ lookupWithDomain: (OFString*)domain;
- initWithDomain: (OFString*)domain;
/// \cond internal

- (void)XMPP_lookup;
- (void)XMPP_addEntry: (XMPPSRVEntry*)item;
/// \endcond
@end

@interface XMPPSRVEnumerator: OFEnumerator
{
	OFList *list;
	of_list_object_t *listIter;
	OFList *subListCopy;
	BOOL done;
}

- initWithList: (OFList*)list;
@end

@class XMPPJID;

/**
 * \brief A class describing an XMPP Stanza.
 */
@interface XMPPStanza: OFXMLElement
{
/// \cond internal
	XMPPJID *_from;
	XMPPJID *_to;
	OFString *_type;
	OFString *_ID;
	OFString *_language;
/// \endcond
}

#ifdef OF_HAVE_PROPERTIES
/// \brief The value of the stanza's from attribute
@property (copy) XMPPJID *from;
/// \brief The value of the stanza's to attribute
@property (copy) XMPPJID *to;

#import "XMPPConnection.h"

@interface XMPPStreamManagement: OFObject
#ifdef OF_HAVE_OPTIONAL_PROTOCOLS
    <XMPPConnectionDelegate>
#endif
{
/// \cond internal
	XMPPConnection *_connection;
	uint32_t receivedCount;
/// \endcond
}

- initWithConnection: (XMPPConnection*)connection;
@end