pyxmpp.stanzaprocessor.StanzaProcessor

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.