# SleekXMPP 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.

  `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.