summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/SwiftenDevelopersGuide')
-rw-r--r--Documentation/SwiftenDevelopersGuide/Examples/EchoBot/.gitignore1
-rw-r--r--Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot1.cpp2
-rw-r--r--Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot2.cpp2
-rw-r--r--Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot3.cpp2
-rw-r--r--Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot4.cpp2
-rw-r--r--Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot5.cpp2
-rw-r--r--Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot6.cpp120
-rw-r--r--Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoComponent.cpp2
-rw-r--r--Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoPayload.h27
-rw-r--r--Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoPayloadParserFactory.h43
-rw-r--r--Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoPayloadSerializer.h21
-rw-r--r--Documentation/SwiftenDevelopersGuide/Examples/EchoBot/SConscript2
-rw-r--r--Documentation/SwiftenDevelopersGuide/SConscript7
-rw-r--r--Documentation/SwiftenDevelopersGuide/Swiften Developers Guide.xml73
14 files changed, 296 insertions, 10 deletions
diff --git a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/.gitignore b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/.gitignore
index 81f2be3..91c939b 100644
--- a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/.gitignore
+++ b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/.gitignore
@@ -1,3 +1,4 @@
EchoBot?
*.cpp.xml
+*.h.xml
EchoComponent
diff --git a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot1.cpp b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot1.cpp
index e545801..f5268ef 100644
--- a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot1.cpp
+++ b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot1.cpp
@@ -4,7 +4,7 @@
* See Documentation/Licenses/GPLv3.txt for more information.
*/
-#include "Swiften/Swiften.h"
+#include <Swiften/Swiften.h>
using namespace Swift;
diff --git a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot2.cpp b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot2.cpp
index 810307c..99efdf9 100644
--- a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot2.cpp
+++ b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot2.cpp
@@ -7,7 +7,7 @@
#include <iostream>
#include <boost/bind.hpp>
-#include "Swiften/Swiften.h"
+#include <Swiften/Swiften.h>
using namespace Swift;
using namespace boost;
diff --git a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot3.cpp b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot3.cpp
index bca00af..3404c2a 100644
--- a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot3.cpp
+++ b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot3.cpp
@@ -7,7 +7,7 @@
#include <iostream>
#include <boost/bind.hpp>
-#include "Swiften/Swiften.h"
+#include <Swiften/Swiften.h>
using namespace Swift;
using namespace boost;
diff --git a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot4.cpp b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot4.cpp
index 9b2277b..0309768 100644
--- a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot4.cpp
+++ b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot4.cpp
@@ -8,7 +8,7 @@
#include <iostream>
#include <boost/bind.hpp>
-#include "Swiften/Swiften.h"
+#include <Swiften/Swiften.h>
using namespace Swift;
using namespace boost;
diff --git a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot5.cpp b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot5.cpp
index 47cbe1f..4c09e1b 100644
--- a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot5.cpp
+++ b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot5.cpp
@@ -8,7 +8,7 @@
#include <iostream>
#include <boost/bind.hpp>
-#include "Swiften/Swiften.h"
+#include <Swiften/Swiften.h>
using namespace Swift;
using namespace boost;
diff --git a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot6.cpp b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot6.cpp
new file mode 100644
index 0000000..4c96f6b
--- /dev/null
+++ b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoBot6.cpp
@@ -0,0 +1,120 @@
+/*
+ * Copyright (c) 2010 Remko Tronçon
+ * Licensed under the GNU General Public License v3.
+ * See Documentation/Licenses/GPLv3.txt for more information.
+ */
+
+//...
+#include <iostream>
+#include <boost/bind.hpp>
+
+#include <Swiften/Swiften.h>
+
+using namespace Swift;
+using namespace boost;
+//...
+#include "EchoPayload.h"
+#include "EchoPayloadParserFactory.h"
+#include "EchoPayloadSerializer.h"
+
+class EchoBot {
+ public:
+ EchoBot(EventLoop* eventLoop, NetworkFactories* networkFactories) {
+ //...
+ client = new Client(eventLoop, networkFactories, JID("echobot@wonderland.lit"), "mypass");
+ client->onConnected.connect(bind(&EchoBot::handleConnected, this));
+ client->onMessageReceived.connect(
+ bind(&EchoBot::handleMessageReceived, this, _1));
+ client->onPresenceReceived.connect(
+ bind(&EchoBot::handlePresenceReceived, this, _1));
+ tracer = new ClientXMLTracer(client);
+
+ softwareVersionResponder = new SoftwareVersionResponder(client->getIQRouter());
+ softwareVersionResponder->setVersion("EchoBot", "1.0");
+ softwareVersionResponder->start();
+ //...
+ client->addPayloadParserFactory(&echoPayloadParserFactory);
+ client->addPayloadSerializer(&echoPayloadSerializer);
+ //...
+ client->connect();
+ //...
+ }
+
+ ~EchoBot() {
+ client->removePayloadSerializer(&echoPayloadSerializer);
+ client->removePayloadParserFactory(&echoPayloadParserFactory);
+ //...
+ softwareVersionResponder->stop();
+ delete softwareVersionResponder;
+ delete tracer;
+ delete client;
+ //...
+ }
+ //...
+
+ private:
+ void handlePresenceReceived(Presence::ref presence) {
+ // Automatically approve subscription requests
+ if (presence->getType() == Presence::Subscribe) {
+ Presence::ref response = Presence::create();
+ response->setTo(presence->getFrom());
+ response->setType(Presence::Subscribed);
+ client->sendPresence(response);
+ }
+ }
+
+ void handleConnected() {
+ // Request the roster
+ GetRosterRequest::ref rosterRequest =
+ GetRosterRequest::create(client->getIQRouter());
+ rosterRequest->onResponse.connect(
+ bind(&EchoBot::handleRosterReceived, this, _2));
+ rosterRequest->send();
+ }
+
+ void handleRosterReceived(ErrorPayload::ref error) {
+ if (error) {
+ std::cerr << "Error receiving roster. Continuing anyway.";
+ }
+ // Send initial available presence
+ client->sendPresence(Presence::create("Send me a message"));
+ }
+
+ //...
+ void handleMessageReceived(Message::ref message) {
+ //...
+ // Echo back the incoming message
+ message->setTo(message->getFrom());
+ message->setFrom(JID());
+ //...
+ if (!message->getPayload<EchoPayload>()) {
+ boost::shared_ptr<EchoPayload> echoPayload(new EchoPayload());
+ echoPayload->setMessage("This is an echoed message");
+ message->addPayload(echoPayload);
+ client->sendMessage(message);
+ }
+ }
+ //...
+
+ //...
+ private:
+ //...
+ Client* client;
+ ClientXMLTracer* tracer;
+ SoftwareVersionResponder* softwareVersionResponder;
+ //...
+ EchoPayloadParserFactory echoPayloadParserFactory;
+ EchoPayloadSerializer echoPayloadSerializer;
+};
+//...
+
+int main(int, char**) {
+ SimpleEventLoop eventLoop;
+ BoostNetworkFactories networkFactories(&eventLoop);
+
+ EchoBot bot(&eventLoop, &networkFactories);
+
+ eventLoop.run();
+ return 0;
+}
+//...
diff --git a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoComponent.cpp b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoComponent.cpp
index 0a856f9..a4155be 100644
--- a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoComponent.cpp
+++ b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoComponent.cpp
@@ -7,7 +7,7 @@
#include <iostream>
#include <boost/bind.hpp>
-#include "Swiften/Swiften.h"
+#include <Swiften/Swiften.h>
using namespace Swift;
using namespace boost;
diff --git a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoPayload.h b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoPayload.h
new file mode 100644
index 0000000..1354ebf
--- /dev/null
+++ b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoPayload.h
@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2010 Remko Tronçon
+ * Licensed under the GNU General Public License v3.
+ * See Documentation/Licenses/GPLv3.txt for more information.
+ */
+//...
+#pragma once
+
+#include <Swiften/Swiften.h>
+
+using namespace Swift;
+//...
+class EchoPayload : public Payload {
+ public:
+ EchoPayload() {}
+
+ const String& getMessage() const {
+ return message;
+ }
+
+ void setMessage(const String& message) {
+ this->message = message;
+ }
+
+ private:
+ String message;
+};
diff --git a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoPayloadParserFactory.h b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoPayloadParserFactory.h
new file mode 100644
index 0000000..3af616c
--- /dev/null
+++ b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoPayloadParserFactory.h
@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2010 Remko Tronçon
+ * Licensed under the GNU General Public License v3.
+ * See Documentation/Licenses/GPLv3.txt for more information.
+ */
+
+#pragma once
+
+#include <Swiften/Swiften.h>
+#include "EchoPayload.h"
+
+using namespace Swift;
+
+class EchoPayloadParser : public GenericPayloadParser<EchoPayload> {
+ public:
+ EchoPayloadParser() : currentDepth(0) {}
+
+ void handleStartElement(
+ const String& /* element */, const String& /* ns */, const AttributeMap&) {
+ currentDepth++;
+ }
+
+ void handleEndElement(const String& /* element */, const String& /* ns */) {
+ currentDepth--;
+ if (currentDepth == 0) {
+ getPayloadInternal()->setMessage(currentText);
+ }
+ }
+
+ void handleCharacterData(const String& data) {
+ currentText += data;
+ }
+
+ private:
+ int currentDepth;
+ String currentText;
+};
+
+class EchoPayloadParserFactory : public GenericPayloadParserFactory<EchoPayloadParser> {
+ public:
+ EchoPayloadParserFactory() :
+ GenericPayloadParserFactory<EchoPayloadParser>("echo", "http://swift.im/echo") {}
+};
diff --git a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoPayloadSerializer.h b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoPayloadSerializer.h
new file mode 100644
index 0000000..1b18be4
--- /dev/null
+++ b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/EchoPayloadSerializer.h
@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2010 Remko Tronçon
+ * Licensed under the GNU General Public License v3.
+ * See Documentation/Licenses/GPLv3.txt for more information.
+ */
+
+#pragma once
+
+#include <Swiften/Swiften.h>
+#include "EchoPayload.h"
+
+using namespace Swift;
+
+class EchoPayloadSerializer : public GenericPayloadSerializer<EchoPayload> {
+ public:
+ String serializePayload(boost::shared_ptr<EchoPayload> payload) const {
+ XMLElement element("echo", "http://swift.im/protocol/echo");
+ element.addNode(XMLTextNode::ref(new XMLTextNode(payload->getMessage())));
+ return element.serialize();
+ }
+};
diff --git a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/SConscript b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/SConscript
index 2ccfb7e..1e410cf 100644
--- a/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/SConscript
+++ b/Documentation/SwiftenDevelopersGuide/Examples/EchoBot/SConscript
@@ -4,6 +4,6 @@ example_env = env.Clone()
example_env.MergeFlags(example_env["SWIFTEN_FLAGS"])
example_env.MergeFlags(example_env["SWIFTEN_DEP_FLAGS"])
-for i in range(1,6) :
+for i in range(1,7) :
example_env.Program("EchoBot" + str(i), ["EchoBot" + str(i) + ".cpp"])
example_env.Program("EchoComponent", "EchoComponent.cpp")
diff --git a/Documentation/SwiftenDevelopersGuide/SConscript b/Documentation/SwiftenDevelopersGuide/SConscript
index dc00ab4..54a3ad2 100644
--- a/Documentation/SwiftenDevelopersGuide/SConscript
+++ b/Documentation/SwiftenDevelopersGuide/SConscript
@@ -84,8 +84,11 @@ def generateDocBookCode(env, target, source) :
if "doc" in ARGUMENTS :
env.DocBook("Swiften Developers Guide.xml")
-for i in range(1, 6) :
- source = "Examples/EchoBot/EchoBot" + str(i) + ".cpp"
+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"]]
+for source in sources :
env.Command(source + ".xml", source, Action(generateDocBookCode, cmdstr = "$GENCOMSTR"))
SConscript(dirs = ["Examples"])
diff --git a/Documentation/SwiftenDevelopersGuide/Swiften Developers Guide.xml b/Documentation/SwiftenDevelopersGuide/Swiften Developers Guide.xml
index 52af24e..ea4ccd4 100644
--- a/Documentation/SwiftenDevelopersGuide/Swiften Developers Guide.xml
+++ b/Documentation/SwiftenDevelopersGuide/Swiften Developers Guide.xml
@@ -301,7 +301,78 @@
<literal>RosterPayload</literal>.
</para>
- <remark>TODO</remark>
+ <para>
+ If you want to extend Swiften with your own XMPP extension, you will first
+ need to create a payload for this extension. For example, suppose we want to
+ reate an extension for use in our Echo bot that contains a special textual
+ message, and add this to all our outgoing messages,
+ we create the <literal>EchoPayload</literal> illustrated in
+ <xref linkend="Example-EchoPayload"/>. We can then append or retrieve this
+ payload from the stanzas using <literal>Stanza::getPayload()</literal> and
+ <literal>Stanza::addPayload()</literal>. For example, the version of our
+ bot in <xref linkend="Example-EchoBot6"/> checks whether an incoming
+ message contains the <literal>EchoPayload</literal>, and if not,
+ echoes back the message, and adds an extension to the message with a
+ descriptive text.
+ </para>
+
+ <example id="Example-EchoPayload">
+ <title>Extending Swiften with a new payload: <literal>EchoPayload</literal></title>
+ <include xmlns="http://www.w3.org/2001/XInclude" href="Examples/EchoBot/EchoPayload.h.xml" xpointer="xpointer(//programlisting|//calloutlist)"/>
+ </example>
+
+ <example id="Example-EchoBot6">
+ <title>Adding a custom extension: Using a custom element, and registering a parser (factory) and serializer for the element.</title>
+ <include xmlns="http://www.w3.org/2001/XInclude" href="Examples/EchoBot/EchoBot6.cpp.xml" xpointer="xpointer(//programlisting|//calloutlist)"/>
+ </example>
+
+ <para>
+ However, having the element is not enough; Swiften also needs to know how to
+ extract this payload from the incoming stanzas, and know how to send it on
+ outgoing stanzas. In order to do this, Swiften uses XML parsers and serializers
+ for the payload. We therefore need to create a parser and serializer for our
+ new payload, and register it with <literal>Client</literal>. Serializers are
+ implemented as subclasses from <literal>PayloadSerializer</literal>, and provide
+ the basic methods <literal>canSerialize()</literal> and
+ <literal>serialize()</literal>. The serializer
+ is registered using <literal>Client::addPayloadSerializer()</literal>
+ (and unregistered using <literal>Client::removePayloadSerializer()</literal>).
+ Parsers consist of 2 parts: a subclass of <literal>PayloadParser</literal>, which
+ parses incoming XML in an event-driven way and builds up the payload, and
+ a subclass of <literal>PayloadParserFactory</literal>, which is responsible
+ for detecting whether a given parser can parse an incoming element, and
+ creates a parser. The parser factory is registered with the client using
+ <literal>Client::addPayloadParserFactory()</literal> (and unregistered
+ using <literal>Client::removePayloadParserFactory()</literal>).
+ </para>
+
+ <para>
+ Although you can subclass the base classes for parsers and serializers
+ directly, Swiften comes with utility classes that contain common
+ functionality for parsers and serializers. For example, for our EchoBot,
+ the parser and serializer using these utility classes is shown in
+ <xref linkend="Example-EchoPayloadParser"/> and
+ <xref linkend="Example-EchoPayloadSerializer"/> respectively. Registration
+ of the parser and serializer is shown in the constructor of our EchoBot in
+ <xref linkend="Example-EchoBot6"/>.
+ </para>
+
+ <example id="Example-EchoPayloadParser">
+ <title>The parser and parser factory for <literal>EchoPayload</literal></title>
+ <include xmlns="http://www.w3.org/2001/XInclude" href="Examples/EchoBot/EchoPayloadParserFactory.h.xml" xpointer="xpointer(//programlisting|//calloutlist)"/>
+ </example>
+
+ <example id="Example-EchoPayloadSerializer">
+ <title>The serializer for <literal>EchoPayload</literal></title>
+ <include xmlns="http://www.w3.org/2001/XInclude" href="Examples/EchoBot/EchoPayloadSerializer.h.xml" xpointer="xpointer(//programlisting|//calloutlist)"/>
+ </example>
+
+ <para>
+ If you want to create your own parser and serializers, you can look at the
+ built-in parsers and serializers in the Swiften library, located in
+ <literal>Swiften/Parser/PayloadParsers</literal> and <literal>Swiften/Serializer/PayloadSerializers</literal>.
+ </para>
+
</sect1>
<sect1 id="Section-CustomQueries">