Package pyxmpp2 :: Module streambase :: Class StreamBase

Class StreamBase

Base class for a generic XMPP stream.

Responsible for establishing connection, parsing the stream, handling stream elements and passing stanzas receiver to other object. 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, stanza_namespace, stanza_route, handlers, settings=None)
Initialize StreamBase object

initiate(self, transport, to=None)
Initiate an XMPP connection over the transport.

_initiate(self)
Initiate an XMPP connection over a connected transport.

receive(self, transport, myname)
Receive an XMPP connection over the transport.

_setup_stream_element_handlers(self)
Set up stream element handlers.

disconnect(self)
Gracefully close the connection.

event(self, event)
Handle a stream event.

transport_connected(self)
Called when transport has been connected.

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

stream_start(self, element)
Process <stream:stream> (stream start) tag received from peer.

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

stream_eof(self)
Process stream EOF.

stream_element(self, element)
Process first level child element of the stream).

stream_parse_error(self, descr)
Called when an error is encountered in the stream.

_send_stream_start(self, stream_id=None, stream_to=None)
Send stream start tag.

send_stream_error(self, condition)
Send stream error element.

_send_stream_error(self, condition)
Same as send_stream_error, but expects lock acquired.

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

ElementTree.Element

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

_send_stream_features(self)
Send stream <features/>.

write_element(self, element)
Write XML element to the stream.

_write_element(self, element)
Same as write_element but with lock already acquired.

send(self, stanza)
Write stanza to the stream.

_send(self, stanza)
Same as send but assume lock is acquired.

_process_element(self, element)
Process first level element of the stream.

uplink_receive(self, stanza)
Handle stanza received from the stream.

process_stream_error(self, error)
Process stream error element received.

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

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

_got_features(self, features)
Process incoming <stream:features/> element.

is_connected(self)
Check if stream is is_connected and stanzas may be sent.

set_peer_authenticated(self, peer, restart_stream=False)
Mark the other side of the stream authenticated as peer

set_authenticated(self, me, restart_stream=False)
Mark stream authenticated as me.

fix_in_stanza(self, stanza)
Fix incoming stanza, setting the implicit fields.

fix_out_stanza(self, stanza)
Fix outgoing, setting or clearing the implicit fields.

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Instance Variables

[hide private]

dict _element_handlers
mapping from stream element names to lists of methods handling them

unicode _input_state
None, "open" (<stream:stream> has been received) "restart" or "closed" (</stream:stream> or EOF has been received)

unicode _output_state
None, "open" (<stream:stream> has been received) "restart" or "closed" (</stream:stream> or EOF has been received)

unicode _stanza_namespace_p
qname prefix of the stanza namespace

list of StreamFeatureHandler _stream_feature_handlers
stream features handlers

bool authenticated
True if local entity has authenticated to peer

ElementTree.Element features
stream features as annouced by the receiver.

list handlers
handlers for stream elements

bool initiator
True if local stream endpoint is the initiating entity.

threading.RLock lock
RLock object used to synchronize access to Stream object.

JID me
local stream endpoint JID.

JID peer
remote stream endpoint JID.

bool peer_authenticated
True if the peer has authenticated to us

unicode peer_language
language of human-readable stream content selected by the peer

XMPPSettings settings
stream settings

unicode stanza_namespace
default namespace of the stream

bool tls_established
True when the stream is protected by TLS

transport.XMPPTransport transport
transport used by this stream

(int, int) tuple version
Negotiated version of the XMPP protocol.

Properties

[hide private]

Inherited from object: __class__

Method Details

[hide private]

init(self, stanza_namespace, stanza_route, handlers, settings=None)
(Constructor)

Initialize StreamBase object

Parameters:

stanza_namespace (unicode) - stream's default namespace URI ("jabber:client" for client, "jabber:server" for server, etc.)
stanza_route (StanzaRoute) - object to handle received stanzas
handlers (list of objects) - objects to handle the stream events and elements
settings (XMPPSettings) - extra settings

Overrides: object.__init__

initiate(self, transport, to=None)

Initiate an XMPP connection over the transport.

Parameters:

transport - an XMPP transport instance
to - peer name

_initiate(self)

Initiate an XMPP connection over a connected transport.

[ called with lock acquired ]

