StanzaExtension Class Reference

#include <stanzaextension.h>

Inheritance diagram for StanzaExtension:

Public Member Functions
	StanzaExtension (int type)
virtual	~StanzaExtension ()
virtual Stanza *	embeddedStanza () const
virtual Tag *	embeddedTag () const
virtual const std::string &	filterString () const =0
virtual StanzaExtension *	newInstance (const Tag *tag) const =0
virtual Tag *	tag () const =0
virtual StanzaExtension *	clone () const =0
int	extensionType () const

Detailed Description

This class abstracts a stanza extension, which is usually an XML child element in a specific namespace inside an XMPP stanza.

This class is the base class for almost all protocol extensions in gloox. As such, it should be used whenever an add-on to the core XMPP spec needs to be made. For simple protocols it may suffice to create a sub-class of StanzaExtension. For protocols which require keeping of state, an additional persistent object acting like a manager may be needed.

A Stanza can be extended by additional namespaced child elements. Obviously, it is not viable to include all the kinds of extensions possible. To avoid hard-coding of such extensions into gloox, StanzaExtension can be used to inform the core of gloox about additional supported extensions without it needing to know about the exact implementation.

Note that a StanzaExtension can be used for both sending and receiving of custom protocols. When receiving, gloox requires an appropriate implementation of the pure virtuals filterString() and newInstance(). To be able to properly use the encapsulation, some getters may be necessary. Note that the object you will be dealing with usually is const.

For sending StanzaExtensions, a custom constructor (as well as some setters, possibly) is needed. Additionally, an implementation of tag() is required.

• Sub-class StanzaExtension and add at least a constructor that accepots a Tag* (so it can parse an incoming extension in XML format), as well as one accepting whatever data you need to construct outgoing extension XML. Alternatively to the latter (or in addition) you can also add setters, of course. One of the constructors should be able to create an empty instance so it can be passed to ClientBase when registering your extension type. This empty instance will only be used to create another new instance using the Tag* constructor when matching extension XML comes in.

• Re-implement filterString(). filterString() is supposed to return an XPath expression that matches the child element of a stanza that the protocol-to-implement uses. For example, consider this hypothetical XML format: The protocol is encapsulated inside a <stats> element in the 'ext:stats' namespace. It uses IQ stanzas for transmission.

  <iq from='...' to='...' id='id1' type='get'>
    <stats xmlns='ext:stats'/>
  </iq>
   
  <iq from='...' to='...' id='id1' type='result'>
    <stats xmlns='ext:stats'>
      <users>10</users>
    </stats>
  </iq>

  The idea of filterString() and its XPath expression is to match the <stats> element such that it can be fed to your StanzaExtension-derived class' constructor when creating a new instance of it. For our stats protocol, filterString() would return something like: /iq/stats[@xmlns='ext:stats']

• When subclassing StanzaExtension, you have to initialize it with an int, the extension's type. You should choose a value that is not yet used in gloox, and unique to the given extension you implement. In general, you are free to use values above ExtUser , e.g ExtUser+1, etc. See StanzaExtensionType for existing values.

• The next step is to implement newInstance(). Whenever filterString()'s XPath expression matches a child element of an incoming stanza, newInstance() is called with the matched Tag. For our example above, this is the <stats> element (including its children):

  <stats xmlns='ext:stats'>
    <users>10</users>
  </stats>

  The purpose of newInstance() is to return a new instance of your specialized StanzaExtension (implicitly cast to StanzaExtension). This way, gloox can deal entirely with the abstract base, StanzaExtension, and never ever needs to know which kind of extension it deals with. The most common implementation of newInstance() looks like this:

  StanzaExtension* StatsExtension::newInstance( const Tag* tag ) const
  {
    return new StatsExtension( tag );
  }

  This of course implies that a constructor exists that takes a const Tag* as the only parameter.

• Finally, gloox must be able to serialize the StanzaExtension back into string'ified XML. This is done by means of the tag() function which must be reimplemented. The output Tag should – like the input Tag – be embeddable into the respective stanza.

• To actually use this you have to register your new extension with ClientBase::registerStanzaExtension(). Here, an empty instance of your class should be passed, which will act as a template later (by means of StanzaExtension::clone(), which you should reimplement).

• You can now also register your handlers with ClientBase, by using the exttype you used in your subclasses with registerIqHandler() , registerMessageHandler() , registerPresenceHandler() , or registerSubscriptionHandler() . ClientBase will then check incoming stanzas against your filter string(s) and call the respective handlers.

Author

