source: wokkel/iwokkel.py @ 15:14a00be2ae9d

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

Add notifyDelete to send out node deletion notifications.

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