XEP 0030¶

class slixmpp.plugins.xep_0030.XEP_0030(xmpp, config=None)[source]¶

XEP-0030: Service Discovery

Service discovery in XMPP allows entities to discover information about other agents in the network, such as the feature sets supported by a client, or signposts to other, related entities.

Also see <http://www.xmpp.org/extensions/xep-0030.html>.

The XEP-0030 plugin works using a hierarchy of dynamic node handlers, ranging from global handlers to specific JID+node handlers. The default set of handlers operate in a static manner, storing disco information in memory. However, custom handlers may use any available backend storage mechanism desired, such as SQLite or Redis.

Node handler hierarchy:

JID   | Node  | Level
---------------------
None  | None  | Global
Given | None  | All nodes for the JID
None  | Given | Node on self.xmpp.boundjid
Given | Given | A single node

Stream Handlers:

Disco Info  -- Any Iq stanze that includes a query with the
               namespace http://jabber.org/protocol/disco#info.
Disco Items -- Any Iq stanze that includes a query with the
               namespace http://jabber.org/protocol/disco#items.

Events:

disco_info         -- Received a disco#info Iq query result.
disco_items        -- Received a disco#items Iq query result.
disco_info_query   -- Received a disco#info Iq query request.
disco_items_query  -- Received a disco#items Iq query request.

Attributes:

Variables

static – Object containing the default set of static node handlers.
default_handlers – A dictionary mapping operations to the default global handler (by default, the static handlers).

add_feature(feature, node=None, jid=None)[source]¶

Add a feature to a JID/node combination.

Parameters

feature (str) – The namespace of the supported feature.
node (Optional[str]) – The node to modify.
jid (Optional[JID]) – The JID to modify.

add_identity(category='', itype='', name='', node=None, jid=None, lang=None)[source]¶

Add a new identity to the given JID/node combination.

Each identity must be unique in terms of all four identity components: category, type, name, and language.

Multiple, identical category/type pairs are allowed only if the xml:lang values are different. Likewise, multiple category/type/xml:lang pairs are allowed so long as the names are different. A category and type is always required.

Parameters

category – The identity’s category.
itype – The identity’s type.
name – Optional name for the identity.
lang – Optional two-letter language code.
node – The node to modify.
jid – The JID to modify.

add_item(jid='', name='', node=None, subnode='', ijid=None)[source]¶

Add a new item element to the given JID/node combination.

Each item is required to have a JID, but may also specify a node value to reference non-addressable entities.

Parameters

jid – The JID for the item.
name – Optional name for the item.
node – The node to modify.
subnode – Optional node for the item.
ijid – The JID to modify.

del_feature(jid=None, node=None, **kwargs)[source]¶

Remove a feature from a given JID/node combination.

Parameters

jid – The JID to modify.
node – The node to modify.
feature – The feature’s namespace.

del_features(jid=None, node=None, **kwargs)[source]¶

Remove all features from a JID/node combination.

Parameters

jid – The JID to modify.
node – The node to modify.

del_identities(jid=None, node=None, **kwargs)[source]¶

Remove all identities for a JID/node combination.

If a language is specified, only identities using that language will be removed.

Parameters

jid – The JID to modify.
node – The node to modify.
lang – Optional. If given, only remove identities using this xml:lang value.

del_identity(jid=None, node=None, **kwargs)[source]¶

Remove an identity from the given JID/node combination.

Parameters

jid (Optional[JID]) – The JID to modify.
node (Optional[str]) – The node to modify.
category – The identity’s category.
itype – The identity’s type value.
name – Optional, human readable name for the identity.
lang – Optional, the identity’s xml:lang value.

del_item(jid=None, node=None, **kwargs)[source]¶

Remove a single item from the given JID/node combination.

Parameters

jid – The JID to modify.
node – The node to modify.
ijid – The item’s JID.
inode – The item’s node.

del_items(jid=None, node=None, **kwargs)[source]¶

Remove all items from the given JID/node combination.

Arguments: :param jid: The JID to modify. :param node: Optional node to modify.

del_node_handler(htype, jid, node)[source]¶

Remove a handler type for a JID and node combination.

The next handler in the hierarchy will be used if one exists. If removing the global handler, make sure that other handlers exist to process existing nodes.

Node handler hierarchy:

JID   | Node  | Level
---------------------
None  | None  | Global
Given | None  | All nodes for the JID
None  | Given | Node on self.xmpp.boundjid
Given | Given | A single node

