twisted/words/protocols/jabber/ijabber.py

   1 # Copyright (c) Twisted Matrix Laboratories.
   2 # See LICENSE for details.
   3
   4 """
   5 Public Jabber Interfaces.
   6 """
   7
   8 from zope.interface import Attribute, Interface
   9
  10 class IInitializer(Interface):
  11     """
  12     Interface for XML stream initializers.
  13
  14     Initializers perform a step in getting the XML stream ready to be
  15     used for the exchange of XML stanzas.
  16     """
  17
  18
  19
  20 class IInitiatingInitializer(IInitializer):
  21     """
  22     Interface for XML stream initializers for the initiating entity.
  23     """
  24
  25     xmlstream = Attribute("""The associated XML stream""")
  26
  27     def initialize():
  28         """
  29         Initiate the initialization step.
  30
  31         May return a deferred when the initialization is done asynchronously.
  32         """
  33
  34
  35
  36 class IIQResponseTracker(Interface):
  37     """
  38     IQ response tracker interface.
  39
  40     The XMPP stanza C{iq} has a request-response nature that fits
  41     naturally with deferreds. You send out a request and when the response
  42     comes back a deferred is fired.
  43
  44     The L{IQ} class implements a C{send} method that returns a deferred. This
  45     deferred is put in a dictionary that is kept in an L{XmlStream} object,
  46     keyed by the request stanzas C{id} attribute.
  47
  48     An object providing this interface (usually an instance of L{XmlStream}),
  49     keeps the said dictionary and sets observers on the iq stanzas of type
  50     C{result} and C{error} and lets the callback fire the associated deferred.
  51     """
  52     iqDeferreds = Attribute("Dictionary of deferreds waiting for an iq "
  53                              "response")
  54
  55
  56
  57 class IXMPPHandler(Interface):
  58     """
  59     Interface for XMPP protocol handlers.
  60
  61     Objects that provide this interface can be added to a stream manager to
  62     handle of (part of) an XMPP extension protocol.
  63     """
  64
  65     parent = Attribute("""XML stream manager for this handler""")
  66     xmlstream = Attribute("""The managed XML stream""")
  67
  68     def setHandlerParent(parent):
  69         """
  70         Set the parent of the handler.
  71
  72         @type parent: L{IXMPPHandlerCollection}
  73         """
  74
  75
  76     def disownHandlerParent(parent):
  77         """
  78         Remove the parent of the handler.
  79
  80         @type parent: L{IXMPPHandlerCollection}
  81         """
  82
  83
  84     def makeConnection(xs):
  85         """
  86         A connection over the underlying transport of the XML stream has been
  87         established.
  88
  89         At this point, no traffic has been exchanged over the XML stream
  90         given in C{xs}.
  91
  92         This should setup L{xmlstream} and call L{connectionMade}.
  93
  94         @type xs: L{XmlStream<twisted.words.protocols.jabber.XmlStream>}
  95         """
  96
  97
  98     def connectionMade():
  99         """
 100         Called after a connection has been established.
 101
 102         This method can be used to change properties of the XML Stream, its
 103         authenticator or the stream manager prior to stream initialization
 104         (including authentication).
 105         """
 106
 107
 108     def connectionInitialized():
 109         """
 110         The XML stream has been initialized.
 111
 112         At this point, authentication was successful, and XML stanzas can be
 113         exchanged over the XML stream L{xmlstream}. This method can be
 114         used to setup observers for incoming stanzas.
 115         """
 116
 117
 118     def connectionLost(reason):
 119         """
 120         The XML stream has been closed.
 121
 122         Subsequent use of C{parent.send} will result in data being queued
 123         until a new connection has been established.
 124
 125         @type reason: L{twisted.python.failure.Failure}
 126         """
 127
 128
 129
 130 class IXMPPHandlerCollection(Interface):
 131     """
 132     Collection of handlers.
 133
 134     Contain several handlers and manage their connection.
 135     """
 136
 137     def __iter__():
 138         """
 139         Get an iterator over all child handlers.
 140         """
 141
 142
 143     def addHandler(handler):
 144         """
 145         Add a child handler.
 146
 147         @type handler: L{IXMPPHandler}
 148         """
 149
 150
 151     def removeHandler(handler):
 152         """
 153         Remove a child handler.
 154
 155         @type handler: L{IXMPPHandler}
 156         """
 157
 158
 159
 160 class IService(Interface):
 161     """
 162     External server-side component service interface.
 163
 164     Services that provide this interface can be added to L{ServiceManager} to
 165     implement (part of) the functionality of the server-side component.
 166     """
 167
 168     def componentConnected(xs):
 169         """
 170         Parent component has established a connection.
 171
 172         At this point, authentication was succesful, and XML stanzas
 173         can be exchanged over the XML stream C{xs}. This method can be used
 174         to setup observers for incoming stanzas.
 175
 176         @param xs: XML Stream that represents the established connection.
 177         @type xs: L{xmlstream.XmlStream}
 178         """
 179
 180
 181     def componentDisconnected():
 182         """
 183         Parent component has lost the connection to the Jabber server.
 184
 185         Subsequent use of C{self.parent.send} will result in data being
 186         queued until a new connection has been established.
 187         """
 188
 189
 190     def transportConnected(xs):
 191         """
 192         Parent component has established a connection over the underlying
 193         transport.
 194
 195         At this point, no traffic has been exchanged over the XML stream. This
 196         method can be used to change properties of the XML Stream (in C{xs}),
 197         the service manager or it's authenticator prior to stream
 198         initialization (including authentication).
 199         """