Package pyxmpp :: Module streambase :: Class StreamBase

[hide private]

# Class StreamBase

source code

    stanzaprocessor.StanzaProcessor --+
                                      |
             xmlextra.StreamHandler --+
                                      |
                                     StreamBase

Known Subclasses:
  - stream.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.

Instance Methods | [hide private]

__init__(self, default_ns, extra_ns=`(``)`, keepalive=0, owner=None) Initialize Stream object | source code

_reset(self) Reset Stream object state making it ready to handle new connections. | source code

__del__(self) | source code

_connect_socket(self, sock, to=None) Initialize stream on outgoing connection. | source code

connect(self, addr, port, service=None, to=None) Establish XMPP connection with given address. | source code

_connect(self, addr, port, service=None, to=None) Same as `Stream.connect` but assume self.lock is acquired. | source code

accept(self, sock, myname) Accept incoming connection. | source code

_accept(self, sock, myname) Same as `Stream.accept` but assume self.lock is acquired. | source code

disconnect(self) Gracefully close the connection. | source code

_disconnect(self) Same as `Stream.disconnect` but assume self.lock is acquired. | source code

_post_connect(self) Called when connection is established. | source code

_post_auth(self) Called when connection is authenticated. | source code

state_change(self, state, arg) Called when connection state is changed. | source code

close(self) Forcibly close the connection and clear the stream state. | source code

_close(self) Same as `Stream.close` but assume self.lock is acquired. | source code

_make_reader(self) Create ne xmlextra.StreamReader instace as self._reader. | source code

stream_start(self, doc) Process <stream:stream> (stream start) tag received from peer. | source code

stream_end(self, _unused) Process </stream:stream> (stream end) tag received from peer. | source code

stanza_start(self, doc, node) Process stanza (first level child element of the stream) start tag -- do nothing. | source code

stanza(self, _unused, node) Process stanza (first level child element of the stream). | source code

error(self, descr) Handle stream XML parse error. | source code

_send_stream_end(self) Send stream end tag. | source code

_send_stream_start(self, sid=None) Send stream start tag. | source code

_send_stream_error(self, condition) Send stream error element. | source code

_restart_stream(self) Restart the stream as needed after SASL and StartTLS negotiation. | source code

_make_stream_features(self) Create the <features/> element for the stream. | source code

_send_stream_features(self) Send stream <features/>. | source code

write_raw(self, data) Write raw data to the stream socket. | source code

_write_raw(self, data) Same as `Stream.write_raw` but assume self.lock is acquired. | source code

_write_node(self, xmlnode) Write XML `xmlnode` to the stream. | source code

send(self, stanza) Write stanza to the stream. | source code

_send(self, stanza) Same as `Stream.send` but assume self.lock is acquired. | source code

idle(self) Do some housekeeping (cache expiration, timeout handling). | source code

_idle(self) Same as `Stream.idle` but assume self.lock is acquired. | source code

fileno(self) Return filedescriptor of the stream socket. | source code

loop(self, timeout) Simple "main loop" for the stream. | source code

loop_iter(self, timeout) Single iteration of a simple "main loop" for the stream. | source code

_loop_iter(self, timeout) Same as `Stream.loop_iter` but assume self.lock is acquired. | source code

process(self) Process stream's pending events. | source code

_process(self) Same as `Stream.process` but assume self.lock is acquired. | source code

_read(self) Read data pending on the stream socket and pass it to the parser. | source code

_feed_reader(self, data) Feed the stream reader with data received. | source code

_process_node(self, xmlnode) Process first level element of the stream. | source code

_process_stream_node(self, xmlnode) Process first level stream-namespaced element of the stream. | source code

process_stream_error(self, err) Process stream error element received. | source code

check_to(self, to) Check "to" attribute of received stream header. | source code

generate_id(self) Generate a random and unique stream ID. | source code

_got_features(self) Process incoming <stream:features/> element. | source code

bind(self, resource) Bind to a resource. | source code

_bind_success(self, stanza) Handle resource binding success. | source code

