source: wokkel/iwokkel.py @ 48:190498075c7f

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

Fix some epytext problems.

Author: ralphm.

File size: 18.6 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    parent = Attribute("""XML stream manager for this handler""")
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
29    def disownHandlerParent(parent):
30        """
31        Remove the parent of the handler.
32
33        @type parent: L{IXMPPHandlerCollection}
34        """
35
36
37    def makeConnection(xs):
38        """
39        A connection over the underlying transport of the XML stream has been
40        established.
41
42        At this point, no traffic has been exchanged over the XML stream
43        given in C{xs}.
44
45        This should setup L{xmlstream} and call L{connectionMade}.
46
47        @type xs: L{XmlStream<twisted.words.protocols.jabber.XmlStream>}
48        """
49
50
51    def connectionMade():
52        """
53        Called after a connection has been established.
54
55        This method can be used to change properties of the XML Stream, its
56        authenticator or the stream manager prior to stream initialization
57        (including authentication).
58        """
59
60
61    def connectionInitialized():
62        """
63        The XML stream has been initialized.
64
65        At this point, authentication was successful, and XML stanzas can be
66        exchanged over the XML stream L{xmlstream}. This method can be
67        used to setup observers for incoming stanzas.
68        """
69
70
71    def connectionLost(reason):
72        """
73        The XML stream has been closed.
74
75        Subsequent use of L{parent.send} will result in data being queued
76        until a new connection has been established.
77
78        @type reason: L{twisted.python.failure.Failure}
79        """
80
81
82
83class IXMPPHandlerCollection(Interface):
84    """
85    Collection of handlers.
86
87    Contain several handlers and manage their connection.
88    """
89
90    def __iter__():
91        """
92        Get an iterator over all child handlers.
93        """
94
95
96    def addHandler(handler):
97        """
98        Add a child handler.
99
100        @type handler: L{IXMPPHandler}
101        """
102
103
104    def removeHandler(handler):
105        """
106        Remove a child handler.
107
108        @type handler: L{IXMPPHandler}
109        """
110
111
112
113class IDisco(Interface):
114    """
115    Interface for XMPP service discovery.
116    """
117
118    def getDiscoInfo(requestor, target, nodeIdentifier=''):
119        """
120        Get identity and features from this entity, node.
121
122        @param requestor: The entity the request originated from.
123        @type requestor: L{jid.JID}
124        @param target: The target entity to which the request is made.
125        @type target: L{jid.JID}
126        @param nodeIdentifier: The optional identifier of the node at this
127                               entity to retrieve the identify and features of.
128                               The default is C{''}, meaning the root node.
129        @type nodeIdentifier: C{unicode}
130        """
131
132    def getDiscoItems(requestor, target, nodeIdentifier=''):
133        """
134        Get contained items for this entity, node.
135
136        @param requestor: The entity the request originated from.
137        @type requestor: L{jid.JID}
138        @param target: The target entity to which the request is made.
139        @type target: L{jid.JID}
140        @param nodeIdentifier: The optional identifier of the node at this
141                               entity to retrieve the identify and features of.
142                               The default is C{''}, meaning the root node.
143        @type nodeIdentifier: C{unicode}
144        """
145
146
147class IPubSubClient(Interface):
148
149    def itemsReceived(event):
150        """
151        Called when an items notification has been received for a node.
152
153        An item can be an element named C{item} or C{retract}. Respectively,
154        they signal an item being published or retracted, optionally
155        accompanied with an item identifier in the C{id} attribute.
156
157        @param event: The items event.
158        @type event: L{ItemsEvent<wokkel.pubsub.ItemsEvent>}
159        """
160
161
162    def deleteReceived(event):
163        """
164        Called when a deletion notification has been received for a node.
165
166        @param event: The items event.
167        @type event: L{ItemsEvent<wokkel.pubsub.DeleteEvent>}
168        """
169
170
171    def purgeReceived(event):
172        """
173        Called when a purge notification has been received for a node.
174
175        Upon receiving this notification all items associated should be
176        considered retracted.
177
178        @param event: The items event.
179        @type event: L{ItemsEvent<wokkel.pubsub.PurgeEvent>}
180        """
181
182    def createNode(service, nodeIdentifier=None):
183        """
184        Create a new publish subscribe node.
185
186        @param service: The publish-subscribe service entity.
187        @type service: L{jid.JID}
188        @param nodeIdentifier: Optional suggestion for the new node's
189                               identifier. If omitted, the creation of an
190                               instant node will be attempted.
191        @type nodeIdentifier: L{unicode}
192        @return: a deferred that fires with the identifier of the newly created
193                 node. Note that this can differ from the suggested identifier
194                 if the publish subscribe service chooses to modify or ignore
195                 the suggested identifier.
196        @rtype: L{defer.Deferred}
197        """
198
199    def deleteNode(service, nodeIdentifier):
200        """
201        Delete a node.
202
203        @param service: The publish-subscribe service entity.
204        @type service: L{jid.JID}
205        @param nodeIdentifier: Identifier of the node to be deleted.
206        @type nodeIdentifier: L{unicode}
207        @rtype: L{defer.Deferred}
208        """
209
210    def subscribe(service, nodeIdentifier, subscriber):
211        """
212        Subscribe to a node with a given JID.
213
214        @param service: The publish-subscribe service entity.
215        @type service: L{jid.JID}
216        @param nodeIdentifier: Identifier of the node to subscribe to.
217        @type nodeIdentifier: L{unicode}
218        @param subscriber: JID to subscribe to the node.
219        @type subscriber: L{jid.JID}
220        @rtype: L{defer.Deferred}
221        """
222
223    def unsubscribe(service, nodeIdentifier, subscriber):
224        """
225        Unsubscribe from a node with a given JID.
226
227        @param service: The publish-subscribe service entity.
228        @type service: L{jid.JID}
229        @param nodeIdentifier: Identifier of the node to unsubscribe from.
230        @type nodeIdentifier: L{unicode}
231        @param subscriber: JID to unsubscribe from the node.
232        @type subscriber: L{jid.JID}
233        @rtype: L{defer.Deferred}
234        """
235
236    def publish(service, nodeIdentifier, items=[]):
237        """
238        Publish to a node.
239
240        Node that the C{items} parameter is optional, because so-called
241        transient, notification-only nodes do not use items and publish
242        actions only signify a change in some resource.
243
244        @param service: The publish-subscribe service entity.
245        @type service: L{jid.JID}
246        @param nodeIdentifier: Identifier of the node to publish to.
247        @type nodeIdentifier: L{unicode}
248        @param items: List of item elements.
249        @type items: L{list} of L{Item}
250        @rtype: L{defer.Deferred}
251        """
252
253
254class IPubSubService(Interface):
255    """
256    Interface for an XMPP Publish Subscribe Service.
257
258    All methods that are called as the result of an XMPP request are to
259    return a deferred that fires when the requested action has been performed.
260    Alternatively, exceptions maybe raised directly or by calling C{errback}
261    on the returned deferred.
262    """
263
264    def notifyPublish(service, nodeIdentifier, notifications):
265        """
266        Send out notifications for a publish event.
267
268        @param service: The entity the notifications will originate from.
269        @type service: L{jid.JID}
270        @param nodeIdentifier: The identifier of the node that was published
271                               to.
272        @type nodeIdentifier: C{unicode}
273        @param notifications: The notifications as tuples of subscriber, the
274                              list of subscriptions and the list of items to be
275                              notified.
276        @type notifications: C{list} of (L{jid.JID}, C{list} of
277                             L{Subscription<wokkel.pubsub.Subscription>},
278                             C{list} of L{domish.Element})
279        """
280
281    def notifyDelete(service, nodeIdentifier, subscribers,
282                     redirectURI=None):
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 subscribers: The subscribers for which a notification should
291                            be sent out.
292        @type subscribers: C{list} of L{jid.JID}
293        @param redirectURI: Optional XMPP URI of another node that subscribers
294                            are redirected to.
295        @type redirectURI: C{str}
296        """
297
298    def publish(requestor, service, nodeIdentifier, items):
299        """
300        Called when a publish request has been received.
301
302        @param requestor: The entity the request originated from.
303        @type requestor: L{jid.JID}
304        @param service: The entity the request was addressed to.
305        @type service: L{jid.JID}
306        @param nodeIdentifier: The identifier of the node to publish to.
307        @type nodeIdentifier: C{unicode}
308        @param items: The items to be published as L{domish} elements.
309        @type items: C{list} of C{domish.Element}
310        @return: deferred that fires on success.
311        @rtype: L{defer.Deferred}
312        """
313
314    def subscribe(requestor, service, nodeIdentifier, subscriber):
315        """
316        Called when a subscribe request has been received.
317
318        @param requestor: The entity the request originated from.
319        @type requestor: L{jid.JID}
320        @param service: The entity the request was addressed to.
321        @type service: L{jid.JID}
322        @param nodeIdentifier: The identifier of the node to subscribe to.
323        @type nodeIdentifier: C{unicode}
324        @param subscriber: The entity to be subscribed.
325        @type subscriber: L{jid.JID}
326        @return: A deferred that fires with a
327                 L{Subscription<wokkel.pubsub.Subscription>}.
328        @rtype: L{defer.Deferred}
329        """
330
331    def unsubscribe(requestor, service, nodeIdentifier, subscriber):
332        """
333        Called when a subscribe request has been received.
334
335        @param requestor: The entity the request originated from.
336        @type requestor: L{jid.JID}
337        @param service: The entity the request was addressed to.
338        @type service: L{jid.JID}
339        @param nodeIdentifier: The identifier of the node to unsubscribe from.
340        @type nodeIdentifier: C{unicode}
341        @param subscriber: The entity to be unsubscribed.
342        @type subscriber: L{jid.JID}
343        @return: A deferred that fires with C{None} when unsubscription has
344                 succeeded.
345        @rtype: L{defer.Deferred}
346        """
347
348    def subscriptions(requestor, service):
349        """
350        Called when a subscriptions retrieval request has been received.
351
352        @param requestor: The entity the request originated from.
353        @type requestor: L{jid.JID}
354        @param service: The entity the request was addressed to.
355        @type service: L{jid.JID}
356        @return: A deferred that fires with a C{list} of subscriptions as
357                 L{Subscription<wokkel.pubsub.Subscription>}.
358        @rtype: L{defer.Deferred}
359        """
360
361    def affiliations(requestor, service):
362        """
363        Called when a affiliations retrieval request has been received.
364
365        @param requestor: The entity the request originated from.
366        @type requestor: L{jid.JID}
367        @param service: The entity the request was addressed to.
368        @type service: L{jid.JID}
369        @return: A deferred that fires with a C{list} of affiliations as
370                 C{tuple}s of (node identifier as C{unicode}, affiliation state
371                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
372                 or C{'outcast'}.
373        @rtype: L{defer.Deferred}
374        """
375
376    def create(requestor, service, nodeIdentifier):
377        """
378        Called when a node creation request has been received.
379
380        @param requestor: The entity the request originated from.
381        @type requestor: L{jid.JID}
382        @param service: The entity the request was addressed to.
383        @type service: L{jid.JID}
384        @param nodeIdentifier: The suggestion for the identifier of the node to
385                               be created. If the request did not include a
386                               suggestion for the node identifier, the value
387                               is C{None}.
388        @type nodeIdentifier: C{unicode} or C{NoneType}
389        @return: A deferred that fires with a C{unicode} that represents
390                 the identifier of the new node.
391        @rtype: L{defer.Deferred}
392        """
393
394    def getConfigurationOptions():
395        """
396        Retrieve all known node configuration options.
397
398        The returned dictionary holds the possible node configuration options
399        by option name. The value of each entry represents the specifics for
400        that option in a dictionary:
401
402         - C{'type'} (C{str}): The option's type (see
403           L{Field<wokkel.data_form.Field>}'s doc string for possible values).
404         - C{'label'} (C{unicode}): A human readable label for this option.
405         - C{'options'} (C{dict}): Optional list of possible values for this
406           option.
407
408        Example::
409
410            {
411            "pubsub#persist_items":
412                {"type": "boolean",
413                 "label": "Persist items to storage"},
414            "pubsub#deliver_payloads":
415                {"type": "boolean",
416                 "label": "Deliver payloads with event notifications"},
417            "pubsub#send_last_published_item":
418                {"type": "list-single",
419                 "label": "When to send the last published item",
420                 "options": {
421                     "never": "Never",
422                     "on_sub": "When a new subscription is processed"}
423                }
424            }
425
426        @rtype: C{dict}.
427        """
428
429    def getDefaultConfiguration(requestor, service, nodeType):
430        """
431        Called when a default node configuration request has been received.
432
433        @param requestor: The entity the request originated from.
434        @type requestor: L{jid.JID}
435        @param service: The entity the request was addressed to.
436        @type service: L{jid.JID}
437        @param nodeType: The type of node for which the configuration is
438                         retrieved, C{'leaf'} or C{'collection'}.
439        @type nodeType: C{str}
440        @return: A deferred that fires with a C{dict} representing the default
441                 node configuration. Keys are C{str}s that represent the
442                 field name. Values can be of types C{unicode}, C{int} or
443                 C{bool}.
444        @rtype: L{defer.Deferred}
445        """
446
447    def getConfiguration(requestor, service, nodeIdentifier):
448        """
449        Called when a node configuration retrieval request has been received.
450
451        @param requestor: The entity the request originated from.
452        @type requestor: L{jid.JID}
453        @param service: The entity the request was addressed to.
454        @type service: L{jid.JID}
455        @param nodeIdentifier: The identifier of the node to retrieve the
456                               configuration from.
457        @type nodeIdentifier: C{unicode}
458        @return: A deferred that fires with a C{dict} representing the node
459                 configuration. Keys are C{str}s that represent the field name.
460                 Values can be of types C{unicode}, C{int} or C{bool}.
461        @rtype: L{defer.Deferred}
462        """
463
464    def setConfiguration(requestor, service, nodeIdentifier, options):
465        """
466        Called when a node configuration change 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 change the
473                               configuration of.
474        @type nodeIdentifier: C{unicode}
475        @return: A deferred that fires with C{None} when the node's
476                 configuration has been changed.
477        @rtype: L{defer.Deferred}
478        """
479
480    def items(requestor, service, nodeIdentifier, maxItems, itemIdentifiers):
481        """
482        Called when a items retrieval request has been received.
483
484        @param requestor: The entity the request originated from.
485        @type requestor: L{jid.JID}
486        @param service: The entity the request was addressed to.
487        @type service: L{jid.JID}
488        @param nodeIdentifier: The identifier of the node to retrieve items
489                               from.
490        @type nodeIdentifier: C{unicode}
491        """
492
493    def retract(requestor, service, nodeIdentifier, itemIdentifiers):
494        """
495        Called when a item retraction request has been received.
496
497        @param requestor: The entity the request originated from.
498        @type requestor: L{jid.JID}
499        @param service: The entity the request was addressed to.
500        @type service: L{jid.JID}
501        @param nodeIdentifier: The identifier of the node to retract items
502                               from.
503        @type nodeIdentifier: C{unicode}
504        """
505
506    def purge(requestor, service, nodeIdentifier):
507        """
508        Called when a node purge request has been received.
509
510        @param requestor: The entity the request originated from.
511        @type requestor: L{jid.JID}
512        @param service: The entity the request was addressed to.
513        @type service: L{jid.JID}
514        @param nodeIdentifier: The identifier of the node to be purged.
515        @type nodeIdentifier: C{unicode}
516        """
517
518    def delete(requestor, service, nodeIdentifier):
519        """
520        Called when a node deletion request has been received.
521
522        @param requestor: The entity the request originated from.
523        @type requestor: L{jid.JID}
524        @param service: The entity the request was addressed to.
525        @type service: L{jid.JID}
526        @param nodeIdentifier: The identifier of the node to be delete.
527        @type nodeIdentifier: C{unicode}
528        """
Note: See TracBrowser for help on using the repository browser.