Swiftdiff options
| author | Remko Tronçon <git@el-tramo.be> | 2010-12-04 12:43:57 (GMT) |
|---|---|---|
| committer | Remko Tronçon <git@el-tramo.be> | 2010-12-04 13:24:48 (GMT) |
| commit | bbf8a5fcb47d649bdcee1b2122eaa76f2c914ef7 (patch) | |
| tree | 3cef6ffab06f263ad6f5dc3df5d7ba065223f84e /Documentation/SwiftenDevelopersGuide/Swiften Developers Guide.xml | |
| parent | ebd2b8b8a2f1ad2812543c5350c0acf0a5b8c188 (diff) | |
| download | swift-bbf8a5fcb47d649bdcee1b2122eaa76f2c914ef7.zip swift-bbf8a5fcb47d649bdcee1b2122eaa76f2c914ef7.tar.bz2 | |
Added EchoPayload parserialement.
Diffstat (limited to 'Documentation/SwiftenDevelopersGuide/Swiften Developers Guide.xml')
| -rw-r--r-- | Documentation/SwiftenDevelopersGuide/Swiften Developers Guide.xml | 73 |
1 files changed, 72 insertions, 1 deletions
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"> |