pyxmpp.stream.Stream

Package pyxmpp :: Module stream :: Class Stream |
[show private | hide private]
[frames | no frames]

## Class Stream

    StanzaProcessor --+
                      |
      StreamHandler --+
                      |
             StreamBase --+
                          |
    PasswordManager --+   |
                      |   |
        StreamSASLMixIn --+
                          |
         StreamTLSMixIn --+
                          |
                         Stream

Known Subclasses:
  `ClientStream`, `ComponentStream`

Generic XMPP stream class.

Responsible for establishing connection, parsing the stream, StartTLS encryption and SASL authentication negotiation and usage, dispatching received stanzas to apopriate handlers and sending application's stanzas.

Whenever we say "stream" here we actually mean two streams (incoming and outgoing) of one connections, as defined by the XMPP specification.

Method Summary
| ``__init__`(self, default_ns, extra_ns, sasl_mechanisms, tls_settings, keepalive)` Initialize Stream object
| ``_got_features`(self)` Process incoming <stream:features/> element.
| ``_make_stream_features`(self)` Create the <features/> element for the stream.
| ``_process_node`(self, xmlnode)` Process first level element of the stream.
| ``_reset`(self)` Reset `Stream` object state making it ready to handle new connections.
Inherited from StreamTLSMixIn
| ``get_tls_connection`(self)` Get the TLS connection object for the stream.
| ``_handle_tls_features`(self)` Process incoming StartTLS related element of <stream:features/>.
`libxml2.xmlNode` | ``_make_stream_tls_features`(self, features)` Update the <features/> with StartTLS feature.
| ``_make_tls_connection`(self)` Initiate TLS connection.
| ``_process`(self)` Same as `Stream.process` but assume `self.lock` is acquired.
`bool` | ``_process_node_tls`(self, xmlnode)` Process incoming stream element.
| ``_process_tls_node`(self, xmlnode)` Process stream element in the TLS namespace.
| ``_read`(self)` Read data pending on the stream socket and pass it to the parser.
| ``_read_tls`(self)` Read data pending on the stream socket and pass it to the parser.
| ``_request_tls`(self)` Request a TLS-encrypted connection.
| ``_reset_tls`(self)` Reset `StreamTLSMixIn` object state making it ready to handle new connections.
| ``_tls_verify_callback`(self, ssl_ctx_ptr, x509_ptr, errnum, depth, ok)` Certificate verification callback for TLS connections.
| ``_write_raw`(self, data)` Same as `Stream.write_raw` but assume `self.lock` is acquired.
Inherited from StreamSASLMixIn
| ``_handle_sasl_features`(self)` Process incoming <stream:features/> element.
| ``_make_stream_sasl_features`(self, features)` Add SASL features to the <features/> element of the stream.
`bool` | ``_process_node_sasl`(self, xmlnode)` Process incoming stream element.
| ``_process_sasl_abort`(self)` Process incoming <sasl:abort/> element.
| ``_process_sasl_auth`(self, mechanism, content)` Process incoming <sasl:auth/> element.
| ``_process_sasl_challenge`(self, content)` Process incoming <sasl:challenge/> element.
| ``_process_sasl_failure`(self, xmlnode)` Process incoming <sasl:failure/> element.
| ``_process_sasl_node`(self, xmlnode)` Process stream element in the SASL namespace.
| ``_process_sasl_response`(self, content)` Process incoming <sasl:response/> element.
| ``_process_sasl_success`(self, content)` Process incoming <sasl:success/> element.
| ``_reset_sasl`(self)` Reset `StreamSASLMixIn` object state making it ready to handle new connections.
| ``_sasl_authenticate`(self, username, authzid, mechanism)` Start SASL authentication process.
Inherited from PasswordManager
`bool` | ``check_authzid`(self, authzid, extra_info)` Check if the authenticated entity is allowed to use given authorization id.
`bool` | ``check_password`(self, username, password, realm)` Check the password validity.
`unicode` | ``choose_realm`(self, realm_list)` Choose an authentication realm from the list provided by the server.
`str` | ``generate_nonce`(self)` Generate a random string for digest authentication challenges.
`unicode`,`str` tuple. | ``get_password`(self, username, realm, acceptable_formats)` Get the password for user authentication.
`list` of `unicode` | ``get_realms`(self)` Get available realms list.
| ``get_serv_host`(self)` Return the host name for DIGEST-MD5 'digest-uri' field.
| ``get_serv_name`(self)` Return the service name for DIGEST-MD5 'digest-uri' field.
| ``get_serv_type`(self)` Return the service type for DIGEST-MD5 'digest-uri' field.
Inherited from StreamBase
| ``__del__`(self)`
| ``accept`(self, sock, myname)` Accept incoming connection.
| ``bind`(self, resource)` Bind to a resource.
| ``check_to`(self, to)` Check "to" attribute of received stream header.
| ``close`(self)` Forcibly close the connection and clear the stream state.
| ``connect`(self, addr, port, service, to)` Establish XMPP connection with given address.
| ``connected`(self)` Check if stream is connected.
| ``disconnect`(self)` Gracefully close the connection.
| ``error`(self, descr)` Handle stream XML parse error.
| ``fileno`(self)` Return filedescriptor of the stream socket.
| ``generate_id`(self)` Generate a random and unique stream ID.
| ``idle`(self)` Do some housekeeping (cache expiration, timeout handling).
| ``loop`(self, timeout)` Simple "main loop" for the stream.
| ``loop_iter`(self, timeout)` Single iteration of a simple "main loop" for the stream.
| ``process`(self)` Process stream's pending events.
| ``process_stream_error`(self, err)` Process stream error element received.
| ``send`(self, stanza)` Write stanza to the stream.
| ``stanza`(self, _unused, node)` Process stanza (first level child element of the stream).
| ``stanza_start`(self, doc, node)` Process stanza (first level child element of the stream) start tag -- do nothing.
| ``state_change`(self, state, arg)` Called when connection state is changed.
| ``stream_end`(self, _unused)` Process </stream:stream> (stream end) tag received from peer.
| ``stream_start`(self, doc)` Process <stream:stream> (stream start) tag received from peer.
| ``write_raw`(self, data)` Write raw data to the stream socket.
| ``_accept`(self, sock, myname)` Same as `Stream.accept` but assume `self.lock` is acquired.
| ``_bind_error`(self, stanza)` Handle resource binding success.
| ``_bind_success`(self, stanza)` Handle resource binding success.
| ``_close`(self)` Same as `Stream.close` but assume `self.lock` is acquired.
| ``_connect`(self, addr, port, service, to)` Same as `Stream.connect` but assume `self.lock` is acquired.
| ``_connect_socket`(self, sock, to)` Initialize stream on outgoing connection.
| ``_disconnect`(self)` Same as `Stream.disconnect` but assume `self.lock` is acquired.
| ``_feed_reader`(self, data)` Feed the stream reader with data received.
| ``_idle`(self)` Same as `Stream.idle` but assume `self.lock` is acquired.
| ``_loop_iter`(self, timeout)` Same as `Stream.loop_iter` but assume `self.lock` is acquired.
| ``_make_reader`(self)` Create ne `xmlextra.StreamReader` instace as `self._reader`.
| ``_post_auth`(self)` Called when connection is authenticated.
| ``_post_connect`(self)` Called when connection is established.
| ``_process_stream_node`(self, xmlnode)` Process first level stream-namespaced element of the stream.
| ``_restart_stream`(self)` Restart the stream as needed after SASL and StartTLS negotiation.
| ``_send`(self, stanza)` Same as `Stream.send` but assume `self.lock` is acquired.
| ``_send_stream_end`(self)` Send stream end tag.
| ``_send_stream_error`(self, condition)` Send stream error element.
| ``_send_stream_features`(self)` Send stream <features/>.
| ``_send_stream_start`(self, sid)` Send stream start tag.
| ``_write_node`(self, xmlnode)` Write XML `xmlnode` to the stream.
Inherited from StanzaProcessor
| ``fix_in_stanza`(self, stanza)` Modify incoming stanza before processing it.
| ``fix_out_stanza`(self, stanza)` Modify outgoing stanza before sending into the stream.
| ``process_iq`(self, stanza)` Process IQ stanza received.
| ``process_message`(self, stanza)` Process message stanza.
| ``process_presence`(self, stanza)` Process presence stanza.
| ``process_stanza`(self, stanza)` Process stanza received from the stream.
| ``route_stanza`(self, stanza)` Process stanza not addressed to us.
| ``set_iq_get_handler`(self, element, namespace, handler)` Set <iq type="get"/> handler.
| ``set_iq_set_handler`(self, element, namespace, handler)` Set <iq type="set"/> handler.
| ``set_message_handler`(self, typ, handler, namespace, priority)` Set a handler for <message/> stanzas.
| ``set_presence_handler`(self, typ, handler, namespace, priority)` Set a handler for <presence/> stanzas.
| ``set_response_handlers`(self, iq, res_handler, err_handler, timeout_handler, timeout)` Set response handler for an IQ "get" or "set" stanza.
| ``unset_iq_get_handler`(self, element, namespace)` Remove <iq type="get"/> handler.
| ``unset_iq_set_handler`(self, element, namespace)` Remove <iq type="set"/> handler.
| ``_set_response_handlers`(self, iq, res_handler, err_handler, timeout_handler, timeout)` Same as `Stream.set_response_handlers` but assume `self.lock` is acquired.
Inherited from StreamHandler
| ``_stanza`(self, _doc, _node)` Process complete stanza.
| ``_stream_end`(self, _doc)` Process stream end.
| ``_stream_start`(self, _doc)` Process stream start.

