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

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

Queries the presence status of one or more Google Talk users.

Arguments

jid

The XMPP address (JID) whose presence status to check, or a list of JIDs (if you are checking the presence status for multiple users). Must be the bare JID of a Google Talk user, such as [email protected] . 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 jid is a single JID (meaning that the presence status for a single user is being queried), and get_show is True , this function will return a tuple consisting of ( availability , show ). availability will be True if the user is online and available, and False if the user is not online or away. show is a String corresponding to a PRESENCE_SHOW_ value as defined in the xmpp module and XMPP RFC 3921.

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

If jid is a list of JID values (meaning that the presence status for multiple users is being queried) then get_show will automatically be set to True , and this function will return a list of tuples consisting of ( availability , show , valid ), where each tuple corresponds to one of the users whose presence status was queried, ordered so as to correspond with the order of the provided JID values. availability and show represent the same values as in a single-JID query, and valid is a boolean that will be set to True if the provided JID is valid and False if it is invalid.

An InvalidJidError will be raised if all of the provided JIDs are invalid.

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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .