Package pyxmpp :: Module stanzaprocessor :: Class StanzaProcessor
[show private | hide private]
[frames | no frames]

Class StanzaProcessor

Known Subclasses:
StreamBase

Universal stanza handler/router class.

Provides facilities to set up custom handlers for various types of stanzas.


Method Summary
  __init__(self)
Initialize a StanzaProcessor object.
  check_to(self, to)
Check "to" attribute of received stream header.
  fix_in_stanza(self, stanza)
Modify incoming stanza before processing it.
  fix_out_stanza(self, stanza)
Modify outgoing stanza before sending into the stream.
  process_iq(self, stanza)
Process IQ stanza received.
  process_message(self, stanza)
Process message stanza.
  process_presence(self, stanza)
Process presence stanza.
  process_stanza(self, stanza)
Process stanza received from the stream.
  route_stanza(self, stanza)
Process stanza not addressed to us.
  send(self, stanza)
Send a stanza somwhere.
  set_iq_get_handler(self, element, namespace, handler)
Set <iq type="get"/> handler.
  set_iq_set_handler(self, element, namespace, handler)
Set <iq type="set"/> handler.
  set_message_handler(self, typ, handler, namespace, priority)
Set a handler for <message/> stanzas.
  set_presence_handler(self, typ, handler, namespace, priority)
Set a handler for <presence/> stanzas.
  set_response_handlers(self, iq, res_handler, err_handler, timeout_handler, timeout)
Set response handler for an IQ "get" or "set" stanza.
  unset_iq_get_handler(self, element, namespace)
Remove <iq type="get"/> handler.
  unset_iq_set_handler(self, element, namespace)
Remove <iq type="set"/> handler.

Instance Variable Summary
  initiator: True if local stream endpoint is the initiating entity.
  lock: lock object used to synchronize access to the StanzaProcessor object.
  me: local JID.
  peer: remote stream endpoint JID.
  process_all_stanzas: when True then all stanzas received are considered local.

Method Details

__init__(self)
(Constructor)

Initialize a StanzaProcessor object.

check_to(self, to)

Check "to" attribute of received stream header.

Should be overriden in derived classes which require other logic for handling that attribute.

Returns:
to if it is equal to self.me, None otherwise.

fix_in_stanza(self, stanza)

Modify incoming stanza before processing it.

This implementation does nothig. It should be overriden in derived classes if needed.

fix_out_stanza(self, stanza)

Modify outgoing stanza before sending into the stream.

This implementation does nothig. It should be overriden in derived classes if needed.

process_iq(self, stanza)

Process IQ stanza received.

If a matching handler is available pass the stanza to it. Otherwise ignore it if it is "error" or "result" stanza or return "feature-not-implemented" error.

Parameters:
stanza - the stanza received

process_message(self, stanza)

Process message stanza.

Pass it to a handler of the stanza's type and payload namespace. If no handler for the actual stanza type succeeds then hadlers for type "normal" are used.

Parameters:
stanza - message stanza to be handled

process_presence(self, stanza)

Process presence stanza.

Pass it to a handler of the stanza's type and payload namespace.

Parameters:
stanza - presence stanza to be handled

process_stanza(self, stanza)

Process stanza received from the stream.

First "fix" the stanza with self.fix_in_stanza(), then pass it to self.route_stanza() if it is not directed to self.me and self.process_all_stanzas is not True. Otherwise stanza is passwd to self.process_iq(), self.process_message() or self.process_presence() appropriately.

Parameters:
stanza - the stanza received.
Returns:
True when stanza was handled

route_stanza(self, stanza)

Process stanza not addressed to us.

Return "recipient-unavailable" return if it is not "error" nor "result" stanza.

This method should be overriden in derived classes if they are supposed to handle stanzas not addressed directly to local stream endpoint.

Parameters:
stanza - presence stanza to be processed

send(self, stanza)

Send a stanza somwhere. This one does nothing. Should be overriden in derived classes.
Parameters:
stanza - the stanza to send.
           (type=pyxmpp.stanza.Stanza)

set_iq_get_handler(self, element, namespace, handler)

Set <iq type="get"/> handler.

Only one handler may be defined per one namespaced element. If a handler for the element was already set it will be lost after calling this method.

Parameters:
element - payload element name
namespace - payload element namespace URI
handler - function to be called when a stanza with defined element is received. Its only argument will be the stanza received.

set_iq_set_handler(self, element, namespace, handler)

Set <iq type="set"/> handler.

Only one handler may be defined per one namespaced element. If a handler for the element was already set it will be lost after calling this method.

Parameters:
element - payload element name
namespace - payload element namespace URI
handler - function to be called when a stanza with defined element is received. Its only argument will be the stanza received.

set_message_handler(self, typ, handler, namespace=None, priority=100)

Set a handler for <message/> stanzas.

Multiple <message /> handlers with the same type/namespace/priority may be set. Order of calling handlers with the same priority is not defined. Handlers will be called in priority order until one of them returns True.

Parameters:
typ - message type. None will be treated the same as "normal", and will be the default for unknown types (those that have no handler associated).
namespace - payload namespace. If None that message with any payload (or even with no payload) will match.
priority - priority value for the handler. Handlers with lower priority value are tried first.

set_presence_handler(self, typ, handler, namespace=None, priority=100)

Set a handler for <presence/> stanzas.

Multiple <presence /> handlers with the same type/namespace/priority may be set. Order of calling handlers with the same priority is not defined. Handlers will be called in priority order until one of them returns True.

Parameters:
typ - presence type. None will be treated the same as "available".
namespace - payload namespace. If None that presence with any payload (or even with no payload) will match.
priority - priority value for the handler. Handlers with lower priority value are tried first.

set_response_handlers(self, iq, res_handler, err_handler, timeout_handler=None, timeout=300)

Set response handler for an IQ "get" or "set" stanza.

This should be called before the stanza is sent.

Parameters:
iq - an IQ stanza
res_handler - result handler for the stanza. Will be called when matching <iq type="result"/> is received. Its only argument will be the stanza received.
err_handler - error handler for the stanza. Will be called when matching <iq type="error"/> is received. Its only argument will be the stanza received.
timeout_handler - timeout handler for the stanza. Will be called when no matching <iq type="result"/> or <iq type="error"/> is received in next timeout seconds. The handler should accept two arguments and ignore them.
timeout - timeout value for the stanza. After that time if no matching <iq type="result"/> nor <iq type="error"/> stanza is received, then timeout_handler (if given) will be called.

unset_iq_get_handler(self, element, namespace)

Remove <iq type="get"/> handler.
Parameters:
element - payload element name
namespace - payload element namespace URI

unset_iq_set_handler(self, element, namespace)

Remove <iq type="set"/> handler.
Parameters:
element - payload element name.
namespace - payload element namespace URI.

Instance Variable Details

initiator

True if local stream endpoint is the initiating entity.

lock

lock object used to synchronize access to the StanzaProcessor object.

me

local JID.

peer

remote stream endpoint JID.

process_all_stanzas

when True then all stanzas received are considered local.