d7ba7cc72a
Since camelcase names are aliased to the underscored name at startup, if the underscored version is replaced later, the camelCase name does not reflect the change.
232 lines
7.9 KiB
Python
232 lines
7.9 KiB
Python
"""
|
|
SleekXMPP: The Sleek XMPP Library
|
|
Copyright (C) 2010 Nathanael C. Fritz
|
|
This file is part of SleekXMPP.
|
|
|
|
See the file LICENSE for copying permission.
|
|
"""
|
|
|
|
from sleekxmpp.stanza import Error
|
|
from sleekxmpp.stanza.rootstanza import RootStanza
|
|
from sleekxmpp.xmlstream import StanzaBase, ET
|
|
from sleekxmpp.xmlstream.handler import Waiter, Callback
|
|
from sleekxmpp.xmlstream.matcher import MatcherId
|
|
|
|
|
|
class Iq(RootStanza):
|
|
|
|
"""
|
|
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.
|
|
|
|
Methods:
|
|
__init__ -- Overrides StanzaBase.__init__.
|
|
unhandled -- Send error if there are no handlers.
|
|
set_payload -- Overrides StanzaBase.set_payload.
|
|
set_query -- Add or modify a <query> element.
|
|
get_query -- Return the namespace of the <query> element.
|
|
del_query -- Remove the <query> element.
|
|
reply -- Overrides StanzaBase.reply
|
|
send -- Overrides StanzaBase.send
|
|
"""
|
|
|
|
namespace = 'jabber:client'
|
|
name = 'iq'
|
|
interfaces = set(('type', 'to', 'from', 'id', 'query'))
|
|
types = set(('get', 'result', 'set', 'error'))
|
|
plugin_attrib = name
|
|
|
|
def __init__(self, *args, **kwargs):
|
|
"""
|
|
Initialize a new <iq> stanza with an 'id' value.
|
|
|
|
Overrides StanzaBase.__init__.
|
|
"""
|
|
StanzaBase.__init__(self, *args, **kwargs)
|
|
if self['id'] == '':
|
|
if self.stream is not None:
|
|
self['id'] = self.stream.new_id()
|
|
else:
|
|
self['id'] = '0'
|
|
|
|
def unhandled(self):
|
|
"""
|
|
Send a feature-not-implemented error if the stanza is not handled.
|
|
|
|
Overrides StanzaBase.unhandled.
|
|
"""
|
|
if self['type'] in ('get', 'set'):
|
|
self.reply()
|
|
self['error']['condition'] = 'feature-not-implemented'
|
|
self['error']['text'] = 'No handlers registered for this request.'
|
|
self.send()
|
|
|
|
def set_payload(self, value):
|
|
"""
|
|
Set the XML contents of the <iq> stanza.
|
|
|
|
Arguments:
|
|
value -- An XML object to use as the <iq> stanza's contents
|
|
"""
|
|
self.clear()
|
|
StanzaBase.set_payload(self, value)
|
|
return self
|
|
|
|
def set_query(self, value):
|
|
"""
|
|
Add or modify a <query> element.
|
|
|
|
Query elements are differentiated by their namespace.
|
|
|
|
Arguments:
|
|
value -- The namespace of the <query> element.
|
|
"""
|
|
query = self.xml.find("{%s}query" % value)
|
|
if query is None and value:
|
|
self.clear()
|
|
query = ET.Element("{%s}query" % value)
|
|
self.xml.append(query)
|
|
return self
|
|
|
|
def get_query(self):
|
|
"""Return the namespace of the <query> element."""
|
|
for child in self.xml.getchildren():
|
|
if child.tag.endswith('query'):
|
|
ns = child.tag.split('}')[0]
|
|
if '{' in ns:
|
|
ns = ns[1:]
|
|
return ns
|
|
return ''
|
|
|
|
def del_query(self):
|
|
"""Remove the <query> element."""
|
|
for child in self.xml.getchildren():
|
|
if child.tag.endswith('query'):
|
|
self.xml.remove(child)
|
|
return self
|
|
|
|
def reply(self, clear=True):
|
|
"""
|
|
Send a reply <iq> stanza.
|
|
|
|
Overrides StanzaBase.reply
|
|
|
|
Sets the 'type' to 'result' in addition to the default
|
|
StanzaBase.reply behavior.
|
|
|
|
Arguments:
|
|
clear -- Indicates if existing content should be
|
|
removed before replying. Defaults to True.
|
|
"""
|
|
self['type'] = 'result'
|
|
StanzaBase.reply(self, clear)
|
|
return self
|
|
|
|
def send(self, block=True, timeout=None, callback=None):
|
|
"""
|
|
Send an <iq> stanza over the XML stream.
|
|
|
|
The send call can optionally block until a response is received or
|
|
a timeout occurs. Be aware that using blocking in non-threaded event
|
|
handlers can drastically impact performance. Otherwise, a callback
|
|
handler can be provided that will be executed when the Iq stanza's
|
|
result reply is received. Be aware though that that the callback
|
|
handler will not be executed in its own thread.
|
|
|
|
Using both block and callback is not recommended, and only the
|
|
callback argument will be used in that case.
|
|
|
|
Overrides StanzaBase.send
|
|
|
|
Arguments:
|
|
block -- Specify if the send call will block until a response
|
|
is received, or a timeout occurs. Defaults to True.
|
|
timeout -- The length of time (in seconds) to wait for a response
|
|
before exiting the send call if blocking is used.
|
|
Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
|
|
callback -- Optional reference to a stream handler function. Will
|
|
be executed when a reply stanza is received.
|
|
"""
|
|
if timeout is None:
|
|
timeout = self.stream.response_timeout
|
|
if callback is not None and self['type'] in ('get', 'set'):
|
|
handler_name = 'IqCallback_%s' % self['id']
|
|
handler = Callback(handler_name,
|
|
MatcherId(self['id']),
|
|
callback,
|
|
once=True)
|
|
self.stream.register_handler(handler)
|
|
StanzaBase.send(self)
|
|
return handler_name
|
|
elif block and self['type'] in ('get', 'set'):
|
|
waitfor = Waiter('IqWait_%s' % self['id'], MatcherId(self['id']))
|
|
self.stream.register_handler(waitfor)
|
|
StanzaBase.send(self)
|
|
return waitfor.wait(timeout)
|
|
else:
|
|
return StanzaBase.send(self)
|
|
|
|
def _set_stanza_values(self, values):
|
|
"""
|
|
Set multiple stanza interface values using a dictionary.
|
|
|
|
Stanza plugin values may be set usind nested dictionaries.
|
|
|
|
If the interface 'query' is given, then it will be set
|
|
last to avoid duplication of the <query /> element.
|
|
|
|
Overrides ElementBase._set_stanza_values.
|
|
|
|
Arguments:
|
|
values -- A dictionary mapping stanza interface with values.
|
|
Plugin interfaces may accept a nested dictionary that
|
|
will be used recursively.
|
|
"""
|
|
query = values.get('query', '')
|
|
if query:
|
|
del values['query']
|
|
StanzaBase._set_stanza_values(self, values)
|
|
self['query'] = query
|
|
else:
|
|
StanzaBase._set_stanza_values(self, values)
|
|
return self
|
|
|
|
|
|
# To comply with PEP8, method names now use underscores.
|
|
# Deprecated method names are re-mapped for backwards compatibility.
|
|
Iq.setPayload = Iq.set_payload
|
|
Iq.getQuery = Iq.get_query
|
|
Iq.setQuery = Iq.set_query
|
|
Iq.delQuery = Iq.del_query
|