_bind_error(self, stanza) Handle resource binding success. | source code

connected(self) Check if stream is connected. | source code

Inherited from `stanzaprocessor.StanzaProcessor`: `fix_in_stanza`, `fix_out_stanza`, `process_iq`, `process_message`, `process_presence`, `process_response`, `process_stanza`, `route_stanza`, `set_iq_get_handler`, `set_iq_set_handler`, `set_message_handler`, `set_presence_handler`, `set_response_handlers`, `unset_iq_get_handler`, `unset_iq_set_handler`

Inherited from `stanzaprocessor.StanzaProcessor` (private): `_set_response_handlers`

Inherited from `xmlextra.StreamHandler`: `warning`

Inherited from `xmlextra.StreamHandler` (private): `_stanza`, `_stream_end`, `_stream_start`

Instance Variables | [hide private]

| _reader : the stream reader object (push parser) for the stream.
| features : stream features as annouced by the initiator.
| initiator : `True` if local stream endpoint is the initiating entity.
| lock : lock object used to synchronize access to the StanzaProcessor object.
| me : local JID.
| owner : Client, Component or similar object "owning" this stream.
| peer : remote stream endpoint JID.
| process_all_stanzas : when `True` then all stanzas received are considered local.

Method Details | [hide private]

### __init__(self, default_ns, extra_ns=`(``)`, keepalive=0, owner=None)
(Constructor)

source code

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.
  - `owner` - : Client, Component or similar object "owning" this stream.
Overrides: xmlextra.StreamHandler.__init__

### _connect_socket(self, sock, to=None)

source code

Initialize stream on outgoing connection.

Parameters:
  - `sock` - : connected socket for the stream
  - `to` - : name of the remote host

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

source code

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`

### accept(self, sock, myname)

source code

Accept incoming connection.

[receiving entity only]

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

### _post_connect(self)

source code

Called when connection is established.

This method is supposed to be overriden in derived classes.

### _post_auth(self)

source code

Called when connection is authenticated.

This method is supposed to be overriden in derived classes.

### state_change(self, state, arg)

source code

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_start(self, doc)

source code

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

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

### stream_end(self, _unused)

source code

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

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

### stanza_start(self, doc, node)

source code

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

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

### stanza(self, _unused, node)

source code

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

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

### error(self, descr)

source code

Handle stream XML parse error.

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

### _send_stream_error(self, condition)

source code

Send stream error element.

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

### _make_stream_features(self)

source code

Create the <features/> element for the stream.

[receving entity only]

Returns:
  new <features/> element node.

### _send_stream_features(self)

source code

Send stream <features/>.

[receiving entity only]

### write_raw(self, data)

source code

Write raw data to the stream socket.

Parameters:
  - `data` - : data to send

### _write_node(self, xmlnode)

source code

Write XML `xmlnode` to the stream.

Parameters:
  - `xmlnode` - : XML node to send.

### send(self, stanza)

source code

Write stanza to the stream.

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

### idle(self)

source code

Do some housekeeping (cache expiration, timeout handling).

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

### process(self)

source code

Process stream's pending events.

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

### _feed_reader(self, data)

source code

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` (: `unicode`) - : data received from the stream socket.

### _process_node(self, xmlnode)

source code

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)

source code

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

### process_stream_error(self, err)

source code

Process stream error element received.

Parameters:
  - `err` (: StreamErrorNode) - : error received

### check_to(self, to)

source code

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

### generate_id(self)

source code

Generate a random and unique stream ID.

Returns:
  the id string generated.

### _got_features(self)

source code

Process incoming <stream:features/> element.

[initiating entity only]

The received features node is available in self.features.

### bind(self, resource)

source code

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.

### _bind_success(self, stanza)

source code

Handle resource binding success.

[initiating entity only]

Set self.me to the full JID negotiated.

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

### _bind_error(self, stanza)

source code

Handle resource binding success.

[initiating entity only]

Raises:
  - `FatalStreamError`

### connected(self)

source code

Check if stream is connected.

Returns:
  True if stream connection is active.