Instance Variable Summary
| `features`: stream features as annouced by the initiator.
| `initiator`: `True` if local stream endpoint is the initiating entity.
| `lock`: RLock object used to synchronize access to Stream object.
| `me`: local stream endpoint JID.
| `peer`: remote stream endpoint JID.
| `process_all_stanzas`: when `True` then all stanzas received are considered local.
| `tls`: TLS connection object.
| `_reader`: the stream reader object (push parser) for the stream.

Method Details

### __init__(self, default_ns, extra_ns=(), sasl_mechanisms=(), tls_settings=None, keepalive=0) (Constructor) 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. `sasl_mechanisms` - sequence of SASL mechanisms allowed for authentication. Currently "PLAIN" and "DIGEST-MD5" are supported. `tls_settings` - settings for StartTLS -- `TLSSettings` instance. `keepalive` - keepalive output interval. 0 to disable. Overrides: `pyxmpp.streamtls.StreamTLSMixIn.__init__`

### _got_features(self) Process incoming <stream:features/> element. [initiating entity only] The received features node is available in `self.features`. Overrides: `pyxmpp.streambase.StreamBase._got_features`

### _make_stream_features(self) Create the <features/> element for the stream. [receving entity only] Returns: new <features/> element node. Overrides: `pyxmpp.streambase.StreamBase._make_stream_features`

### _process_node(self, xmlnode) 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 Overrides: `pyxmpp.streambase.StreamBase._process_node`

### _reset(self) Reset `Stream` object state making it ready to handle new connections. Overrides: `pyxmpp.streambase.StreamBase._reset`

Instance Variable Details

### features stream features as annouced by the initiator.

### initiator `True` if local stream endpoint is the initiating entity.

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

### me local stream endpoint JID.

### peer remote stream endpoint JID.

### process_all_stanzas when `True` then all stanzas received are considered local.

### tls TLS connection object.

### _reader the stream reader object (push parser) for the stream.