Skip to content
Back to top
View this page

# IQ Stanza

class slixmpp.stanza.Iq(*args, recv=False, **kwargs)

  XMPP <iq> stanzas, or info/query stanzas, are XMPP’s method of requesting and modifying information, similar to HTTP’s GET and POST methods.

  Each <iq> stanza must have an ‘id’ value which associates the stanza with the response stanza. XMPP entities must always be given a response <iq> stanza with a type of ‘result’ after sending a stanza of type ‘get’ or ‘set’.

  Most uses cases for <iq> stanzas will involve adding a <query> element whose namespace indicates the type of information desired. However, some custom XMPP applications use <iq> stanzas as a carrier stanza for an application-specific protocol instead.

  Example <iq> Stanzas:

      <iq to="user@example.com" type="get" id="314">
        <query xmlns="http://jabber.org/protocol/disco#items" />
      </iq>

      <iq to="user@localhost" type="result" id="17">
        <query xmlns='jabber:iq:roster'>
          <item jid='otheruser@example.net'
                name='John Doe'
                subscription='both'>
            <group>Friends</group>
          </item>
        </query>
      </iq>

  Stanza Interface:

    - query: The namespace of the <query> element if one exists.

  Attributes:

    - types: May be one of: get, set, result, or error.

  del_query()

    Remove the <query> element.

  get_query()

    Return the namespace of the <query> element.

    Return type:

      str

  interfaces: ClassVar[Set[str]] = {'from', 'id', 'query', 'to', 'type'}

    The set of keys that the stanza provides for accessing and manipulating the underlying XML object. This set may be augmented with the `plugin_attrib` value of any registered stanza plugins.

  name: ClassVar[str] = 'iq'

    The XML tag name of the element, not including any namespace prefixes. For example, an `ElementBase` object for `<message />` would use `name = 'message'`.

  namespace: str = 'jabber:client'

    The default XMPP client namespace

  plugin_attrib: ClassVar[str] = 'iq'

    For `ElementBase` subclasses which are intended to be used as plugins, the `plugin_attrib` value defines the plugin name. Plugins may be accessed by using the `plugin_attrib` value as the interface. An example using `plugin_attrib = 'foo'`:

        register_stanza_plugin(Message, FooPlugin)
        msg = Message()
        msg['foo']['an_interface_from_the_foo_plugin']

  plugin_attrib_map: ClassVar[Dict[str, Type[ElementBase]]] = {'error': <class 'slixmpp.stanza.error.Error'>, 'pubsub': <class 'slixmpp.plugins.xep_0060.stanza.pubsub.Pubsub'>, 'pubsub_owner': <class 'slixmpp.plugins.xep_0060.stanza.pubsub_owner.PubsubOwner'>, 'roster': <class 'slixmpp.stanza.roster.Roster'>, 'vcard': <class 'slixmpp.plugins.xep_0292.stanza.VCard4'>}

    A mapping of the `plugin_attrib` values of registered plugins to their respective classes.

  plugin_iterables: ClassVar[Set[Type[ElementBase]]] = {}

    The set of stanza classes that can be iterated over using the ‘substanzas’ interface. Classes are added to this set when registering a plugin with `iterable=True`:

        register_stanza_plugin(DiscoInfo, DiscoItem, iterable=True)

    Added in version 1.0-Beta5.

  plugin_overrides: ClassVar[Dict[str, str]] = {}

    A map of interface operations to the overriding functions. For example, after overriding the `set` operation for the interface `body`, `plugin_overrides` would be:

        {'set_body': <some function>}

  plugin_tag_map: ClassVar[Dict[str, Type[ElementBase]]] = {'{http://jabber.org/protocol/pubsub#owner}pubsub': <class 'slixmpp.plugins.xep_0060.stanza.pubsub_owner.PubsubOwner'>, '{http://jabber.org/protocol/pubsub}pubsub': <class 'slixmpp.plugins.xep_0060.stanza.pubsub.Pubsub'>, '{jabber:client}error': <class 'slixmpp.stanza.error.Error'>, '{jabber:iq:roster}query': <class 'slixmpp.stanza.roster.Roster'>, '{urn:ietf:params:xml:ns:vcard-4.0}vcard': <class 'slixmpp.plugins.xep_0292.stanza.VCard4'>}

    A mapping of root element tag names (in `'{namespace}elementname'` format) to the plugin classes responsible for them.

  reply(clear=True)

    Create a new <iq> stanza replying to `self`.

    Overrides StanzaBase.reply

    Sets the ‘type’ to ‘result’ in addition to the default StanzaBase.reply behavior.

    Parameters:

      clear (bool) – Indicates if existing content should be removed before replying. Defaults to True.

  send(callback=None, timeout=None)

    Send an <iq> stanza over the XML stream.

    A callback handler can be provided that will be executed when the Iq stanza’s result reply is received.

    Returns a future which result will be set to the result Iq if it is of type ‘get’ or ‘set’ (when it is received), or a future with the result set to None if it has another type.

    Overrides StanzaBase.send

    Parameters:

      - callback (function) – Optional reference to a stream handler function. Will be executed when a reply stanza is received.

      - timeout (int) – The length of time (in seconds) to wait for a response before raising an IqTimeout

    Return type:

      asyncio.Future

  set_payload(value)

    Set the XML contents of the <iq> stanza.

    Parameters:

      value (list or XML object) – An XML object or a list of XML objects to use as the <iq> stanza’s contents

  set_query(value)

    Add or modify a <query> element.

    Query elements are differentiated by their namespace.

    Parameters:

      value (str) – The namespace of the <query> element.

  unhandled()

    Send a feature-not-implemented error if the stanza is not handled.

    Overrides StanzaBase.unhandled.