receive(self, transport, myname)

Receive an XMPP connection over the transport.

Parameters:

transport - an XMPP transport instance
myname - local stream endpoint name.

_setup_stream_element_handlers(self)

Set up stream element handlers.

Scans the handlers list for StreamFeatureHandler instances and updates _element_handlers mapping with their methods decorated with @`stream_element_handler`

event(self, event)

Handle a stream event.

Called when connection state is changed.

Should not be called with self.lock acquired!

transport_connected(self)

Called when transport has been connected.

Send the stream head if initiator.

stream_start(self, element)

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

lock is acquired when this method is called.

Parameters:

element - root element (empty) created by the parser

Overrides: xmppparser.XMLStreamHandler.stream_start

stream_end(self)

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

Overrides: xmppparser.XMLStreamHandler.stream_end

stream_eof(self)

Process stream EOF.

Overrides: xmppparser.XMLStreamHandler.stream_eof

stream_element(self, element)

Process first level child element of the stream).

Parameters:

element (ElementTree.Element) - XML element received

Overrides: xmppparser.XMLStreamHandler.stream_element

stream_parse_error(self, descr)

Called when an error is encountered in the stream.

Parameters:

descr (unicode) - description of the error

Overrides: xmppparser.XMLStreamHandler.stream_parse_error

send_stream_error(self, condition)

Send stream error element.

Parameters:

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

_make_stream_features(self)

Create the <features/> element for the stream.

[receving entity only]

Returns: ElementTree.Element: new <features/> element

_send_stream_features(self)

Send stream <features/>.

[receiving entity only]

write_element(self, element)

Write XML element to the stream.

Parameters:

element (ElementTree.Element) - Element node to send.

send(self, stanza)

Write stanza to the stream.

Parameters:

stanza (pyxmpp2.stanza.Stanza) - XMPP stanza to send.

_process_element(self, element)

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:

element (ElementTree.Element) - XML element

process_stream_error(self, error)

Process stream error element received.

Parameters:

error (StreamErrorElement) - error received

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 me, None otherwise.

generate_id(self)

Generate a random and unique stream ID.

Returns:: the id string generated.

_got_features(self, features)

Process incoming <stream:features/> element.

[initiating entity only]

The received features node is available in features.

is_connected(self)

Check if stream is is_connected and stanzas may be sent.

Returns:: True if stream connection is active.

set_peer_authenticated(self, peer, restart_stream=False)

Mark the other side of the stream authenticated as peer

Parameters:

peer (JID) - local JID just authenticated
restart_stream (bool) - True when stream should be restarted (needed after SASL authentication)

set_authenticated(self, me, restart_stream=False)

Mark stream authenticated as me.

Parameters:

me (JID) - local JID just authenticated
restart_stream (bool) - True when stream should be restarted (needed after SASL authentication)

fix_in_stanza(self, stanza)

Fix incoming stanza, setting the implicit fields.

Used for for servers side of client stream to set proper stanza from.

fix_out_stanza(self, stanza)

Fix outgoing, setting or clearing the implicit fields.

Used for for client side of client stream to clear the 'from' attribute.

Instance Variable Details

[hide private]

version

Negotiated version of the XMPP protocol. (0,9) for the legacy (pre-XMPP) Jabber protocol.

Type:: (int, int) tuple

Class StreamBase

__init__(self, stanza_namespace, stanza_route, handlers, settings=None) (Constructor)

initiate(self, transport, to=None)

_initiate(self)

receive(self, transport, myname)

_setup_stream_element_handlers(self)

event(self, event)

transport_connected(self)

stream_start(self, element)

stream_end(self)

stream_eof(self)

stream_element(self, element)

stream_parse_error(self, descr)

send_stream_error(self, condition)

_make_stream_features(self)

_send_stream_features(self)

write_element(self, element)

send(self, stanza)

_process_element(self, element)

process_stream_error(self, error)

check_to(self, to)

generate_id(self)

_got_features(self, features)

is_connected(self)

set_peer_authenticated(self, peer, restart_stream=False)

set_authenticated(self, me, restart_stream=False)

fix_in_stanza(self, stanza)

fix_out_stanza(self, stanza)

version

init(self, stanza_namespace, stanza_route, handlers, settings=None)
(Constructor)