Disco Class Reference

`#include <disco.h>`

Inheritance diagram for Disco:
[legend]

## Classes

class | Info
class | Identity
class | Items
class | Item

## 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 IdentityList & | identities () const
void | setForm (DataForm *form)
const DataForm * | form () 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)
Public Member Functions inherited from IqHandler
virtual | ~IqHandler ()

## 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 Schröter js@ca.nosp@m.maya.nosp@m..net

Definition at line 45 of file disco.h.

## Member Typedef Documentation

## IdentityList

typedef std::list<Identity*> IdentityList

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

Definition at line 56 of file disco.h.

## ItemList

typedef std::list<Item*> ItemList

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

Definition at line 266 of file disco.h.

## Member Function Documentation

## addFeature()

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

  feature | A 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.

## addIdentity()

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

  category | The entity category of this client. Default: client. May not be empty.
  type | The type of this entity. Default: bot. May not be empty.
  name | The name of the entity. Default: empty.

Definition at line 521 of file disco.h.

## features()

const StringList features | ( | bool | defaultFeatures = false | ) | const

Lets you retrieve the features this Disco instance supports.

Parameters

  defaultFeatures | Include default features. Defaults to false.

Returns
  A list of supported features/namespaces.

Definition at line 524 of file disco.cpp.

## form()

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.

## getDiscoInfo()

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

  to | The destination-JID of the query.
  node | An optional node to query. Not inserted if empty.
  dh | The DiscoHandler to notify about results.
  context | A context identifier.
  tid | An 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.

## getDiscoItems()

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

  to | The destination-JID of the query.
  node | An optional node to query. Not inserted if empty.
  dh | The DiscoHandler to notify about results.
  context | A context identifier.
  tid | An 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.

## handleIq()

bool handleIq | ( | const IQ & | iq | ) |

virtual

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

Parameters

  iq | The 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, an 'error' will be sent back.

Since
  1.0

Implements IqHandler.

Definition at line 283 of file disco.cpp.

## handleIqID()

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 empty positive reply, i.e. <iq type='result' id='reg'/> where a namespace filter wouldn't work.

Parameters

  iq | The complete IQ stanza.
  context | A 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 408 of file disco.cpp.

## identities()

const IdentityList & identities | ( |  | ) | const

inline

Returns the entity's identities.

Returns
  The entity's identities.

Definition at line 529 of file disco.h.

## name()

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.

## os()

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.

## registerDiscoHandler()

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

  dh | The DiscoHandler-derived object to register.

Definition at line 552 of file disco.h.

## registerNodeHandler()

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

  nh | The NodeHandler-derived object to register.
  node | The node name to associate with this handler. Use an empty string to register for the root node.

Definition at line 497 of file disco.cpp.

## removeDiscoHandler()

void removeDiscoHandler | ( | DiscoHandler * | dh | ) |

Unregisters the given DiscoHandler.

Parameters

  dh | The DiscoHandler to unregister.

Definition at line 481 of file disco.cpp.

## removeFeature()

void removeFeature | ( | const std::string & | feature | ) |

inline

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

Parameters

  feature | The feature to remove.

Since
  0.9

Definition at line 430 of file disco.h.

## removeNodeHandler()

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

Removes the node handler for the given node.

Parameters

  nh | The NodeHandler to unregister.
  node | The node for which the handler shall be removed. Use an empty string to remove the root node's handler.

Definition at line 502 of file disco.cpp.

## removeNodeHandlers()

void removeNodeHandlers | ( | DiscoNodeHandler * | nh | ) |

Removes all registered nodes of the given node handler.

Parameters

  nh | The NodeHandler to unregister.

Definition at line 513 of file disco.cpp.

## setForm()

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

  form | An 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 277 of file disco.cpp.

## setIdentity()

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

  category | The entity category of this client. Default: client. May not be empty.
  type | The type of this entity. Default: bot. May not be empty.
  name | The 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 474 of file disco.cpp.

## setVersion()

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

  name | The name to be returned to inquiring clients.
  version | The version to be returned to inquiring clients.
  os | The operating system to announce. Default: don't include.

Definition at line 467 of file disco.cpp.

## version()

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:

- disco.h
- disco.cpp