Parameters

htype – The type of handler to remove.
jid – The JID from which to remove the handler.
node – The node from which to remove the handler.

get_info(jid=None, node=None, local=None, cached=None, **kwargs)[source]¶

Retrieve the disco#info results from a given JID/node combination.

Info may be retrieved from both local resources and remote agents; the local parameter indicates if the information should be gathered by executing the local node handlers, or if a disco#info stanza must be generated and sent.

If requesting items from a local JID/node, then only a DiscoInfo stanza will be returned. Otherwise, an Iq stanza will be returned.

Parameters

jid – Request info from this JID.
node – The particular node to query.
local – If true, then the query is for a JID/node combination handled by this Slixmpp instance and no stanzas need to be sent. Otherwise, a disco stanza must be sent to the remote JID to retrieve the info.
cached – If true, then look for the disco info data from the local cache system. If no results are found, send the query as usual. The self.use_cache setting must be set to true for this option to be useful. If set to false, then the cache will be skipped, even if a result has already been cached. Defaults to false.

async get_info_from_domain(domain=None, timeout=None, cached=True, callback=None)[source]¶: Fetch disco#info of specified domain and one disco#items level below

get_items(jid=None, node=None, local=False, **kwargs)[source]¶

Retrieve the disco#items results from a given JID/node combination.

Items may be retrieved from both local resources and remote agents; the local parameter indicates if the items should be gathered by executing the local node handlers, or if a disco#items stanza must be generated and sent.

If requesting items from a local JID/node, then only a DiscoItems stanza will be returned. Otherwise, an Iq stanza will be returned.

Parameters

jid – Request info from this JID.
node – The particular node to query.
local – If true, then the query is for a JID/node combination handled by this Slixmpp instance and no stanzas need to be sent. Otherwise, a disco stanza must be sent to the remove JID to retrieve the items.
iterator – If True, return a result set iterator using the XEP-0059 plugin, if the plugin is loaded. Otherwise the parameter is ignored.

has_identity(jid=None, node=None, category=None, itype=None, lang=None, local=False, cached=True, ifrom=None)[source]¶

Check if a JID provides a given identity.

Return values: :param True: The identity is provided :param False: The identity is not listed :param None: Nothing could be found due to a timeout

Parameters

jid – Request info from this JID.
node – The particular node to query.
category – The category of the identity to check.
itype – The type of the identity to check.
lang – The language of the identity to check.
local – If true, then the query is for a JID/node combination handled by this Slixmpp instance and no stanzas need to be sent. Otherwise, a disco stanza must be sent to the remove JID to retrieve the info.
cached – If true, then look for the disco info data from the local cache system. If no results are found, send the query as usual. The self.use_cache setting must be set to true for this option to be useful. If set to false, then the cache will be skipped, even if a result has already been cached. Defaults to false.

restore_defaults(jid=None, node=None, handlers=None)[source]¶

Change all or some of a node’s handlers to the default handlers. Useful for manually overriding the contents of a node that would otherwise be handled by a JID level or global level dynamic handler.

The default is to use the built-in static handlers, but that may be changed by modifying self.default_handlers.

Parameters

jid – The JID owning the node to modify.
node – The node to change to using static handlers.
handlers – Optional list of handlers to change to the default version. If provided, only these handlers will be changed. Otherwise, all handlers will use the default version.

set_features(jid=None, node=None, **kwargs)[source]¶

Add or replace the set of supported features for a JID/node combination.

Parameters

jid – The JID to modify.
node – The node to modify.
features – The new set of supported features.

set_identities(jid=None, node=None, **kwargs)[source]¶

Add or replace all identities for the given JID/node combination.

The identities must be in a set where each identity is a tuple of the form: (category, type, lang, name)

Parameters

jid – The JID to modify.
node – The node to modify.
identities – A set of identities in tuple form.
lang – Optional, xml:lang value.

set_info(jid=None, node=None, info=None)[source]¶: Set the disco#info data for a JID/node based on an existing disco#info stanza.

set_items(jid=None, node=None, **kwargs)[source]¶

Set or replace all items for the specified JID/node combination.

The given items must be in a list or set where each item is a tuple of the form: (jid, node, name).

Parameters

jid – The JID to modify.
node – Optional node to modify.
items – A series of items in tuple format.

