pyxmpp.stream

Package pyxmpp :: Module stream |
[hide private]

# Source Code for Module pyxmpp.stream

      1  #
      2  # (C) Copyright 2003-2010 Jacek Konieczny <jajcus@jajcus.net>
      3  #
      4  # This program is free software; you can redistribute it and/or modify
      5  # it under the terms of the GNU Lesser General Public License Version
      6  # 2.1 as published by the Free Software Foundation.
      7  #
      8  # This program is distributed in the hope that it will be useful,
      9  # but WITHOUT ANY WARRANTY; without even the implied warranty of
     10  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     11  # GNU Lesser General Public License for more details.
     12  #
     13  # You should have received a copy of the GNU Lesser General Public
     14  # License along with this program; if not, write to the Free Software
     15  # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
     16  #
     17
     18  """Generic XMPP stream implementation.
     19
     20  Normative reference:
     21    - `RFC 3920 <http://www.ietf.org/rfc/rfc3920.txt>`__
     22  """
     23
     24  __revision__="$Id: stream.py 714 2010-04-05 10:20:10Z jajcus $"
     25  __docformat__="restructuredtext en"
     26
     27  import logging
     28
     29  from pyxmpp.streambase import StreamBase
     30  from pyxmpp.streamtls import StreamTLSMixIn
     31  from pyxmpp.streamsasl import StreamSASLMixIn
     32
     33 -class Stream(StreamTLSMixIn,StreamSASLMixIn,StreamBase):
     34      """Generic XMPP stream class.
     35
     36      Responsible for establishing connection, parsing the stream,
     37      StartTLS encryption and SASL authentication negotiation
     38      and usage, dispatching received stanzas to apopriate handlers
     39      and sending application's stanzas.
     40
     41      Whenever we say "stream" here we actually mean two streams
     42      (incoming and outgoing) of one connections, as defined by the XMPP
     43      specification.
     44
     45      :Ivariables:
     46          - `lock`: RLock object used to synchronize access to Stream object.
     47          - `features`: stream features as annouced by the initiator.
     48          - `me`: local stream endpoint JID.
     49          - `peer`: remote stream endpoint JID.
     50          - `process_all_stanzas`: when `True` then all stanzas received are
     51            considered local.
     52          - `tls`: TLS connection object.
     53          - `initiator`: `True` if local stream endpoint is the initiating entity.
     54          - `_reader`: the stream reader object (push parser) for the stream.
     55      """
     56 -    def __init__(self, default_ns, extra_ns = (), sasl_mechanisms = (),
     57                      tls_settings = None, keepalive = 0, owner = None):
     58          """Initialize Stream object
     59
     60          :Parameters:
     61            - `default_ns`: stream's default namespace ("jabber:client" for
     62              client, "jabber:server" for server, etc.)
     63            - `extra_ns`: sequence of extra namespace URIs to be defined for
     64              the stream.
     65            - `sasl_mechanisms`: sequence of SASL mechanisms allowed for
     66              authentication. Currently "PLAIN", "DIGEST-MD5" and "GSSAPI" are supported.
     67            - `tls_settings`: settings for StartTLS -- `TLSSettings` instance.
     68            - `keepalive`: keepalive output interval. 0 to disable.
     69            - `owner`: `Client`, `Component` or similar object "owning" this stream.
     70          """
     71          StreamBase.__init__(self, default_ns, extra_ns, keepalive, owner)
     72          StreamTLSMixIn.__init__(self, tls_settings)
     73          StreamSASLMixIn.__init__(self, sasl_mechanisms)
     74          self.__logger = logging.getLogger("pyxmpp.Stream")
     75
     76 -    def _reset(self):
     77          """Reset `Stream` object state making it ready to handle new
     78          connections."""
     79          StreamBase._reset(self)
     80          self._reset_tls()
     81          self._reset_sasl()
     82
     83 -    def _make_stream_features(self):
     84          """Create the <features/> element for the stream.
     85
     86          [receving entity only]
     87
     88          :returns: new <features/> element node."""
     89          features=StreamBase._make_stream_features(self)
     90          self._make_stream_tls_features(features)
     91          self._make_stream_sasl_features(features)
     92          return features
     93
     94 -    def _process_node(self,xmlnode):
     95          """Process first level element of the stream.
     96
     97          The element may be stream error or features, StartTLS
     98          request/response, SASL request/response or a stanza.
     99
    100          :Parameters:
    101              - `xmlnode`: XML node describing the element
    102          """
    103          if self._process_node_tls(xmlnode):
    104              return
    105          if self._process_node_sasl(xmlnode):
    106              return
    107          StreamBase._process_node(self,xmlnode)
    108
    109 -    def _got_features(self):
    110          """Process incoming <stream:features/> element.
    111
    112          [initiating entity only]
    113
    114          The received features node is available in `self.features`."""
    115          self._handle_tls_features()
    116          self._handle_sasl_features()
    117          StreamBase._got_features(self)
    118          if not self.tls_requested and not self.authenticated:
    119              self.state_change("fully connected",self.peer)
    120              self._post_connect()
    121
    122  # vi: sts=4 et sw=4
    123