From bf5b66e7a8252fd1d9db26f5822c393e24ad091a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Remko=20Tron=C3=A7on?= <git@el-tramo.be>
Date: Sat, 4 Dec 2010 16:40:40 +0100
Subject: Document custom requests & responders, and components.


diff --git a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoComponent.cpp b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoComponent.cpp
index a4155be..4843b80 100644
--- a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoComponent.cpp
+++ b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoComponent.cpp
@@ -15,7 +15,8 @@ using namespace boost;
 class EchoComponent {
 	public:
 		EchoComponent(EventLoop* eventLoop, NetworkFactories* networkFactories) {
-			component = new Component(eventLoop, networkFactories, JID("echo.wonderland.lit"), "EchoSecret");
+			component = new Component(eventLoop, networkFactories,
+					JID("echo.wonderland.lit"), "EchoSecret");
 			component->onConnected.connect(bind(&EchoComponent::handleConnected, this));
 			component->onMessageReceived.connect(
 					bind(&EchoComponent::handleMessageReceived, this, _1));
diff --git a/Documentation/SwiftenDevelopersGuide/SConscript b/Documentation/SwiftenDevelopersGuide/SConscript
index 54a3ad2..e000ac2 100644
--- a/Documentation/SwiftenDevelopersGuide/SConscript
+++ b/Documentation/SwiftenDevelopersGuide/SConscript
@@ -87,7 +87,7 @@ if "doc" in ARGUMENTS :
 sources = []
 for i in range(1, 7) :
 	sources.append("Examples/EchoBot/EchoBot" + str(i) + ".cpp")
-sources += ["Examples/EchoBot/" + i for i in ["EchoPayloadParserFactory.h", "EchoPayloadSerializer.h", "EchoPayload.h"]]
+sources += ["Examples/EchoBot/" + i for i in ["EchoPayloadParserFactory.h", "EchoPayloadSerializer.h", "EchoPayload.h", "EchoComponent.cpp"]]
 for source in sources :
 	env.Command(source + ".xml", source, Action(generateDocBookCode, cmdstr = "$GENCOMSTR"))
 
diff --git a/Documentation/SwiftenDevelopersGuide/Swiften Developers Guide.xml b/Documentation/SwiftenDevelopersGuide/Swiften Developers Guide.xml
index ea4ccd4..e0daff3 100644
--- a/Documentation/SwiftenDevelopersGuide/Swiften Developers Guide.xml	
+++ b/Documentation/SwiftenDevelopersGuide/Swiften Developers Guide.xml	
@@ -202,7 +202,7 @@
       </para>
     </sect1>
 
-    <sect1>
+    <sect1 id="Section-Requests">
       <title>Presence Management: Requests</title>
       <para>
         The current version of our EchoBot does what it is supposed to do:
@@ -252,7 +252,7 @@
       </para>
     </sect1>
 
-    <sect1>
+    <sect1 id="Section-Responders">
       <title>Publishing version information: Responders</title>
       <para>
         Most XMPP clients have support for querying software version information
@@ -377,7 +377,16 @@
 
     <sect1 id="Section-CustomQueries">
       <title>Extending Swiften with new queries and responders</title>
-      <remark>TODO</remark>
+      <para>
+        <xref linkend="Section-Requests"/> and <xref linkend="Section-Responders"/> 
+        explained that Swiften provides Requests and Responder classes for querying
+        or responding to queries of specific payloads. If you extend Swiften with your
+        own payloads, you can use these to create your own <literal>Request</literal>
+        or <literal>Responder</literal> subclasses. Swiften also provides convenience
+        classes such as <literal>GenericRequest</literal>, <literal>GetResponder</literal>
+        and <literal>SetResponder</literal> for creating your requests and responders
+        for your custom payloads.
+      </para>
     </sect1>
 
     <sect1>
@@ -395,6 +404,24 @@
       	management, VCards, Avatars, Service Discovery, Multi-User Chats, ...
       </para>
     </sect1>
+
+    <sect1>
+      <title>Writing server components</title>
+      <para>
+        Swiften also provides classes for creating server components. The 
+        <literal>Component</literal> class has a similar interface
+        as <literal>Client</literal>, but uses the component protocol to connect with
+        the XMPP server. Except for a few classes, the same techniques and classes for 
+        writing clients can be applied to write components. 
+        <xref linkend="Example-EchoComponent"/> illustrates how we would build a
+        component version of our Echo bot.
+      </para>
+
+      <example id="Example-EchoComponent">
+        <title>EchoBot as a server component</title>
+        <include xmlns="http://www.w3.org/2001/XInclude" href="Examples/EchoBot/EchoComponent.cpp.xml" xpointer="xpointer(//programlisting|//calloutlist)"/>
+      </example>
+    </sect1>
   </chapter>
 
   <bibliography>
diff --git a/Swiften/Queries/Request.h b/Swiften/Queries/Request.h
index 625c147..5ed518d 100644
--- a/Swiften/Queries/Request.h
+++ b/Swiften/Queries/Request.h
@@ -19,30 +19,40 @@
 #include "Swiften/JID/JID.h"
 
 namespace Swift {
+	/**
+	 * An IQ get/set request query.
+	 */
 	class Request : public IQHandler, public boost::enable_shared_from_this<Request> {
 		public:
 			void send();
 
 		protected:
+			/**
+			 * Constructs a request of a certain type to a specific receiver, and attaches the given
+			 * payload.
+			 */
 			Request(
 					IQ::Type type, 
 					const JID& receiver, 
 					boost::shared_ptr<Payload> payload, 
 					IQRouter* router);
+			/**
+			 * Constructs a request of a certain type to a specific receiver.
+			 */
 			Request(
 					IQ::Type type, 
 					const JID& receiver, 
 					IQRouter* router);
 
-			virtual void setPayload(boost::shared_ptr<Payload> p) {
-				payload_ = p;
+			virtual void setPayload(Payload::ref payload) {
+				payload_ = payload;
 			}
 
-			boost::shared_ptr<Payload> getPayload() const {
+			Payload::ref getPayload() const {
 				return payload_;
 			}
 
-			virtual void handleResponse(boost::shared_ptr<Payload>, ErrorPayload::ref) = 0;
+			virtual void handleResponse(Payload::ref, ErrorPayload::ref) = 0;
 
 		private:
 			bool handleIQ(boost::shared_ptr<IQ>);
-- 
cgit v0.10.2-6-g49f6