set_node_handler(htype, jid=None, node=None, handler=None)[source]¶

Add a node handler for the given hierarchy level and handler type.

Node handlers are ordered in a hierarchy where the most specific handler is executed. Thus, a fallback, global handler can be used for the majority of cases with a few node specific handler that override the global behavior.

Node handler hierarchy:

JID   | Node  | Level
---------------------
None  | None  | Global
Given | None  | All nodes for the JID
None  | Given | Node on self.xmpp.boundjid
Given | Given | A single node

Handler types:

get_info
get_items
set_identities
set_features
set_items
del_items
del_identities
del_identity
del_feature
del_features
del_item
add_identity
add_feature
add_item

Parameters

htype (str) – The operation provided by the handler.
jid (Optional[JID]) – The JID the handler applies to. May be narrowed further if a node is given.
node (Optional[str]) – The particular node the handler is for. If no JID is given, then the self.xmpp.boundjid.full is assumed.
handler (Optional[Callable]) – The handler function to use.

stanza = <module 'slixmpp.plugins.xep_0030.stanza' from '/home/docs/checkouts/readthedocs.org/user_builds/slixmpp/checkouts/slix-1.6.0/slixmpp/plugins/xep_0030/stanza/__init__.py'>¶

supports(jid=None, node=None, feature=None, local=False, cached=True, ifrom=None)[source]¶

Check if a JID supports a given feature.

Return values: :param True: The feature is supported :param False: The feature is not listed as supported :param None: Nothing could be found due to a timeout

Parameters

jid – Request info from this JID.
node – The particular node to query.
feature – The name of the feature to check.
local – If true, then the query is for a JID/node combination handled by this Slixmpp instance and no stanzas need to be sent. Otherwise, a disco stanza must be sent to the remove JID to retrieve the info.
cached – If true, then look for the disco info data from the local cache system. If no results are found, send the query as usual. The self.use_cache setting must be set to true for this option to be useful. If set to false, then the cache will be skipped, even if a result has already been cached. Defaults to false.

Stanza elements¶

See the file LICENSE for copying permission.

class slixmpp.plugins.xep_0030.stanza.info.DiscoInfo(xml=None, parent=None)[source]¶

XMPP allows for users and agents to find the identities and features supported by other entities in the XMPP network through service discovery, or “disco”. In particular, the “disco#info” query type for <iq> stanzas is used to request the list of identities and features offered by a JID.

An identity is a combination of a category and type, such as the ‘client’ category with a type of ‘pc’ to indicate the agent is a human operated client with a GUI, or a category of ‘gateway’ with a type of ‘aim’ to identify the agent as a gateway for the legacy AIM protocol. See <http://xmpp.org/registrar/disco-categories.html> for a full list of accepted category and type combinations.

Features are simply a set of the namespaces that identify the supported features. For example, a client that supports service discovery will include the feature ‘http://jabber.org/protocol/disco#info’.

Since clients and components may operate in several roles at once, identity and feature information may be grouped into “nodes”. If one were to write all of the identities and features used by a client, then node names would be like section headings.

Example disco#info stanzas:

<iq type="get">
  <query xmlns="http://jabber.org/protocol/disco#info" />
</iq>

<iq type="result">
  <query xmlns="http://jabber.org/protocol/disco#info">
    <identity category="client" type="bot" name="Slixmpp Bot" />
    <feature var="http://jabber.org/protocol/disco#info" />
    <feature var="jabber:x:data" />
    <feature var="urn:xmpp:ping" />
  </query>
</iq>

Stanza Interface:

node       -- The name of the node to either
              query or return info from.
identities -- A set of 4-tuples, where each tuple contains
              the category, type, xml:lang, and name
              of an identity.
features   -- A set of namespaces for features.

add_feature(feature)[source]¶

Add a single, new feature.

Parameters: feature – The namespace of the supported feature.

add_identity(category, itype, name=None, lang=None)[source]¶

Add a new identity element. Each identity must be unique in terms of all four identity components.

Parameters

category – The general category to which the agent belongs.
itype – A more specific designation with the category.
name – Optional human readable name for this identity.
lang – Optional standard xml:lang value.

del_feature(feature)[source]¶

Remove a single feature.

Parameters: feature – The namespace of the removed feature.

del_features()[source]¶: Remove all features.

del_identities(lang=None)[source]¶

Remove all identities. If a language was specified, only remove identities using that language.

