source: wokkel/iwokkel.py @ 1:677f7d3cca75

Last change on this file since 1:677f7d3cca75 was 1:677f7d3cca75, checked in by Ralph Meijer <ralphm@…>, 14 years ago

Initial, heavily worked around code drop from the idavoll and mimir projects.

File size: 10.6 KB
Line 
1# Copyright (c) 2003-2007 Ralph Meijer
2# See LICENSE for details.
3
4"""
5Wokkel interfaces.
6"""
7
8from zope.interface import Attribute, Interface
9
10class IXMPPHandler(Interface):
11    """
12    Interface for XMPP protocol handlers.
13
14    Objects that provide this interface can be added to a stream manager to
15    handle of (part of) an XMPP extension protocol.
16    """
17
18    manager = Attribute("""XML stream manager""")
19    xmlstream = Attribute("""The managed XML stream""")
20
21    def makeConnection(xs):
22        """
23        A connection over the underlying transport of the XML stream has been
24        established.
25
26        At this point, no traffic has been exchanged over the XML stream
27        given in C{xs}.
28
29        This should setup C{self.xmlstream} and call L{connectionMade}.
30
31        @type xs: L{XmlStream<twisted.words.protocols.jabber.XmlStream>}
32        """
33
34    def connectionMade(self):
35        """
36        Called after a connection has been established.
37
38        This method can be used to change properties of the XML Stream, its
39        authenticator or the stream manager prior to stream initialization
40        (including authentication).
41        """
42
43    def connectionInitialized():
44        """
45        The XML stream has been initialized.
46
47        At this point, authentication was successful, and XML stanzas can be
48        exchanged over the XML stream C{self.xmlstream}. This method can be
49        used to setup observers for incoming stanzas.
50        """
51
52    def connectionLost(reason):
53        """
54        The XML stream has been closed.
55
56        Subsequent use of C{self.parent.send} will result in data being queued
57        until a new connection has been established.
58
59        @type reason: L{twisted.python.failure.Failure}
60        """
61
62
63class IDisco(Interface):
64    """
65    Interface for XMPP service discovery.
66    """
67
68    def getDiscoInfo(target, requestor, nodeIdentifier=None):
69        """
70        Get identity and features from this entity, node.
71
72        @param requestor: The entity the request originated from.
73        @type requestor: L{jid.JID}
74        @param nodeIdentifier: The optional identifier of the node at this
75                               entity to retrieve the identify and features of.
76                               The default is C{None}, meaning the root node.
77        @type nodeIdentifier: C{unicode}
78        """
79
80    def getDiscoItems(target, requestor, nodeIdentifier=None):
81        """
82        Get contained items for this entity, node.
83
84        @param requestor: The entity the request originated from.
85        @type requestor: L{jid.JID}
86        @param nodeIdentifier: The optional identifier of the node at this
87                               entity to retrieve the identify and features of.
88                               The default is C{None}, meaning the root node.
89        @type nodeIdentifier: C{unicode}
90        """
91
92class IPubSubService(Interface):
93    """
94    Interface for an XMPP Publish Subscribe Service.
95
96    All methods that are called as the result of an XMPP request are to
97    return a deferred that fires when the requested action has been performed.
98    Alternatively, exceptions maybe raised directly or by calling C{errback}
99    on the returned deferred.
100    """
101
102    def notifyPublish(entity, nodeIdentifier, notifications):
103        """
104        Send out notifications for a publish event.
105
106        @param entity: The entity the notifications will originate from.
107        @type entity: L{jid.JID}
108        @param nodeIdentifier: The identifier of the node that was published
109                               to.
110        @type nodeIdentifier: C{unicode}
111        @param notifications: The notifications as tuples of subscriber and
112                              the list of items to be notified.
113        @type notifications: C{list} of (L{jid.JID}, C{list} of
114                             L{domish.Element})
115        """
116
117    def publish(requestor, nodeIdentifier, items):
118        """
119        Called when a publish request has been received.
120
121        @param requestor: The entity the request originated from.
122        @type requestor: L{jid.JID}
123        @param nodeIdentifier: The identifier of the node to publish to.
124        @type nodeIdentifier: C{unicode}
125        @param items: The items to be published as L{domish} elements.
126        @type items: C{list} of C{domish.Element}
127        @return: deferred that fires on success.
128        @rtype: L{defer.Deferred}
129        """
130
131    def subscribe(requestor, nodeIdentifier, subscriber):
132        """
133        Called when a subscribe request has been received.
134
135        @param requestor: The entity the request originated from.
136        @type requestor: L{jid.JID}
137        @param nodeIdentifier: The identifier of the node to subscribe to.
138        @type nodeIdentifier: C{unicode}
139        @param subscriber: The entity to be subscribed.
140        @type subscriber: L{jid.JID}
141        @return: A deferred that fires with a C{str} representing the
142                 subscription state, C{'subscribed'} or C{'pending'}.
143        @rtype: L{defer.Deferred}
144        """
145
146    def unsubscribe(requestor, nodeIdentifier, subscriber):
147        """
148        Called when a subscribe request has been received.
149
150        @param requestor: The entity the request originated from.
151        @type requestor: L{jid.JID}
152        @param nodeIdentifier: The identifier of the node to unsubscribe from.
153        @type nodeIdentifier: C{unicode}
154        @param subscriber: The entity to be unsubscribed.
155        @type subscriber: L{jid.JID}
156        @return: A deferred that fires with C{None} when unsubscription has
157                 succeeded.
158        @rtype: L{defer.Deferred}
159        """
160
161    def subscriptions(requestor):
162        """
163        Called when a subscriptions retrieval request has been received.
164
165        @param requestor: The entity the request originated from.
166        @type requestor: L{jid.JID}
167        @return: A deferred that fires with a C{list} of suscriptions as
168                 C{tuple}s of (node identifier as C{unicode}, subscriber as
169                 L{jid.JID}, subscription state as C{str}). The subscription
170                 state can be C{'subscribed'} or C{'pending'}.
171        @rtype: L{defer.Deferred}
172        """
173
174    def affiliations(requestor):
175        """
176        Called when a affiliations retrieval request has been received.
177
178        @param requestor: The entity the request originated from.
179        @type requestor: L{jid.JID}
180        @return: A deferred that fires with a C{list} of affiliations as
181                 C{tuple}s of (node identifier as C{unicode}, affiliation state
182                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
183                 or C{'outcast'}.
184        @rtype: L{defer.Deferred}
185        """
186
187    def create(requestor, nodeIdentifier):
188        """
189        Called when a node creation request has been received.
190
191        @param requestor: The entity the request originated from.
192        @type requestor: L{jid.JID}
193        @param nodeIdentifier: The suggestion for the identifier of the node to
194                               be created. If the request did not include a
195                               suggestion for the node identifier, the value
196                               is C{None}.
197        @type nodeIdentifier: C{unicode} or C{NoneType}
198        @return: A deferred that fires with a C{unicode} that represents
199                 the identifier of the new node.
200        @rtype: L{defer.Deferred}
201        """
202
203    def getDefaultConfiguration(requestor):
204        """
205        Called when a default node configuration request has been received.
206
207        @param requestor: The entity the request originated from.
208        @type requestor: L{jid.JID}
209        @return: A deferred that fires with a C{dict} representing the default
210                 node configuration. Keys are C{str}s that represent the
211                 field name. Values can be of types C{unicode}, C{int} or
212                 C{bool}.
213        @rtype: L{defer.Deferred}
214        """
215
216    def getConfiguration(requestor, nodeIdentifier):
217        """
218        Called when a node configuration retrieval request has been received.
219
220        @param requestor: The entity the request originated from.
221        @type requestor: L{jid.JID}
222        @param nodeIdentifier: The identifier of the node to retrieve the
223                               configuration from.
224        @type nodeIdentifier: C{unicode}
225        @return: A deferred that fires with a C{dict} representing the node
226                 configuration. Keys are C{str}s that represent the field name.
227                 Values can be of types C{unicode}, C{int} or C{bool}.
228        @rtype: L{defer.Deferred}
229        """
230
231    def setConfiguration(requestor, nodeIdentifier, options):
232        """
233        Called when a node configuration change request has been received.
234
235        @param requestor: The entity the request originated from.
236        @type requestor: L{jid.JID}
237        @param nodeIdentifier: The identifier of the node to change the
238                               configuration of.
239        @type nodeIdentifier: C{unicode}
240        @return: A deferred that fires with C{None} when the node's
241                 configuration has been changed.
242        @rtype: L{defer.Deferred}
243        """
244
245    def items(requestor, nodeIdentifier, maxItems, itemIdentifiers):
246        """
247        Called when a items retrieval request has been received.
248
249        @param requestor: The entity the request originated from.
250        @type requestor: L{jid.JID}
251        @param nodeIdentifier: The identifier of the node to retrieve items
252                               from.
253        @type nodeIdentifier: C{unicode}
254        """
255
256    def retract(requestor, nodeIdentifier, itemIdentifiers):
257        """
258        Called when a item retraction request has been received.
259
260        @param requestor: The entity the request originated from.
261        @type requestor: L{jid.JID}
262        @param nodeIdentifier: The identifier of the node to retract items
263                               from.
264        @type nodeIdentifier: C{unicode}
265        """
266
267    def purge(requestor, nodeIdentifier):
268        """
269        Called when a node purge request has been received.
270
271        @param requestor: The entity the request originated from.
272        @type requestor: L{jid.JID}
273        @param nodeIdentifier: The identifier of the node to be purged.
274        @type nodeIdentifier: C{unicode}
275        """
276
277    def delete(requestor, nodeIdentifier):
278        """
279        Called when a node deletion request has been received.
280
281        @param requestor: The entity the request originated from.
282        @type requestor: L{jid.JID}
283        @param nodeIdentifier: The identifier of the node to be delete.
284        @type nodeIdentifier: C{unicode}
285        """
286
287
Note: See TracBrowser for help on using the repository browser.