source: wokkel/iwokkel.py @ 4:e8e7d5543a6f

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

Reverse how handlers are associated with the stream manager. Kick version.

File size: 13.4 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 setHandlerParent(parent):
22        """
23        Set the parent of the handler.
24
25        @type parent: L{IXMPPHandlerCollection}
26        """
27
28    def disownHandlerParent(parent):
29        """
30        Remove the parent of the handler.
31
32        @type parent: L{IXMPPHandlerCollection}
33        """
34
35    def makeConnection(xs):
36        """
37        A connection over the underlying transport of the XML stream has been
38        established.
39
40        At this point, no traffic has been exchanged over the XML stream
41        given in C{xs}.
42
43        This should setup C{self.xmlstream} and call L{connectionMade}.
44
45        @type xs: L{XmlStream<twisted.words.protocols.jabber.XmlStream>}
46        """
47
48    def connectionMade(self):
49        """
50        Called after a connection has been established.
51
52        This method can be used to change properties of the XML Stream, its
53        authenticator or the stream manager prior to stream initialization
54        (including authentication).
55        """
56
57    def connectionInitialized():
58        """
59        The XML stream has been initialized.
60
61        At this point, authentication was successful, and XML stanzas can be
62        exchanged over the XML stream C{self.xmlstream}. This method can be
63        used to setup observers for incoming stanzas.
64        """
65
66    def connectionLost(reason):
67        """
68        The XML stream has been closed.
69
70        Subsequent use of C{self.parent.send} will result in data being queued
71        until a new connection has been established.
72
73        @type reason: L{twisted.python.failure.Failure}
74        """
75
76class IXMPPHandlerCollection(Interface):
77    """
78    Collection of handlers.
79
80    Contain several handlers and manage their connection.
81    """
82
83    def __iter__():
84        """
85        Get an iterator over all child handlers.
86        """
87
88    def addHandler(handler):
89        """
90        Add a child handler.
91
92        @type handler: L{IXMPPHandler}
93        """
94
95    def removeHandler(handler):
96        """
97        Remove a child handler.
98
99        @type handler: L{IXMPPHandler}
100        """
101
102class IDisco(Interface):
103    """
104    Interface for XMPP service discovery.
105    """
106
107    def getDiscoInfo(target, requestor, nodeIdentifier=None):
108        """
109        Get identity and features from this entity, node.
110
111        @param requestor: The entity the request originated from.
112        @type requestor: L{jid.JID}
113        @param nodeIdentifier: The optional identifier of the node at this
114                               entity to retrieve the identify and features of.
115                               The default is C{None}, meaning the root node.
116        @type nodeIdentifier: C{unicode}
117        """
118
119    def getDiscoItems(target, requestor, nodeIdentifier=None):
120        """
121        Get contained items for this entity, node.
122
123        @param requestor: The entity the request originated from.
124        @type requestor: L{jid.JID}
125        @param nodeIdentifier: The optional identifier of the node at this
126                               entity to retrieve the identify and features of.
127                               The default is C{None}, meaning the root node.
128        @type nodeIdentifier: C{unicode}
129        """
130
131
132class IPubSubClient(Interface):
133
134    def itemsReceived(notifier, node, items):
135        """
136        Called when items have been received from a node.
137
138        @param notifier: the entity from which the notification was received.
139        @type notifier: L{jid.JID}
140        @param node: identifier of the node the items belong to.
141        @type node: C{unicode}
142        @param items: list of received items as domish elements.
143        @type items: C{list} of L{domish.Element}
144        """
145
146    def createNode(node=None):
147        """
148        Create a new publish subscribe node.
149
150        @param node: optional suggestion for the new node's identifier. If
151                     omitted, the creation of an instant node will be
152                     attempted.
153        @type node: L{unicode}
154        @return: a deferred that fires with the identifier of the newly created
155                 node. Note that this can differ from the suggested identifier
156                 if the publish subscribe service chooses to modify or ignore
157                 the suggested identifier.
158        @rtype: L{defer.Deferred}
159        """
160
161    def deleteNode(node):
162        """
163        Delete a node.
164
165        @param node: identifier of the node to be deleted.
166        @type node: L{unicode}
167        @rtype: L{defer.Deferred}
168        """
169
170    def subscribe(node, subscriber):
171        """
172        Subscribe to a node with a given JID.
173
174        @param node: identifier of the node to subscribe to.
175        @type node: L{unicode}
176        @param subscriber: JID to subscribe to the node.
177        @type subscriber: L{jid.JID}
178        @rtype: L{defer.Deferred}
179        """
180
181    def publish(requestor, node, items=[]):
182        """
183        Publish to a node.
184
185        Node that the C{items} parameter is optional, because so-called
186        transient, notification-only nodes do not use items and publish
187        actions only signify a change in some resource.
188
189        @param node: identifier of the node to publish to.
190        @type node: L{unicode}
191        @param items: list of item elements.
192        @type items: L{list} of L{Item}
193        @rtype: L{defer.Deferred}
194        """
195
196
197class IPubSubService(Interface):
198    """
199    Interface for an XMPP Publish Subscribe Service.
200
201    All methods that are called as the result of an XMPP request are to
202    return a deferred that fires when the requested action has been performed.
203    Alternatively, exceptions maybe raised directly or by calling C{errback}
204    on the returned deferred.
205    """
206
207    def notifyPublish(entity, nodeIdentifier, notifications):
208        """
209        Send out notifications for a publish event.
210
211        @param entity: The entity the notifications will originate from.
212        @type entity: L{jid.JID}
213        @param nodeIdentifier: The identifier of the node that was published
214                               to.
215        @type nodeIdentifier: C{unicode}
216        @param notifications: The notifications as tuples of subscriber and
217                              the list of items to be notified.
218        @type notifications: C{list} of (L{jid.JID}, C{list} of
219                             L{domish.Element})
220        """
221
222    def publish(requestor, nodeIdentifier, items):
223        """
224        Called when a publish request has been received.
225
226        @param requestor: The entity the request originated from.
227        @type requestor: L{jid.JID}
228        @param nodeIdentifier: The identifier of the node to publish to.
229        @type nodeIdentifier: C{unicode}
230        @param items: The items to be published as L{domish} elements.
231        @type items: C{list} of C{domish.Element}
232        @return: deferred that fires on success.
233        @rtype: L{defer.Deferred}
234        """
235
236    def subscribe(requestor, nodeIdentifier, subscriber):
237        """
238        Called when a subscribe request has been received.
239
240        @param requestor: The entity the request originated from.
241        @type requestor: L{jid.JID}
242        @param nodeIdentifier: The identifier of the node to subscribe to.
243        @type nodeIdentifier: C{unicode}
244        @param subscriber: The entity to be subscribed.
245        @type subscriber: L{jid.JID}
246        @return: A deferred that fires with a C{str} representing the
247                 subscription state, C{'subscribed'} or C{'pending'}.
248        @rtype: L{defer.Deferred}
249        """
250
251    def unsubscribe(requestor, nodeIdentifier, subscriber):
252        """
253        Called when a subscribe request has been received.
254
255        @param requestor: The entity the request originated from.
256        @type requestor: L{jid.JID}
257        @param nodeIdentifier: The identifier of the node to unsubscribe from.
258        @type nodeIdentifier: C{unicode}
259        @param subscriber: The entity to be unsubscribed.
260        @type subscriber: L{jid.JID}
261        @return: A deferred that fires with C{None} when unsubscription has
262                 succeeded.
263        @rtype: L{defer.Deferred}
264        """
265
266    def subscriptions(requestor):
267        """
268        Called when a subscriptions retrieval request has been received.
269
270        @param requestor: The entity the request originated from.
271        @type requestor: L{jid.JID}
272        @return: A deferred that fires with a C{list} of suscriptions as
273                 C{tuple}s of (node identifier as C{unicode}, subscriber as
274                 L{jid.JID}, subscription state as C{str}). The subscription
275                 state can be C{'subscribed'} or C{'pending'}.
276        @rtype: L{defer.Deferred}
277        """
278
279    def affiliations(requestor):
280        """
281        Called when a affiliations retrieval request has been received.
282
283        @param requestor: The entity the request originated from.
284        @type requestor: L{jid.JID}
285        @return: A deferred that fires with a C{list} of affiliations as
286                 C{tuple}s of (node identifier as C{unicode}, affiliation state
287                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
288                 or C{'outcast'}.
289        @rtype: L{defer.Deferred}
290        """
291
292    def create(requestor, nodeIdentifier):
293        """
294        Called when a node creation request has been received.
295
296        @param requestor: The entity the request originated from.
297        @type requestor: L{jid.JID}
298        @param nodeIdentifier: The suggestion for the identifier of the node to
299                               be created. If the request did not include a
300                               suggestion for the node identifier, the value
301                               is C{None}.
302        @type nodeIdentifier: C{unicode} or C{NoneType}
303        @return: A deferred that fires with a C{unicode} that represents
304                 the identifier of the new node.
305        @rtype: L{defer.Deferred}
306        """
307
308    def getDefaultConfiguration(requestor):
309        """
310        Called when a default node configuration request has been received.
311
312        @param requestor: The entity the request originated from.
313        @type requestor: L{jid.JID}
314        @return: A deferred that fires with a C{dict} representing the default
315                 node configuration. Keys are C{str}s that represent the
316                 field name. Values can be of types C{unicode}, C{int} or
317                 C{bool}.
318        @rtype: L{defer.Deferred}
319        """
320
321    def getConfiguration(requestor, nodeIdentifier):
322        """
323        Called when a node configuration retrieval request has been received.
324
325        @param requestor: The entity the request originated from.
326        @type requestor: L{jid.JID}
327        @param nodeIdentifier: The identifier of the node to retrieve the
328                               configuration from.
329        @type nodeIdentifier: C{unicode}
330        @return: A deferred that fires with a C{dict} representing the node
331                 configuration. Keys are C{str}s that represent the field name.
332                 Values can be of types C{unicode}, C{int} or C{bool}.
333        @rtype: L{defer.Deferred}
334        """
335
336    def setConfiguration(requestor, nodeIdentifier, options):
337        """
338        Called when a node configuration change request has been received.
339
340        @param requestor: The entity the request originated from.
341        @type requestor: L{jid.JID}
342        @param nodeIdentifier: The identifier of the node to change the
343                               configuration of.
344        @type nodeIdentifier: C{unicode}
345        @return: A deferred that fires with C{None} when the node's
346                 configuration has been changed.
347        @rtype: L{defer.Deferred}
348        """
349
350    def items(requestor, nodeIdentifier, maxItems, itemIdentifiers):
351        """
352        Called when a items retrieval request has been received.
353
354        @param requestor: The entity the request originated from.
355        @type requestor: L{jid.JID}
356        @param nodeIdentifier: The identifier of the node to retrieve items
357                               from.
358        @type nodeIdentifier: C{unicode}
359        """
360
361    def retract(requestor, nodeIdentifier, itemIdentifiers):
362        """
363        Called when a item retraction request has been received.
364
365        @param requestor: The entity the request originated from.
366        @type requestor: L{jid.JID}
367        @param nodeIdentifier: The identifier of the node to retract items
368                               from.
369        @type nodeIdentifier: C{unicode}
370        """
371
372    def purge(requestor, nodeIdentifier):
373        """
374        Called when a node purge request has been received.
375
376        @param requestor: The entity the request originated from.
377        @type requestor: L{jid.JID}
378        @param nodeIdentifier: The identifier of the node to be purged.
379        @type nodeIdentifier: C{unicode}
380        """
381
382    def delete(requestor, nodeIdentifier):
383        """
384        Called when a node deletion request has been received.
385
386        @param requestor: The entity the request originated from.
387        @type requestor: L{jid.JID}
388        @param nodeIdentifier: The identifier of the node to be delete.
389        @type nodeIdentifier: C{unicode}
390        """
391
392
Note: See TracBrowser for help on using the repository browser.