source: wokkel/iwokkel.py @ 13:b460ae320c23

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

Add support for receiving notifications for item retraction, node deletion and purging.

File size: 17.5 KB
Line 
1# Copyright (c) 2003-2008 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(requestor, target, 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 target: The target entity to which the request is made.
114        @type target: L{jid.JID}
115        @param nodeIdentifier: The optional identifier of the node at this
116                               entity to retrieve the identify and features of.
117                               The default is C{None}, meaning the root node.
118        @type nodeIdentifier: C{unicode}
119        """
120
121    def getDiscoItems(requestor, target, nodeIdentifier=None):
122        """
123        Get contained items for this entity, node.
124
125        @param requestor: The entity the request originated from.
126        @type requestor: L{jid.JID}
127        @param target: The target entity to which the request is made.
128        @type target: L{jid.JID}
129        @param nodeIdentifier: The optional identifier of the node at this
130                               entity to retrieve the identify and features of.
131                               The default is C{None}, meaning the root node.
132        @type nodeIdentifier: C{unicode}
133        """
134
135
136class IPubSubClient(Interface):
137
138    def itemsReceived(recipient, service, nodeIdentifier, items):
139        """
140        Called when an items notification has been received for a node.
141
142        An item can be an element named C{item} or C{retract}. Respectively,
143        they signal an item being published or retracted, optionally
144        accompanied with an item identifier in the C{id} attribute.
145
146        @param recipient: The entity to which the notification was sent.
147        @type recipient: L{jid.JID}
148        @param service: The entity from which the notification was received.
149        @type service: L{jid.JID}
150        @param nodeIdentifier: Identifier of the node the items belong to.
151        @type nodeIdentifier: C{unicode}
152        @param items: List of received items as domish elements.
153        @type items: C{list} of L{domish.Element}
154        """
155
156    def deleteReceived(recipient, service, nodeIdentifier, items):
157        """
158        Called when a deletion notification has been received for a node.
159
160        @param recipient: The entity to which the notification was sent.
161        @type recipient: L{jid.JID}
162        @param service: The entity from which the notification was received.
163        @type service: L{jid.JID}
164        @param nodeIdentifier: Identifier of the node that has been deleted.
165        @type nodeIdentifier: C{unicode}
166        """
167
168    def purgeReceived(recipient, service, nodeIdentifier, items):
169        """
170        Called when a purge notification has been received for a node.
171
172        Upon receiving this notification all items associated should be
173        considered retracted.
174
175        @param recipient: The entity to which the notification was sent.
176        @type recipient: L{jid.JID}
177        @param service: The entity from which the notification was received.
178        @type service: L{jid.JID}
179        @param nodeIdentifier: Identifier of the node that has been purged.
180        @type nodeIdentifier: C{unicode}
181        """
182
183    def createNode(service, nodeIdentifier=None):
184        """
185        Create a new publish subscribe node.
186
187        @param service: The publish-subscribe service entity.
188        @type service: L{jid.JID}
189        @param nodeIdentifier: Optional suggestion for the new node's
190                               identifier. If omitted, the creation of an
191                               instant node will be attempted.
192        @type nodeIdentifier: L{unicode}
193        @return: a deferred that fires with the identifier of the newly created
194                 node. Note that this can differ from the suggested identifier
195                 if the publish subscribe service chooses to modify or ignore
196                 the suggested identifier.
197        @rtype: L{defer.Deferred}
198        """
199
200    def deleteNode(service, nodeIdentifier):
201        """
202        Delete a node.
203
204        @param service: The publish-subscribe service entity.
205        @type service: L{jid.JID}
206        @param nodeIdentifier: Identifier of the node to be deleted.
207        @type nodeIdentifier: L{unicode}
208        @rtype: L{defer.Deferred}
209        """
210
211    def subscribe(service, nodeIdentifier, subscriber):
212        """
213        Subscribe to a node with a given JID.
214
215        @param service: The publish-subscribe service entity.
216        @type service: L{jid.JID}
217        @param nodeIdentifier: Identifier of the node to subscribe to.
218        @type nodeIdentifier: L{unicode}
219        @param subscriber: JID to subscribe to the node.
220        @type subscriber: L{jid.JID}
221        @rtype: L{defer.Deferred}
222        """
223
224    def unsubscribe(service, nodeIdentifier, subscriber):
225        """
226        Unsubscribe from a node with a given JID.
227
228        @param service: The publish-subscribe service entity.
229        @type service: L{jid.JID}
230        @param nodeIdentifier: Identifier of the node to unsubscribe from.
231        @type nodeIdentifier: L{unicode}
232        @param subscriber: JID to unsubscribe from the node.
233        @type subscriber: L{jid.JID}
234        @rtype: L{defer.Deferred}
235        """
236
237    def publish(service, nodeIdentifier, items=[]):
238        """
239        Publish to a node.
240
241        Node that the C{items} parameter is optional, because so-called
242        transient, notification-only nodes do not use items and publish
243        actions only signify a change in some resource.
244
245        @param service: The publish-subscribe service entity.
246        @type service: L{jid.JID}
247        @param nodeIdentifier: Identifier of the node to publish to.
248        @type nodeIdentifier: L{unicode}
249        @param items: List of item elements.
250        @type items: L{list} of L{Item}
251        @rtype: L{defer.Deferred}
252        """
253
254
255class IPubSubService(Interface):
256    """
257    Interface for an XMPP Publish Subscribe Service.
258
259    All methods that are called as the result of an XMPP request are to
260    return a deferred that fires when the requested action has been performed.
261    Alternatively, exceptions maybe raised directly or by calling C{errback}
262    on the returned deferred.
263    """
264
265    def notifyPublish(service, nodeIdentifier, notifications):
266        """
267        Send out notifications for a publish event.
268
269        @param service: The entity the notifications will originate from.
270        @type service: L{jid.JID}
271        @param nodeIdentifier: The identifier of the node that was published
272                               to.
273        @type nodeIdentifier: C{unicode}
274        @param notifications: The notifications as tuples of subscriber and
275                              the list of items to be notified.
276        @type notifications: C{list} of (L{jid.JID}, C{list} of
277                             L{domish.Element})
278        """
279
280    def publish(requestor, service, nodeIdentifier, items):
281        """
282        Called when a publish request has been received.
283
284        @param requestor: The entity the request originated from.
285        @type requestor: L{jid.JID}
286        @param service: The entity the request was addressed to.
287        @type service: L{jid.JID}
288        @param nodeIdentifier: The identifier of the node to publish to.
289        @type nodeIdentifier: C{unicode}
290        @param items: The items to be published as L{domish} elements.
291        @type items: C{list} of C{domish.Element}
292        @return: deferred that fires on success.
293        @rtype: L{defer.Deferred}
294        """
295
296    def subscribe(requestor, service, nodeIdentifier, subscriber):
297        """
298        Called when a subscribe request has been received.
299
300        @param requestor: The entity the request originated from.
301        @type requestor: L{jid.JID}
302        @param service: The entity the request was addressed to.
303        @type service: L{jid.JID}
304        @param nodeIdentifier: The identifier of the node to subscribe to.
305        @type nodeIdentifier: C{unicode}
306        @param subscriber: The entity to be subscribed.
307        @type subscriber: L{jid.JID}
308        @return: A deferred that fires with a C{str} representing the
309                 subscription state, C{'subscribed'} or C{'pending'}.
310        @rtype: L{defer.Deferred}
311        """
312
313    def unsubscribe(requestor, service, nodeIdentifier, subscriber):
314        """
315        Called when a subscribe request has been received.
316
317        @param requestor: The entity the request originated from.
318        @type requestor: L{jid.JID}
319        @param service: The entity the request was addressed to.
320        @type service: L{jid.JID}
321        @param nodeIdentifier: The identifier of the node to unsubscribe from.
322        @type nodeIdentifier: C{unicode}
323        @param subscriber: The entity to be unsubscribed.
324        @type subscriber: L{jid.JID}
325        @return: A deferred that fires with C{None} when unsubscription has
326                 succeeded.
327        @rtype: L{defer.Deferred}
328        """
329
330    def subscriptions(requestor, service):
331        """
332        Called when a subscriptions retrieval request has been received.
333
334        @param requestor: The entity the request originated from.
335        @type requestor: L{jid.JID}
336        @param service: The entity the request was addressed to.
337        @type service: L{jid.JID}
338        @return: A deferred that fires with a C{list} of suscriptions as
339                 C{tuple}s of (node identifier as C{unicode}, subscriber as
340                 L{jid.JID}, subscription state as C{str}). The subscription
341                 state can be C{'subscribed'} or C{'pending'}.
342        @rtype: L{defer.Deferred}
343        """
344
345    def affiliations(requestor, service):
346        """
347        Called when a affiliations retrieval request has been received.
348
349        @param requestor: The entity the request originated from.
350        @type requestor: L{jid.JID}
351        @param service: The entity the request was addressed to.
352        @type service: L{jid.JID}
353        @return: A deferred that fires with a C{list} of affiliations as
354                 C{tuple}s of (node identifier as C{unicode}, affiliation state
355                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
356                 or C{'outcast'}.
357        @rtype: L{defer.Deferred}
358        """
359
360    def create(requestor, service, nodeIdentifier):
361        """
362        Called when a node creation request has been received.
363
364        @param requestor: The entity the request originated from.
365        @type requestor: L{jid.JID}
366        @param service: The entity the request was addressed to.
367        @type service: L{jid.JID}
368        @param nodeIdentifier: The suggestion for the identifier of the node to
369                               be created. If the request did not include a
370                               suggestion for the node identifier, the value
371                               is C{None}.
372        @type nodeIdentifier: C{unicode} or C{NoneType}
373        @return: A deferred that fires with a C{unicode} that represents
374                 the identifier of the new node.
375        @rtype: L{defer.Deferred}
376        """
377
378    def getDefaultConfiguration(requestor, service):
379        """
380        Called when a default node configuration request has been received.
381
382        @param requestor: The entity the request originated from.
383        @type requestor: L{jid.JID}
384        @param service: The entity the request was addressed to.
385        @type service: L{jid.JID}
386        @return: A deferred that fires with a C{dict} representing the default
387                 node configuration. Keys are C{str}s that represent the
388                 field name. Values can be of types C{unicode}, C{int} or
389                 C{bool}.
390        @rtype: L{defer.Deferred}
391        """
392
393    def getConfiguration(requestor, service, nodeIdentifier):
394        """
395        Called when a node configuration retrieval request has been received.
396
397        @param requestor: The entity the request originated from.
398        @type requestor: L{jid.JID}
399        @param service: The entity the request was addressed to.
400        @type service: L{jid.JID}
401        @param nodeIdentifier: The identifier of the node to retrieve the
402                               configuration from.
403        @type nodeIdentifier: C{unicode}
404        @return: A deferred that fires with a C{dict} representing the node
405                 configuration. Keys are C{str}s that represent the field name.
406                 Values can be of types C{unicode}, C{int} or C{bool}.
407        @rtype: L{defer.Deferred}
408        """
409
410    def setConfiguration(requestor, service, nodeIdentifier, options):
411        """
412        Called when a node configuration change request has been received.
413
414        @param requestor: The entity the request originated from.
415        @type requestor: L{jid.JID}
416        @param service: The entity the request was addressed to.
417        @type service: L{jid.JID}
418        @param nodeIdentifier: The identifier of the node to change the
419                               configuration of.
420        @type nodeIdentifier: C{unicode}
421        @return: A deferred that fires with C{None} when the node's
422                 configuration has been changed.
423        @rtype: L{defer.Deferred}
424        """
425
426    def items(requestor, service, nodeIdentifier, maxItems, itemIdentifiers):
427        """
428        Called when a items retrieval request has been received.
429
430        @param requestor: The entity the request originated from.
431        @type requestor: L{jid.JID}
432        @param service: The entity the request was addressed to.
433        @type service: L{jid.JID}
434        @param nodeIdentifier: The identifier of the node to retrieve items
435                               from.
436        @type nodeIdentifier: C{unicode}
437        """
438
439    def retract(requestor, service, nodeIdentifier, itemIdentifiers):
440        """
441        Called when a item retraction request has been received.
442
443        @param requestor: The entity the request originated from.
444        @type requestor: L{jid.JID}
445        @param service: The entity the request was addressed to.
446        @type service: L{jid.JID}
447        @param nodeIdentifier: The identifier of the node to retract items
448                               from.
449        @type nodeIdentifier: C{unicode}
450        """
451
452    def purge(requestor, service, nodeIdentifier):
453        """
454        Called when a node purge request has been received.
455
456        @param requestor: The entity the request originated from.
457        @type requestor: L{jid.JID}
458        @param service: The entity the request was addressed to.
459        @type service: L{jid.JID}
460        @param nodeIdentifier: The identifier of the node to be purged.
461        @type nodeIdentifier: C{unicode}
462        """
463
464    def delete(requestor, service, nodeIdentifier):
465        """
466        Called when a node deletion request has been received.
467
468        @param requestor: The entity the request originated from.
469        @type requestor: L{jid.JID}
470        @param service: The entity the request was addressed to.
471        @type service: L{jid.JID}
472        @param nodeIdentifier: The identifier of the node to be delete.
473        @type nodeIdentifier: C{unicode}
474        """
Note: See TracBrowser for help on using the repository browser.