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.

:Ivariables:
    - `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.
    - `initiator`: `True` if local stream endpoint is the initiating entity.

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.

Method Details

__init__(self)
(Constructor)

Initialize a `StanzaProcessor` object.

check_to(self, to)

Check "to" attribute of received stream header.

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

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

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.

:Parameters:
    - `stanza`: the 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.

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.
:Types:
    - `stanza`: `pyxmpp.stanza.Stanza`

set_iq_get_handler(self, element, namespace, handler)

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

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

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.

set_iq_set_handler(self, element, namespace, handler)

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

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

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.

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

Set a handler for <message/> stanzas.

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

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.

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

Set a handler for <presence/> stanzas.

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

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.

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.

Generated by Epydoc 2.1 on Wed May 31 22:37:02 2006 http://epydoc.sf.net