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` (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.