Package pyxmpp2 :: Module streambase :: Class StreamBase
[hide private]

Class StreamBase


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.

Nested Classes [hide private]

Inherited from mainloop.interfaces.TimeoutHandler: __metaclass__

Instance Methods [hide private]
 
__init__(self, stanza_namespace, 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.
int
regular_tasks(self)
Do some housekeeping (cache expiration, timeout handling).
 
_process_element(self, element)
Process first level element of 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.

Inherited from stanzaprocessor.StanzaProcessor: fix_in_stanza, fix_out_stanza, process_iq, process_message, process_presence, process_stanza, route_stanza, set_response_handlers, setup_stanza_handlers

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

Class Variables [hide private]

Inherited from mainloop.interfaces.TimeoutHandler: __abstractmethods__

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 and stanza payload
bool initiator
True if local stream endpoint is the initiating entity.
threading.RLock lock
lock object used to synchronize access to the StanzaProcessor object.
JID me
local 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
bool process_all_stanzas
when True then all stanzas received are considered local.
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, 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.)
  • 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 - stanza's full XML
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:

send(self, stanza)

 
Write stanza to the stream.
Parameters:
Overrides: stanzaprocessor.StanzaProcessor.send

regular_tasks(self)

 

Do some housekeeping (cache expiration, timeout handling).

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

Returns: int
suggested delay (in seconds) before the next call to this method.
Decorators:
  • @timeout_handler(1)

_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:

process_stream_error(self, error)

 
Process stream error element received.
Parameters:

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

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)

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