Updated doxygen.

author: Remko Tronçon <git@el-tramo.be> 2010-10-25 19:21:10 (GMT)
committer: Remko Tronçon <git@el-tramo.be> 2010-10-25 19:35:08 (GMT)
commit: 09ea1261f5da1fb63307e67d994bee617c09a481 (patch)
tree: 5a489d8cde5b74c2c0a6290d35b6c4523129f174 /Swiften
parent: 96c5a881b2768057f8189030b543fefa2835e782 (diff)
download: swift-09ea1261f5da1fb63307e67d994bee617c09a481.zip
swift-09ea1261f5da1fb63307e67d994bee617c09a481.tar.bz2
2 files changed, 106 insertions, 23 deletions
diff --git a/Swiften/Client/Client.h b/Swiften/Client/Client.h
index eb3fc09..47a276a 100644
--- a/Swiften/Client/Client.h
+++ b/Swiften/Client/Client.h
@@ -29,12 +29,16 @@ namespace Swift {
 	 *
 	 * Besides connecting to an XMPP server, this class also provides interfaces for
 	 * performing most tasks on the XMPP network.
-	 *
-	 * \param storages The interfaces for storing cache information etc. If this is NULL,
-	 *    all data will be stored in memory (and be lost on shutdown)
 	 */
 	class Client : public CoreClient {
 		public:
+			/**
+			 * Constructs a client for the given JID with the given password.
+			 *
+			 * \param storages The interfaces for storing cache information etc. If 
+			 *	this is NULL,
+			 *	all data will be stored in memory (and be lost on shutdown)
+			 */
 			Client(const JID& jid, const String& password, Storages* storages = NULL);
 			~Client();
 
@@ -46,16 +50,18 @@ namespace Swift {
 			 */
 			void setSoftwareVersion(const String& name, const String& version);
 
-			/**
+			/** 
 			 * Returns a representation of the roster.
 			 *
-			 * The roster is initially empty. To populate it, call requestRoster(), which
-			 * will request the roster from the server. When the roster has been requested,
-			 * it will also be kept up to date when it is updated on the server side.
+			 * The roster is initially empty. To populate it, call requestRoster(),
+			 * which will request the roster from the server. When the roster has
+			 * been requested, it will also be kept up to date when it is updated on
+			 * the server side.
 			 *
-			 * This pointer remains the same across the lifetime of Client. All changes
-			 * to the roster (e.g. after the initial roster request, or after subsequent
-			 * roster updates) are notified through the XMPPRoster's signals.
+			 * This pointer remains the same across the lifetime of Client. All
+			 * changes to the roster (e.g. after the initial roster request, or after
+			 * subsequent roster updates) are notified through the XMPPRoster's
+			 * signals.
 			 *
 			 * \see requestRoster()
 			 */
diff --git a/Swiften/Client/CoreClient.h b/Swiften/Client/CoreClient.h
index 24f44fc..f440dfe 100644
--- a/Swiften/Client/CoreClient.h
+++ b/Swiften/Client/CoreClient.h
@@ -32,38 +32,63 @@ namespace Swift {
 	class ClientSession;
 	class BasicSessionStream;
 
-	/**
+	/** 
 	 * The central class for communicating with an XMPP server.
 	 *
-	 * This class is responsible for setting up the connection with the XMPP server, authenticating, and
-	 * initializing the session.
+	 * This class is responsible for setting up the connection with the XMPP
+	 * server, authenticating, and initializing the session.
 	 *
-	 * This class can be used directly in your application, although the Client subclass provides more
-	 * functionality and interfaces, and is better suited for most needs.
+	 * This class can be used directly in your application, although the Client
+	 * subclass provides more functionality and interfaces, and is better suited
+	 * for most needs.
 	 */
-	class CoreClient  {
-		public:
-			CoreClient(const JID& jid, const String& password);
+	class CoreClient  { 
+		public: 
+			/**
+			 * Constructs a client for the given JID with the given password.
+			 */
+			CoreClient(const JID& jid, const String& password); 
 			~CoreClient();
 
 			void setCertificate(const String& certificate);
 
+			/**
+			 * Connects the client to the server.
+			 *
+			 * After the connection is established, the client will set 
+			 * initialize the stream and authenticate.
+			 */
 			void connect();
+
+			/**
+			 * Disconnects the client from the server.
+			 */
+			void disconnect();
+
 			void connect(const JID& jid);
 			void connect(const String& host);
-			void disconnect();
 			
+			/**
+			 * Sends a message.
+			 */
 			void sendMessage(Message::ref);
+
+			/**
+			 * Sends a presence stanza.
+			 */
 			void sendPresence(Presence::ref);
 
+			/**
+			 * Returns the IQ router for this client.
+			 */
 			IQRouter* getIQRouter() const {
 				return iqRouter_;
 			}
 
-			StanzaChannel* getStanzaChannel() const {
-				return stanzaChannel_;
-			}
-
+			/**
+			 * Checks whether the client is connected to the server,
+			 * and stanzas can be sent.
+			 */
 			bool isAvailable() const {
 				return stanzaChannel_->isAvailable();
 			}
@@ -81,14 +106,66 @@ namespace Swift {
 				}
 			}
 
+			/**
+			 * Checks whether stream management is enabled.
+			 *
+			 * If stream management is enabled, onStanzaAcked will be
+			 * emitted when a stanza is received by the server.
+			 *
+			 * \see onStanzaAcked
+			 */
+			bool getStreamManagementEnabled() const {
+				return stanzaChannel_->getStreamManagementEnabled();
+			}
+
+			StanzaChannel* getStanzaChannel() const {
+				return stanzaChannel_;
+			}
+
 		public:
+			/**
+			 * Emitted when a non-recoverable error occurs.
+			 */
 			boost::signal<void (const ClientError&)> onError;
+
+			/**
+			 * Emitted when the client is connected and authenticated,
+			 * and stanzas can be sent.
+			 */
 			boost::signal<void ()> onConnected;
+
+			/**
+			 * Emitted when the client receives data.
+			 *
+			 * This signal is emitted before the XML data is parsed,
+			 * so this data is unformatted.
+			 */
 			boost::signal<void (const String&)> onDataRead;
+
+			/**
+			 * Emitted when the client sends data.
+			 *
+			 * This signal is emitted after the XML was serialized, and 
+			 * is unformatted.
+			 */
 			boost::signal<void (const String&)> onDataWritten;
 
+			/**
+			 * Emitted when a message is received.
+			 */
 			boost::signal<void (Message::ref)> onMessageReceived;
+
+			/**
+			 * Emitted when a presence stanza is received.
+			 */
 			boost::signal<void (Presence::ref) > onPresenceReceived;
+
+			/**
+			 * Emitted when the server acknowledges receipt of a
+			 * stanza (if acknowledgements are available).
+			 *
+			 * \see getStreamManagementEnabled()
+			 */
 			boost::signal<void (Stanza::ref)> onStanzaAcked;
 
 		private:
author	Remko Tronçon <git@el-tramo.be>	2010-10-25 19:21:10 (GMT)
committer	Remko Tronçon <git@el-tramo.be>	2010-10-25 19:35:08 (GMT)
commit	09ea1261f5da1fb63307e67d994bee617c09a481 (patch)
tree	5a489d8cde5b74c2c0a6290d35b6c4523129f174 /Swiften
parent	96c5a881b2768057f8189030b543fefa2835e782 (diff)
download	swift-09ea1261f5da1fb63307e67d994bee617c09a481.zip swift-09ea1261f5da1fb63307e67d994bee617c09a481.tar.bz2