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.


Method Summary
  __init__(self, default_ns, extra_ns, keepalive)
Initialize Stream object
  __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.
  _accept(self, sock, myname)
Same as Stream.accept but assume self.lock is acquired.
  _bind_error(self, stanza)
Handle resource binding success.
  _bind_success(self, stanza)
Handle resource binding success.
  _close(self)
Same as Stream.close but assume self.lock is acquired.
  _connect(self, addr, port, service, to)
Same as Stream.connect but assume self.lock is acquired.
  _connect_socket(self, sock, to)
Initialize stream on outgoing connection.
  _disconnect(self)
Same as Stream.disconnect but assume self.lock is acquired.
  _feed_reader(self, data)
Feed the stream reader with data received.
  _got_features(self)
Process incoming <stream:features/> element.
  _idle(self)
Same as Stream.idle but assume self.lock is acquired.
  _loop_iter(self, timeout)
Same as Stream.loop_iter but assume self.lock is acquired.
  _make_reader(self)
Create ne xmlextra.StreamReader instace as self._reader.
  _make_stream_features(self)
Create the <features/> element for the stream.
  _post_auth(self)
Called when connection is authenticated.
  _post_connect(self)
Called when connection is established.
  _process(self)
Same as Stream.process but assume self.lock is acquired.
  _process_node(self, xmlnode)
Process first level element of the stream.
  _process_stream_node(self, xmlnode)
Process first level stream-namespaced element of the stream.
  _read(self)
Read data pending on the stream socket and pass it to the parser.
  _reset(self)
Reset Stream object state making it ready to handle new connections.
  _restart_stream(self)
Restart the stream as needed after SASL and StartTLS negotiation.
  _send(self, stanza)
Same as Stream.send but assume self.lock is acquired.
  _send_stream_end(self)
Send stream end tag.
  _send_stream_error(self, condition)
Send stream error element.
  _send_stream_features(self)
Send stream <features/>.
  _send_stream_start(self, sid)
Send stream start tag.
  _write_node(self, xmlnode)
Write XML xmlnode to the stream.
  _write_raw(self, data)
Same as Stream.write_raw but assume self.lock is acquired.
    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.
  _set_response_handlers(self, iq, res_handler, err_handler, timeout_handler, timeout)
Same as Stream.set_response_handlers but assume self.lock is acquired.
    Inherited from StreamHandler
  _stanza(self, _doc, _node)
Process complete stanza.
  _stream_end(self, _doc)
Process stream end.
  _stream_start(self, _doc)
Process stream start.

Instance Variable Summary
  features: stream features as annouced by the initiator.
  initiator: True if local stream endpoint is the initiating entity.
  lock: RLock object used to synchronize access to Stream object.
  me: local stream endpoint JID.
  peer: remote stream endpoint JID.
  process_all_stanzas: when True then all stanzas received are considered local.
  _reader: the stream reader object (push parser) for the stream.

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]

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

Parameters:
resource - the resource name to bind to.

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.
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.
Returns:
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.
Returns:
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.
Parameters:
err - error received
           (type=StreamErrorNode)

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

_accept(self, sock, myname)

Same as Stream.accept but assume self.lock is acquired.

_bind_error(self, stanza)

Handle resource binding success.

[initiating entity only]

Raises:
FatalStreamError -

_bind_success(self, stanza)

Handle resource binding success.

[initiating entity only]

Set self.me to the full JID negotiated.

Parameters:
stanza - <iq type="result"/> stanza received.

_close(self)

Same as Stream.close but assume self.lock is acquired.

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

Same as Stream.connect but assume self.lock is acquired.

_connect_socket(self, sock, to=None)

Initialize stream on outgoing connection.
Parameters:
sock - connected socket for the stream
to - name of the remote host

_disconnect(self)

Same as Stream.disconnect but assume self.lock is acquired.

_feed_reader(self, data)

Feed the stream reader with data received.

If data is None or empty, then stream end (peer disconnected) is assumed and the stream is closed.

Parameters:
data - data received from the stream socket.
           (type=unicode)

_got_features(self)

Process incoming <stream:features/> element.

[initiating entity only]

The received features node is available in self.features.

_idle(self)

Same as Stream.idle but assume self.lock is acquired.

_loop_iter(self, timeout)

Same as Stream.loop_iter but assume self.lock is acquired.

_make_reader(self)

Create ne xmlextra.StreamReader instace as self._reader.

_make_stream_features(self)

Create the <features/> element for the stream.

[receving entity only]

Returns:
new <features/> element node.

_post_auth(self)

Called when connection is authenticated.

This method is supposed to be overriden in derived classes.

_post_connect(self)

Called when connection is established.

This method is supposed to be overriden in derived classes.

_process(self)

Same as Stream.process but assume self.lock is acquired.

_process_node(self, xmlnode)

Process first level element of the stream.

The element may be stream error or features, StartTLS request/response, SASL request/response or a stanza.

Parameters:
xmlnode - XML node describing the element

_process_stream_node(self, xmlnode)

Process first level stream-namespaced element of the stream.

The element may be stream error or stream features.

Parameters:
xmlnode - XML node describing the element

_read(self)

Read data pending on the stream socket and pass it to the parser.

_reset(self)

Reset Stream object state making it ready to handle new connections.

_restart_stream(self)

Restart the stream as needed after SASL and StartTLS negotiation.

_send(self, stanza)

Same as Stream.send but assume self.lock is acquired.

_send_stream_end(self)

Send stream end tag.

_send_stream_error(self, condition)

Send stream error element.
Parameters:
condition - stream error condition name, as defined in the XMPP specification.

_send_stream_features(self)

Send stream <features/>.

[receiving entity only]

_send_stream_start(self, sid=None)

Send stream start tag.

_write_node(self, xmlnode)

Write XML xmlnode to the stream.
Parameters:
xmlnode - XML node to send.

_write_raw(self, data)

Same as Stream.write_raw but assume self.lock is acquired.

Instance Variable Details

features

stream features as annouced by the initiator.

initiator

True if local stream endpoint is the initiating entity.

lock

RLock object used to synchronize access to Stream object.

me

local stream endpoint JID.

peer

remote stream endpoint JID.

process_all_stanzas

when True then all stanzas received are considered local.

_reader

the stream reader object (push parser) for the stream.