Package pyxmpp :: Module clientstream :: Class ClientStream
[show private | hide private]
[frames | no frames]

Class ClientStream

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

Known Subclasses:
LegacyClientStream

Handles XMPP-IM client connection stream.

Both client and server side of the connection is supported. This class handles
client SASL authentication, authorisation and resource binding.

This class is not ready for handling of legacy Jabber servers, as it doesn't
provide legacy authentication.

:Ivariables:
    - `my_jid`: requested local JID. Please notice that this may differ from
      `me`, which is actual authorized JID after the resource binding.
    - `server`: server to use.
    - `port`: port number to use.
    - `password`: user's password.
    - `auth_methods`: allowed authentication methods.
:Types:
    - `my_jid`: `pyxmpp.JID`
    - `server`: `str`
    - `port`: `int`
    - `password`: `str`
    - `auth_methods`: `list` of `str`

Method Summary
  __init__(self, jid, password, server, port, auth_methods, tls_settings, keepalive)
Initialize the ClientStream object.
  accept(self, sock)
Accept an incoming client connection.
  check_authzid(self, authzid, extra_info)
Check authorization id provided by the client.
  choose_realm(self, realm_list)
Choose authentication realm from the list provided by the server.
  connect(self, server, port)
Establish a client connection to a server.
  do_bind(self, stanza)
Do the resource binding requested by a client connected.
  fix_in_stanza(self, stanza)
Fix an incoming stanza.
  fix_out_stanza(self, stanza)
Fix outgoing stanza.
  get_password(self, username, realm, acceptable_formats)
Get a user password for the SASL authentication.
  get_realms(self)
Get realms available for client authentication.
  get_serv_host(self)
Get the service host name for SASL authentication.
  get_serv_name(self)
Get the service name for SASL authentication.
  get_serv_type(self)
Get the server name for SASL authentication.
  _connect(self, server, port)
Same as `ClientStream.connect` but assume `self.lock` is acquired.
  _get_stream_features(self)
Include resource binding feature in the stream features list.
  _post_connect(self)
Initialize authentication when the connection is established and we are the initiator.
  _reset(self)
Reset `ClientStream` object state, making the object ready to handle new connections.
  _try_auth(self)
Try to authenticate using the first one of allowed authentication methods left.
    Inherited from Stream
  _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.
    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/>.
  _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.
  _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.
  _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
  check_password(self, username, password, realm)
Check the password validity.
  generate_nonce(self)
Generate a random string for digest authentication challenges.
    Inherited from StreamBase
  __del__(self)
  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.
  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_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.
  _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
  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.

Method Details

__init__(self, jid, password=None, server=None, port=None, auth_methods=('sasl:DIGEST-MD5',), tls_settings=None, keepalive=0)
(Constructor)

Initialize the ClientStream object.

:Parameters:
    - `jid`: local JID.
    - `password`: user's password.
    - `server`: server to use. If not given then address will be derived form the JID.
    - `port`: port number to use. If not given then address will be derived form the JID.
    - `auth_methods`: sallowed authentication methods. SASL authentication mechanisms
      in the list should be prefixed with "sasl:" string.
    - `tls_settings`: settings for StartTLS -- `TLSSettings` instance.
    - `keepalive`: keepalive output interval. 0 to disable.
:Types:
    - `jid`: `pyxmpp.JID`
    - `password`: `unicode`
    - `server`: `unicode`
    - `port`: `int`
    - `auth_methods`: sequence of `str`
    - `tls_settings`: `pyxmpp.TLSSettings`
    - `keepalive`: `int`
Overrides:
pyxmpp.stream.Stream.__init__

accept(self, sock)

Accept an incoming client connection.

[server only]

:Parameters:
    - `sock`: a listening socket.
Overrides:
pyxmpp.streambase.StreamBase.accept

check_authzid(self, authzid, extra_info=None)

Check authorization id provided by the client.

[server only]