Parameters: lang – Optional, standard xml:lang value.

del_identity(category, itype, name=None, lang=None)[source]¶

Remove a given identity.

Parameters

category – The general category to which the agent belonged.
itype – A more specific designation with the category.
name – Optional human readable name for this identity.
lang – Optional, standard xml:lang value.

get_features(dedupe=True)[source]¶: Return the set of all supported features.

get_identities(lang=None, dedupe=True)[source]¶

Return a set of all identities in tuple form as so:

(category, type, lang, name)

If a language was specified, only return identities using that language.

Parameters

lang – Optional, standard xml:lang value.
dedupe – If True, de-duplicate identities, otherwise return a list of all identities.

interfaces = {'features', 'identities', 'node'}¶

lang_interfaces = {'identities'}¶

name = 'query'¶

namespace = 'http://jabber.org/protocol/disco#info'¶

plugin_attrib = 'disco_info'¶

set_features(features)[source]¶

Add or replace the set of supported features.

Parameters: features – The new set of supported features.

set_identities(identities, lang=None)[source]¶

Add or replace all identities. The identities must be a in set where each identity is a tuple of the form:

(category, type, lang, name)

If a language is specifified, any identities using that language will be removed to be replaced with the given identities.

Note

An identity’s language will not be changed regardless of the value of lang.

Parameters

identities – A set of identities in tuple form.
lang – Optional, standard xml:lang value.

setup(xml=None)[source]¶

Populate the stanza object using an optional XML object.

Overrides ElementBase.setup

Caches identity and feature information.

Parameters: xml – Use an existing XML object for the stanza’s values.

See the file LICENSE for copying permission.

class slixmpp.plugins.xep_0030.stanza.items.DiscoItem(xml=None, parent=None)[source]¶

get_name()[source]¶: Return the item’s human readable name, or None.

get_node()[source]¶: Return the item’s node name or None.

interfaces = {'jid', 'name', 'node'}¶

name = 'item'¶

namespace = 'http://jabber.org/protocol/disco#items'¶

plugin_attrib = 'item'¶

class slixmpp.plugins.xep_0030.stanza.items.DiscoItems(xml=None, parent=None)[source]¶

Example disco#items stanzas:

<iq type="get">
  <query xmlns="http://jabber.org/protocol/disco#items" />
</iq>

<iq type="result">
  <query xmlns="http://jabber.org/protocol/disco#items">
    <item jid="chat.example.com"
          node="xmppdev"
          name="XMPP Dev" />
    <item jid="chat.example.com"
          node="slixdev"
          name="Slixmpp Dev" />
  </query>
</iq>

Stanza Interface:

node  -- The name of the node to either
         query or return info from.
items -- A list of 3-tuples, where each tuple contains
         the JID, node, and name of an item.

add_item(jid, node=None, name=None)[source]¶

Add a new item element. Each item is required to have a JID, but may also specify a node value to reference non-addressable entitities.

Parameters

jid – The JID for the item.
node – Optional additional information to reference non-addressable items.
name – Optional human readable name for the item.

del_item(jid, node=None)[source]¶

Remove a single item.

Parameters

jid – JID of the item to remove.
node – Optional extra identifying information.

del_items()[source]¶: Remove all items.

get_items()[source]¶: Return all items.

interfaces = {'items', 'node'}¶

name = 'query'¶

namespace = 'http://jabber.org/protocol/disco#items'¶

plugin_attrib = 'disco_items'¶

plugin_attrib_map = {'item': <class 'slixmpp.plugins.xep_0030.stanza.items.DiscoItem'>}¶

plugin_iterables = {<class 'slixmpp.plugins.xep_0030.stanza.items.DiscoItem'>}¶

plugin_overrides = {}¶

plugin_tag_map = {'{http://jabber.org/protocol/disco#items}item': <class 'slixmpp.plugins.xep_0030.stanza.items.DiscoItem'>}¶

set_items(items)[source]¶

Set or replace all items. The given items must be in a list or set where each item is a tuple of the form:

(jid, node, name)

Parameters: items – A series of items in tuple format.

setup(xml=None)[source]¶

Populate the stanza object using an optional XML object.

Overrides ElementBase.setup

Caches item information.

Parameters: xml – Use an existing XML object for the stanza’s values.

XEP 0030

1.6 Documentation

XEP 0030¶

Stanza elements¶