← Back to branch summary

~justin-fathomdb/nova/justinsb-openstack-api-volumes

« back to all changes in this revision

Viewing changes to vendor/Twisted-10.0.0/twisted/words/protocols/jabber/ijabber.py

  • Committer: Jesse Andrews
  • Date: 2010-05-28 06:05:26 UTC
  • Revision ID: git-v1:bf6e6e718cdc7488e2da87b21e258ccc065fe499
initial commit

Show diffs side-by-side

added added

removed removed

Lines of Context:
vendor/Twisted-10.0.0/twisted/words/protocols/jabber/ijabber.py
 
1
# Copyright (c) 2001-2008 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 L{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 L{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 L{xs}),
 
197
        the service manager or it's authenticator prior to stream
 
198
        initialization (including authentication).
 
199
        """