:Parameters:
    - `authzid`: authorization id provided.
    - `extra_info`: additional information about the user
      from the authentication backend. This mapping will
      usually contain at least 'username' item.
:Types:
    - `authzid`: unicode
    - `extra_info`: mapping

:return: `True` if user is authorized to use that `authzid`.
:returntype: `bool`
Overrides:
pyxmpp.sasl.core.PasswordManager.check_authzid

choose_realm(self, realm_list)

Choose authentication realm from the list provided by the server.

[client only]

Use domain of the own JID if no realm list was provided or the domain is on the list
or the first realm on the list otherwise.

:Parameters:
    - `realm_list`: realm list provided by the server.
:Types:
    - `realm_list`: `list` of `unicode`

:return: the realm chosen.
:returntype: `unicode`
Overrides:
pyxmpp.sasl.core.PasswordManager.choose_realm

connect(self, server=None, port=None)

Establish a client connection to a server.

[client only]

:Parameters:
    - `server`: name or address of the server to use. Not recommended -- proper value
      should be derived automatically from the JID.
    - `port`: port number of the server to use. Not recommended --
      proper value should be derived automatically from the JID.

:Types:
    - `server`: `unicode`
    - `port`: `int`
Overrides:
pyxmpp.streambase.StreamBase.connect

do_bind(self, stanza)

Do the resource binding requested by a client connected.

[server only]

:Parameters:
    - `stanza`: resource binding request stanza.
:Types:
    - `stanza`: `pyxmpp.Iq`

fix_in_stanza(self, stanza)

Fix an incoming stanza.

Ona server replace the sender address with authorized client JID.
Overrides:
pyxmpp.stanzaprocessor.StanzaProcessor.fix_in_stanza

fix_out_stanza(self, stanza)

Fix outgoing stanza.

On a client clear the sender JID. On a server set the sender
address to the own JID if the address is not set yet.
Overrides:
pyxmpp.stanzaprocessor.StanzaProcessor.fix_out_stanza

get_password(self, username, realm=None, acceptable_formats=('plain',))

Get a user password for the SASL authentication.

:Parameters:
    - `username`: username used for authentication.
    - `realm`: realm used for authentication.
    - `acceptable_formats`: acceptable password encoding formats requested.
:Types:
    - `username`: `unicode`
    - `realm`: `unicode`
    - `acceptable_formats`: `list` of `str`

:return: The password and the format name ('plain').
:returntype: (`unicode`,`str`)
Overrides:
pyxmpp.sasl.core.PasswordManager.get_password

get_realms(self)

Get realms available for client authentication.

[server only]

:return: list of realms.
:returntype: `list` of `unicode`
Overrides:
pyxmpp.sasl.core.PasswordManager.get_realms

get_serv_host(self)

Get the service host name for SASL authentication.

:return: domain of the own JID.
Overrides:
pyxmpp.sasl.core.PasswordManager.get_serv_host

get_serv_name(self)

Get the service name for SASL authentication.

:return: domain of the own JID.
Overrides:
pyxmpp.sasl.core.PasswordManager.get_serv_name

get_serv_type(self)

Get the server name for SASL authentication.

:return: 'xmpp'.
Overrides:
pyxmpp.sasl.core.PasswordManager.get_serv_type

_connect(self, server=None, port=None)

Same as `ClientStream.connect` but assume `self.lock` is acquired.
Overrides:
pyxmpp.streambase.StreamBase._connect

_get_stream_features(self)

Include resource binding feature in the stream features list.

[server only]

_post_connect(self)

Initialize authentication when the connection is established
and we are the initiator.
Overrides:
pyxmpp.streambase.StreamBase._post_connect

_reset(self)

Reset `ClientStream` object state, making the object ready to handle
new connections.
Overrides:
pyxmpp.stream.Stream._reset

_try_auth(self)

Try to authenticate using the first one of allowed authentication
methods left.

[client only]

Generated by Epydoc 2.1 on Wed May 31 22:37:04 2006 http://epydoc.sf.net