Jakob Schröter js@ca.nosp@m.maya.nosp@m..net

Since

0.9

Definition at line 203 of file stanzaextension.h.

Constructor & Destructor Documentation

StanzaExtension()

StanzaExtension ( int type )

inline

Constructs an empty StanzaExtension.

Parameters

type	Designates the extension's type. It should be one of StanzaExtensionType for built-in extensions, and it should be higher than ExtUser for custom types.

Definition at line 211 of file stanzaextension.h.

~StanzaExtension()

virtual ~StanzaExtension ( )

inlinevirtual

Virtual destructor.

Definition at line 216 of file stanzaextension.h.

Member Function Documentation

clone()

virtual StanzaExtension * clone ( ) const

pure virtual

Returns an identical copy of the current StanzaExtension.

Returns

An identical copy of the current StanzaExtension.

Implemented in Adhoc::Command, AMP, Attention, Capabilities, Carbons, ChatState, DataForm, DelayedDelivery, Disco::Info, Disco::Items, Error, FeatureNeg, Forward, GPGEncrypted, GPGSigned, IOData, Session::Jingle, LastActivity::Query, MessageEvent, MUCRoom::MUC, MUCRoom::MUCUser, Nickname, OOB, Event, Receipt, Registration::Query, SHIM, SoftwareVersion, VCard, VCardUpdate, and XHtmlIM.

embeddedStanza()

virtual Stanza * embeddedStanza ( ) const

inlinevirtual

This function returns the embedded Stanza, if any. You only have to reimplement it if your protocol flow contains embedded Stanzas.

Returns

The embedded Stanza. May be 0.

Reimplemented in Carbons, and Forward.

Definition at line 224 of file stanzaextension.h.

embeddedTag()

virtual Tag * embeddedTag ( ) const

inlinevirtual

This function returns the embedded Tag that the embedded Stanza is based on, if any. You only have to reimplement it if your protocol flow contains embedded Stanzas.

Returns

The embedded Tag. May be 0.

Reimplemented in Carbons, Forward, and Session::Jingle.

Definition at line 232 of file stanzaextension.h.

extensionType()

int extensionType ( ) const

inline

Returns the extension's type.

Returns

The extension's type.

Definition at line 271 of file stanzaextension.h.

filterString()

virtual const std::string & filterString ( ) const

pure virtual

Returns an XPath expression that describes a path to child elements of a stanza that an extension handles.

Returns

The extension's filter string.

Implemented in Adhoc::Command, AMP, Attention, Capabilities, Carbons, ChatState, DataForm, DelayedDelivery, Disco::Info, Disco::Items, Error, FeatureNeg, Forward, GPGEncrypted, GPGSigned, IOData, Session::Jingle, LastActivity::Query, MessageEvent, MUCRoom::MUC, MUCRoom::MUCUser, Nickname, OOB, Event, Receipt, Registration::Query, SHIM, SoftwareVersion, VCard, VCardUpdate, and XHtmlIM.

newInstance()

virtual StanzaExtension * newInstance ( const Tag * tag ) const

pure virtual

Returns a new Instance of the derived type. Usually, for a derived class FooExtension, the implementation of this function looks like:

StanzaExtension* FooExtension::newInstance( const Tag* tag ) const
{
  return new FooExtension( tag );
}

Returns

The derived extension's new instance.

Implemented in Adhoc::Command, AMP, Attention, Capabilities, Carbons, ChatState, DataForm, DelayedDelivery, Disco::Info, Disco::Items, Error, FeatureNeg, Forward, GPGEncrypted, GPGSigned, IOData, Session::Jingle, LastActivity::Query, MessageEvent, MUCRoom::MUC, MUCRoom::MUCUser, Nickname, OOB, Event, Receipt, Registration::Query, SHIM, SoftwareVersion, VCard, VCardUpdate, and XHtmlIM.

tag()

virtual Tag * tag ( ) const

pure virtual

Returns a Tag representation of the extension.

Returns

A Tag representation of the extension.

Implemented in Adhoc::Command, AMP, Attention, Capabilities, Carbons, ChatState, DataForm, DelayedDelivery, Disco::Info, Disco::Items, Error, FeatureNeg, Forward, GPGEncrypted, GPGSigned, IOData, Session::Jingle, LastActivity::Query, MessageEvent, MUCRoom::MUC, MUCRoom::MUCUser, Nickname, OOB, Event, Receipt, Registration::Query, SHIM, SoftwareVersion, VCard, VCardUpdate, and XHtmlIM.

---

The documentation for this class was generated from the following file:

• stanzaextension.h