gloox 1.0
Classes | Public Types | Public Member Functions

Disco Class Reference

This class implements XEP-0030 (Service Discovery) and XEP-0092 (Software Version). More...

#include <disco.h>

Inheritance diagram for Disco:
Inheritance graph
[legend]

List of all members.

Classes

class  Identity
 An abstraction of a Disco identity (Service Discovery, XEP-0030). More...
class  Info
 An abstraction of a Disco Info element (from Service Discovery, XEP-0030) as a StanzaExtension. More...
class  Item
 An abstraction of a Disco item (Service Discovery, XEP-0030). More...
class  Items
 An abstraction of a Disco query element (from Service Discovery, XEP-0030) in the disco::items namespace, implemented as a StanzaExtension. More...

Public Types

typedef std::list< Identity * > IdentityList
typedef std::list< Item * > ItemList

Public Member Functions

void addFeature (const std::string &feature)
void removeFeature (const std::string &feature)
const StringList features (bool defaultFeatures=false) const
void getDiscoInfo (const JID &to, const std::string &node, DiscoHandler *dh, int context, const std::string &tid=EmptyString)
void getDiscoItems (const JID &to, const std::string &node, DiscoHandler *dh, int context, const std::string &tid=EmptyString)
void setVersion (const std::string &name, const std::string &version, const std::string &os=EmptyString)
const std::string & name () const
const std::string & version () const
const std::string & os () const
void setIdentity (const std::string &category, const std::string &type, const std::string &name=EmptyString)
void addIdentity (const std::string &category, const std::string &type, const std::string &name=EmptyString)
const IdentityListidentities () const
void setForm (DataForm *form)
const DataFormform () const
void registerDiscoHandler (DiscoHandler *dh)
void removeDiscoHandler (DiscoHandler *dh)
void registerNodeHandler (DiscoNodeHandler *nh, const std::string &node)
void removeNodeHandler (DiscoNodeHandler *nh, const std::string &node)
void removeNodeHandlers (DiscoNodeHandler *nh)
virtual bool handleIq (const IQ &iq)
virtual void handleIqID (const IQ &iq, int context)

Detailed Description

This class implements XEP-0030 (Service Discovery) and XEP-0092 (Software Version).

ClientBase will automatically instantiate a Disco object. It can be used to announce special features of your client, or its version, or...

XEP version: 2.2

Author:
Jakob Schroeter <js@camaya.net>

Definition at line 45 of file disco.h.


Member Typedef Documentation

typedef std::list<Identity*> IdentityList

A list of pointers to Identity objects. Used with Disco::Info.

Definition at line 51 of file disco.h.

typedef std::list<Item*> ItemList

A list of pointers to Item objects. Used with Disco::Items.

Definition at line 261 of file disco.h.


Member Function Documentation

void addFeature ( const std::string &  feature) [inline]

Adds a feature to the list of supported Jabber features. The list will be posted as an answer to IQ queries in the "http://jabber.org/protocol/disco#info" namespace. These IQ packets will also be forwarded to the application's IqHandler, if it listens to the disco#info namespace. By default, disco(very) queries are handled by the library. By default, all supported, not disabled features are announced.

Parameters:
featureA feature (namespace) the host app supports.
Note:
Use this function for non-queryable features. For nodes that shall answer to disco#info queries, use registerNodeHandler().

Definition at line 422 of file disco.h.

void addIdentity ( const std::string &  category,
const std::string &  type,
const std::string &  name = EmptyString 
) [inline]

Adds another identity to the list of identities.

Parameters:
categoryThe entity category of this client. Default: client.
typeThe type of this entity. Default: bot.
nameThe name of the entity. Default: empty.

Definition at line 521 of file disco.h.

const StringList features ( bool  defaultFeatures = false) const

Lets you retrieve the features this Disco instance supports.

Parameters:
defaultFeaturesInclude default features. Defaults to false.
Returns:
A list of supported features/namespaces.

Definition at line 525 of file disco.cpp.

const DataForm* form ( ) const [inline]

Returns the DataForm set by setForm(). Used by Capabilities.

Returns:
The DataForm, or 0.

Definition at line 544 of file disco.h.

void getDiscoInfo ( const JID to,
const std::string &  node,
DiscoHandler dh,
int  context,
const std::string &  tid = EmptyString 
) [inline]

Queries the given JID for general infomation according to XEP-0030 (Service Discovery). To receive the results inherit from DiscoHandler and register with the Disco object.

Parameters:
toThe destination-JID of the query.
nodeAn optional node to query. Not inserted if empty.
dhThe DiscoHandler to notify about results.
contextA context identifier.
tidAn optional id that is going to be used as the IQ request's id. Only necessary if you need to know the request's id.

Definition at line 451 of file disco.h.

void getDiscoItems ( const JID to,
const std::string &  node,
DiscoHandler dh,
int  context,
const std::string &  tid = EmptyString 
) [inline]

Queries the given JID for its items according to XEP-0030 (Service Discovery). To receive the results inherit from DiscoHandler and register with the Disco object.

