# Slixmpp classes

class slixmpp.Message(*args, **kwargs)

  XMPP's <message> stanzas are a "push" mechanism to send information to other XMPP entities without requiring a response.

  Chat clients will typically use <message> stanzas that have a type of either "chat" or "groupchat".

  When handling a message event, be sure to check if the message is an error response.

  Example <message> stanzas:

      <message to="user1@example.com" from="user2@example.com">
        <body>Hi!</body>
      </message>

      <message type="groupchat" to="room@conference.example.com">
        <body>Hi everyone!</body>
      </message>

  Stanza Interface:

    - body: The main contents of the message.

    - subject: An optional description of the message's contents.

    - mucroom: (Read-only) The name of the MUC room that sent the message.

    - mucnick: (Read-only) The MUC nickname of message's sender.

  Attributes:

    - types: May be one of: normal, chat, headline, groupchat, or error.

  chat()

    Set the message type to 'chat'.

  del_mucnick()

    Dummy method to prevent deletion.

  del_mucroom()

    Dummy method to prevent deletion.

  del_parent_thread()

    Delete the message thread's parent reference.

  get_mucnick()

    Return the nickname of the MUC user that sent the message.

    Read-only stanza interface.

    Return type

      str

  get_mucroom()

    Return the name of the MUC room where the message originated.

    Read-only stanza interface.

    Return type

      str

  get_parent_thread()

    Return the message thread's parent thread.

    Return type

      str

  get_type()

    Return the message type.

    Overrides default stanza interface behavior.

    Returns 'normal' if no type attribute is present.

    Return type

      str

  normal()

    Set the message type to 'normal'.

  reply(body=None, clear=True)

    Create a message reply.

    Overrides StanzaBase.reply.

    Sets proper 'to' attribute if the message is from a MUC, and adds a message body if one is given.

    Parameters

      - body (str) -- Optional text content for the message.

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

    Return type

      `Message`

  set_mucnick(value)

    Dummy method to prevent modification.

  set_mucroom(value)

    Dummy method to prevent modification.

  set_parent_thread(value)

    Add or change the message thread's parent thread.

    Parameters

      value (str) -- identifier of the thread

class slixmpp.Presence(*args, **kwargs)

  XMPP's <presence> stanza allows entities to know the status of other clients and components. Since it is currently the only multi-cast stanza in XMPP, many extensions add more information to <presence> stanzas to broadcast to every entry in the roster, such as capabilities, music choices, or locations (XEP-0115: Entity Capabilities and XEP-0163: Personal Eventing Protocol).

  Since <presence> stanzas are broadcast when an XMPP entity changes its status, the bulk of the traffic in an XMPP network will be from <presence> stanzas. Therefore, do not include more information than necessary in a status message or within a <presence> stanza in order to help keep the network running smoothly.

  Example <presence> stanzas:

      <presence />

      <presence from="user@example.com">
        <show>away</show>
        <status>Getting lunch.</status>
        <priority>5</priority>
      </presence>

      <presence type="unavailable" />

      <presence to="user@otherhost.com" type="subscribe" />

  Stanza Interface:

    - priority: A value used by servers to determine message routing.

    - show: The type of status, such as away or available for chat.

    - status: Custom, human readable status message.

  Attributes:

    - types: One of: available, unavailable, error, probe, subscribe, subscribed, unsubscribe, and unsubscribed.

    - showtypes: One of: away, chat, dnd, and xa.

  del_type()

    Remove both the type attribute and the <show> element.

  get_priority()

    Return the value of the <presence> element as an integer.

    Return type

      int

  get_type()

    Return the value of the <presence> stanza's type attribute, or the value of the <show> element if valid.

  reply(clear=True)

    Create a new reply <presence/> stanza from `self`.

    Overrides StanzaBase.reply.

    Parameters

      clear (bool) -- Indicates if the stanza contents should be removed before replying. Defaults to True.

  set_priority(value)

    Set the entity's priority value. Some server use priority to determine message routing behavior.

    Bot clients should typically use a priority of 0 if the same JID is used elsewhere by a human-interacting client.

    Parameters

      value (int) -- An integer value greater than or equal to 0.

  set_show(show)

    Set the value of the <show> element.

    Parameters

      show (str) -- Must be one of: away, chat, dnd, or xa.

  set_type(value)

    Set the type attribute's value, and the <show> element if applicable.

    Parameters

      value (str) -- Must be in either self.types or self.showtypes.

class slixmpp.Iq(*args, **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

  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, timeout_callback=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 the timeout_callback is called, instead of the regular callback

      - timeout_callback (function) -- Optional reference to a stream handler function. Will be executed when the timeout expires before a response has been received for the originally-sent IQ stanza.

    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.