English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# Functions

The `google.appengine.api.xmpp` package provides the following functions:

get_presence(jid, from_jid=None, get_show=False)

  Queries the presence status of a Google Talk user.

  Arguments:

  jid
    The XMPP address (JID) whose presence status to check. Must be the bare JID of a Google Talk user, such as `example@gmail.com`. Can be a `@gmail.com` JID, or a JID using a Google Apps domain.
  from_jid
    A custom XMPP address from which to request the presence status. Must either be `app-id@appspot.com` or match the pattern `anything@app-id.appspotchat.com`. If `None`, defaults to `app-id@appspot.com`.
  get_show
    If `True`, this function will return a tuple consisting of (`availability`, `show`). The first value in the tuple will be `True` if the user is online and available, and `False` if the user is not online or away. The second value is a String corresponding to a `PRESENCE_SHOW_` value as defined in the `xmpp` module and XMPP RFC 3921.

    If `False` this function will return `True` if the user is online and available, `False` if the user is not online or away.

send_invite(jid, from_jid=None)

  Sends an invitation to a user to chat.

  Arguments:

  jid
    The XMPP address to invite.
  from_jid
    A custom XMPP address from which to send the invitation. Must either be `your_app_id@appspot.com` or match the pattern `anything@your_app_id.appspotchat.com`. If `None`, defaults to `your_app_id@appspot.com`.
send_message(jids, body, from_jid=None, message_type=MESSAGE_TYPE_CHAT, raw_xml=False)

  Sends a message to a user.

  Arguments:

  jids
    The recipients of the message, as a single XMPP address (a string), or as a list of XMPP addresses.
  body
    The body content of the message.
  from_jid
    A custom XMPP address from which to send the message. Must either be `your_app_id@appspot.com` or match the pattern `anything@your_app_id.appspotchat.com`. If `None`, defaults to `your_app_id@appspot.com`.
  message_type

    The type of the message, one of the types allowed by RFC 3921. The allowed values are defined by the following constants:

    - `xmpp.MESSAGE_TYPE_CHAT`: a one-to-one chat message
    - `xmpp.MESSAGE_TYPE_ERROR`: an error message, in response to an incoming message
    - `xmpp.MESSAGE_TYPE_GROUPCHAT`: a group chat message
    - `xmpp.MESSAGE_TYPE_HEADLINE`: an announcement message
    - `xmpp.MESSAGE_TYPE_NORMAL`: a message expecting a reply, but is not a one-to-one chat or group chat message

    Note: An app can only receive messages of the "chat" and "normal" types. In particular, this means that apps cannot participate in group chats. An app can otherwise send messages of any of the supported types.

  raw_xml
    If `True`, the body is expected to be valid XML that is included verbatim in the XMPP message stanza. If `False`, the body is treated as plain text (XML characters are escaped before being inserted into the XMPP message).

  Returns a list of status values, one for each intended recipient in jids. Each status value is one of the following:

  - `xmpp.NO_ERROR`: the message was sent successfully to this user
  - `xmpp.INVALID_JID`: this XMPP address was invalid
  - `xmpp.OTHER_ERROR`: another error occurred while sending the message to this user
send_presence(jid, status=None, from_jid=None, presence_type=PRESENCE_TYPE_AVAILABLE, presence_show=PRESENCE_SHOW_NONE)
  Sends presence information to the given user, or, if `presence_type` is `PRESENCE_TYPE_PROBE`, requests presence information from the given user.
  Arguments:
  jid
    The XMPP address where you wish to send the presence.
  status
    An optional status message to send to the given JID, up to 1KB. This message provides the status of the application in the user's roster.
  from_jid
    The optional custom JID to use for sending. Currently, the default is `<appid>@appspot.com`. This is supported as a value. Custom JIDs can be of the form `<anything>@<appid>.appspotchat.com`.
  presence_type
    Optional type of the presence. This argument accepts a subset of the types specified in RFC 3921, section 2.2.1. An empty string results in a presence stanza without a `type` attribute. For convenience, all of the valid types are in the `PRESENCE_TYPE_*` constants list in the `google.appengine.api.xmpp` package. The default is `PRESENCE_TYPE_AVAILABLE`. Any other values throw an exception.
    If this parameter is set to `PRESENCE_TYPE_PROBE`, this method requests presence information from the specified XMPP address. Presence information will be sent via POST to `/_ah/xmpp/presence/available` or `/_ah/xmpp/presence/unavailable` as appropriate. See the overview of user presence for more information.
  presence_show
    Optional value that sets the current status for the presence. Restricted to the values specified in RFC 3921, section 2.2.2.1. You can find the valid types in the `PRESENCE_SHOW_*` constants in the google.api.xmpp package. The default is `PRESENCE_SHOW_NONE`. Any other values throw an exception.