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

Class StreamBase

source code

stanzaprocessor.StanzaProcessor --+
                                  |
         xmlextra.StreamHandler --+
                                  |
                                 StreamBase
Known Subclasses:

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 xmlextra.StreamHandler: warning

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:

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:

connected(self)

source code 
Check if stream is connected.
Returns:
True if stream connection is active.