Parameters:
toThe destination-JID of the query.
nodeAn optional node to query. Not inserted if empty.
dhThe DiscoHandler to notify about results.
contextA context identifier.
tidAn optional id that is going to be used as the IQ request's id. Only necessary if you need to know the request's id.

Definition at line 466 of file disco.h.

bool handleIq ( const IQ iq) [virtual]

Reimplement this function if you want to be notified about incoming IQs.

Parameters:
iqThe complete IQ stanza.
Returns:
Indicates whether a request of type 'get' or 'set' has been handled. This includes the obligatory 'result' answer. If you return false, a 'error' will be sent.
Since:
1.0

Implements IqHandler.

Definition at line 284 of file disco.cpp.

void handleIqID ( const IQ iq,
int  context 
) [virtual]

Reimplement this function if you want to be notified about incoming IQs with a specific value of the id attribute. You have to enable tracking of those IDs using Client::trackID(). This is usually useful for IDs that generate a positive reply, i.e. <iq type='result' id='reg'/> where a namespace filter wouldn't work.

Parameters:
iqThe complete IQ stanza.
contextA value to restore context, stored with ClientBase::trackID().
Note:
Only IQ stanzas of type 'result' or 'error' can arrive here.
Since:
1.0

Implements IqHandler.

Definition at line 409 of file disco.cpp.

const IdentityList& identities ( ) const [inline]

Returns the entity's identities.

Returns:
The entity's identities.

Definition at line 529 of file disco.h.

const std::string& name ( ) const [inline]

Returns the application's advertised name.

Returns:
The application's advertised name.

Definition at line 485 of file disco.h.

const std::string& os ( ) const [inline]

Returns the application's advertised operating system.

Returns:
The application's advertised operating system.

Definition at line 497 of file disco.h.

void registerDiscoHandler ( DiscoHandler dh) [inline]

Use this function to register an DiscoHandler with the Disco object. This is only necessary if you want to receive Disco-set requests. Else a one-time registration happens when calling getDiscoInfo() and getDiscoItems(), respectively.

Parameters:
dhThe DiscoHandler-derived object to register.

Definition at line 552 of file disco.h.

void registerNodeHandler ( DiscoNodeHandler nh,
const std::string &  node 
)

Use this function to register a DiscoNodeHandler with the Disco object. The DiscoNodeHandler will receive disco::items queries which are directed to the corresponding node registered for the handler.

Parameters:
nhThe NodeHandler-derived object to register.
nodeThe node name to associate with this handler. Use an empty string to register for the root node.

Definition at line 498 of file disco.cpp.

void removeDiscoHandler ( DiscoHandler dh)

Unregisters the given DiscoHandler.

Parameters:
dhThe DiscoHandler to unregister.

Definition at line 482 of file disco.cpp.

void removeFeature ( const std::string &  feature) [inline]

Removes the given feature from the list of advertised client features.

Parameters:
featureThe feature to remove.
Since:
0.9

Definition at line 430 of file disco.h.

void removeNodeHandler ( DiscoNodeHandler nh,
const std::string &  node 
)

Removes the node handler for the given node.

Parameters:
nhThe NodeHandler to unregister.
nodeThe node for which the handler shall be removed. Use an empty string to remove the root node's handler.

Definition at line 503 of file disco.cpp.

void removeNodeHandlers ( DiscoNodeHandler nh)

Removes all registered nodes of the given node handler.

Parameters:
nhThe NodeHandler to unregister.

Definition at line 514 of file disco.cpp.

void setForm ( DataForm form)

Adds an optional DataForm to Disco:Info replies, e.g. for XEP-0232. Only one form can be added at this point.

Parameters:
formAn optional DataForm to include in the Info reply. The form will be owned by and deleted on destruction of the Disco object.
Note:
If called more than once the previously set form will be deleted.

Definition at line 278 of file disco.cpp.

void setIdentity ( const std::string &  category,
const std::string &  type,
const std::string &  name = EmptyString 
)

Sets the identity of this entity. The library uses this information to answer disco::info requests with a correct identity. XEP-0030 requires an entity to have at least one identity. See XEP-0030 for more information on categories and types.

Parameters:
categoryThe entity category of this client. Default: client.
typeThe type of this entity. Default: bot.
nameThe name of the entity. Default: empty.
Note:
An entity can have more than one identity. You cann add more identities using addIdentity(). A call to setIdentity() will clear the list of identities and, after that, add the new identity given by the arguments to setIdentity().

Definition at line 475 of file disco.cpp.

void setVersion ( const std::string &  name,
const std::string &  version,
const std::string &  os = EmptyString 
)

Sets the version of the host application using this library. The library takes care of jabber:iq:version requests. These IQ packets will not be forwarded to the IqHandlers.

Parameters:
nameThe name to be returned to inquireing clients.
versionThe version to be returned to inquireing clients.
osThe operating system to announce. Default: don't include.

Definition at line 468 of file disco.cpp.

const std::string& version ( ) const [inline]

Returns the application's advertised version.

Returns:
The application's advertised version.

Definition at line 491 of file disco.h.


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