Package pyxmpp :: Module streambase :: Class StreamBase
[show private | hide private]
[frames | no frames]

Class StreamBase

StanzaProcessor --+
                  |
  StreamHandler --+
                  |
                 StreamBase

Known Subclasses:
Stream

Base class for a generic XMPP stream.

Responsible for establishing connection, parsing the stream, dispatching
received stanzas to apopriate handlers and sending application's stanzas.
This doesn't provide any authentication or encryption (both required by
the XMPP specification) and is not usable on its own.

Whenever we say "stream" here we actually mean two streams
(incoming and outgoing) of one connections, as defined by the XMPP
specification.

:Ivariables:
    - `lock`: RLock object used to synchronize access to Stream object.
    - `features`: stream features as annouced by the initiator.
    - `me`: local stream endpoint 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.
    - `_reader`: the stream reader object (push parser) for the stream.

Method Summary
  __init__(self, default_ns, extra_ns, keepalive)
Initialize Stream object :Parameters: - `default_ns`: stream's default namespace ("jabber:client" for client, "jabber:server" for server, etc.) - `extra_ns`: sequence of extra namespace URIs to be defined for the stream.
  __del__(self)
  accept(self, sock, myname)
Accept incoming connection.
  bind(self, resource)
Bind to a resource.
  check_to(self, to)
Check "to" attribute of received stream header.
  close(self)
Forcibly close the connection and clear the stream state.
  connect(self, addr, port, service, to)
Establish XMPP connection with given address.
  connected(self)
Check if stream is connected.
  disconnect(self)
Gracefully close the connection.
  error(self, descr)
Handle stream XML parse error.
  fileno(self)
Return filedescriptor of the stream socket.
  generate_id(self)
Generate a random and unique stream ID.
  idle(self)
Do some housekeeping (cache expiration, timeout handling).
  loop(self, timeout)
Simple "main loop" for the stream.
  loop_iter(self, timeout)
Single iteration of a simple "main loop" for the stream.
  process(self)
Process stream's pending events.
  process_stream_error(self, err)
Process stream error element received.
  send(self, stanza)
Write stanza to the stream.
  stanza(self, _unused, node)
Process stanza (first level child element of the stream).
  stanza_start(self, doc, node)
Process stanza (first level child element of the stream) start tag -- do nothing.
  state_change(self, state, arg)
Called when connection state is changed.
  stream_end(self, _unused)
Process </stream:stream> (stream end) tag received from peer.
  stream_start(self, doc)
Process <stream:stream> (stream start) tag received from peer.
  write_raw(self, data)
Write raw data to the stream socket.
    Inherited from StanzaProcessor
  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.
  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, default_ns, extra_ns=(), keepalive=0)
(Constructor)

Initialize Stream object

:Parameters:
  - `default_ns`: stream's default namespace ("jabber:client" for
    client, "jabber:server" for server, etc.)
  - `extra_ns`: sequence of extra namespace URIs to be defined for
    the stream.
  - `keepalive`: keepalive output interval. 0 to disable.
Overrides:
pyxmpp.stanzaprocessor.StanzaProcessor.__init__

accept(self, sock, myname)

Accept incoming connection.

[receiving entity only]

:Parameters:
    - `sock`: a listening socket.
    - `myname`: local stream endpoint name.

bind(self, resource)

Bind to a resource.

[initiating entity only]

:Parameters:
    - `resource`: the resource name to bind to.

XMPP stream is authenticated for bare JID only. To use
the full JID it must be bound to a resource.

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.
Overrides:
pyxmpp.stanzaprocessor.StanzaProcessor.check_to

close(self)

Forcibly close the connection and clear the stream state.

connect(self, addr, port, service=None, to=None)

Establish XMPP connection with given address.

[initiating entity only]

:Parameters:
    - `addr`: peer name or IP address
    - `port`: port number to connect to
    - `service`: service name (to be resolved using SRV DNS records)
    - `to`: peer name if different than `addr`

connected(self)

Check if stream is connected.

:return: True if stream connection is active.

disconnect(self)

Gracefully close the connection.

error(self, descr)

Handle stream XML parse error.

:Parameters:
    - `descr`: error description
Overrides:
pyxmpp.xmlextra.StreamHandler.error

fileno(self)

Return filedescriptor of the stream socket.

generate_id(self)

Generate a random and unique stream ID.

:return: the id string generated.

idle(self)

Do some housekeeping (cache expiration, timeout handling).

This method should be called periodically from the application's
main loop.

loop(self, timeout)

Simple "main loop" for the stream.

loop_iter(self, timeout)

Single iteration of a simple "main loop" for the stream.

process(self)

Process stream's pending events.

Should be called whenever there is input available
on `self.fileno()` socket descriptor. Is called by
`self.loop_iter`.

process_stream_error(self, err)

Process stream error element received.

:Types:
    - `err`: `StreamErrorNode`

:Parameters:
    - `err`: error received

send(self, stanza)

Write stanza to the stream.

:Parameters:
    - `stanza`: XMPP stanza to send.
Overrides:
pyxmpp.stanzaprocessor.StanzaProcessor.send

stanza(self, _unused, node)

Process stanza (first level child element of the stream).

:Parameters:
    - `_unused`: parsed document
    - `node`: stanza's full XML
Overrides:
pyxmpp.xmlextra.StreamHandler.stanza

stanza_start(self, doc, node)

Process stanza (first level child element of the stream) start tag
-- do nothing.

:Parameters:
    - `doc`: parsed document
    - `node`: stanza's full XML

state_change(self, state, arg)

Called when connection state is changed.

This method is supposed to be overriden in derived classes
or replaced by an application.

It may be used to display the connection progress.

stream_end(self, _unused)

Process </stream:stream> (stream end) tag received from peer.

:Parameters:
    - `_unused`: document created by the parser
Overrides:
pyxmpp.xmlextra.StreamHandler.stream_end

stream_start(self, doc)

Process <stream:stream> (stream start) tag received from peer.

:Parameters:
    - `doc`: document created by the parser
Overrides:
pyxmpp.xmlextra.StreamHandler.stream_start

write_raw(self, data)

Write raw data to the stream socket.

:Parameters:
    - `data`: data to send

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