source: wokkel/iwokkel.py @ 240:3a201c5b385f

Last change on this file since 240:3a201c5b385f was 240:3a201c5b385f, checked in by Ralph Meijer <ralphm@…>, 3 years ago

Use incremental instead of t.p.versions everywhere

twisted.python.versions is a precursor of the incremental library
but isn't fully API compatible. This caused breakage with older Twisted
versions. Switching to incremental everywhere resolves this. Also fix
the version to at least 16.9.0, which introduced the release_candidate
parameter.

  • Property exe set to *
File size: 35.4 KB
Line 
1# -*- test-case-name: wokkel.test.test_iwokkel -*-
2#
3# Copyright (c) Ralph Meijer.
4# See LICENSE for details.
5
6"""
7Wokkel interfaces.
8"""
9
10from __future__ import division, absolute_import
11
12from zope.interface import Interface
13from twisted.python.deprecate import deprecatedModuleAttribute
14from twisted.words.protocols.jabber.ijabber import IXMPPHandler
15from twisted.words.protocols.jabber.ijabber import IXMPPHandlerCollection
16
17from incremental import Version
18
19deprecatedModuleAttribute(
20        Version("wokkel", 0, 7, 0),
21        "Use twisted.words.protocols.jabber.ijabber.IXMPPHandler instead.",
22        __name__,
23        "IXMPPHandler")
24
25deprecatedModuleAttribute(
26        Version("wokkel", 0, 7, 0),
27        "Use twisted.words.protocols.jabber.ijabber.IXMPPHandlerCollection "
28                "instead.",
29        __name__,
30        "IXMPPHandlerCollection")
31
32
33class IDisco(Interface):
34    """
35    Interface for XMPP service discovery.
36    """
37
38    def getDiscoInfo(requestor, target, nodeIdentifier=''):
39        """
40        Get identity and features from this entity, node.
41
42        @param requestor: The entity the request originated from.
43        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
44        @param target: The target entity to which the request is made.
45        @type target: L{JID<twisted.words.protocols.jabber.jid.JID>}
46        @param nodeIdentifier: The optional identifier of the node at this
47            entity to retrieve the identify and features of.  The default is
48            C{''}, meaning the root node.
49        @type nodeIdentifier: C{unicode}
50        """
51
52    def getDiscoItems(requestor, target, nodeIdentifier=''):
53        """
54        Get contained items for this entity, node.
55
56        @param requestor: The entity the request originated from.
57        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
58        @param target: The target entity to which the request is made.
59        @type target: L{JID<twisted.words.protocols.jabber.jid.JID>}
60        @param nodeIdentifier: The optional identifier of the node at this
61                               entity to retrieve the identify and features of.
62                               The default is C{''}, meaning the root node.
63        @type nodeIdentifier: C{unicode}
64        """
65
66
67
68class IPubSubClient(Interface):
69
70    def itemsReceived(event):
71        """
72        Called when an items notification has been received for a node.
73
74        An item can be an element named C{item} or C{retract}. Respectively,
75        they signal an item being published or retracted, optionally
76        accompanied with an item identifier in the C{id} attribute.
77
78        @param event: The items event.
79        @type event: L{ItemsEvent<wokkel.pubsub.ItemsEvent>}
80        """
81
82
83    def deleteReceived(event):
84        """
85        Called when a deletion notification has been received for a node.
86
87        @param event: The items event.
88        @type event: L{ItemsEvent<wokkel.pubsub.DeleteEvent>}
89        """
90
91
92    def purgeReceived(event):
93        """
94        Called when a purge notification has been received for a node.
95
96        Upon receiving this notification all items associated should be
97        considered retracted.
98
99        @param event: The items event.
100        @type event: L{ItemsEvent<wokkel.pubsub.PurgeEvent>}
101        """
102
103    def createNode(service, nodeIdentifier=None):
104        """
105        Create a new publish subscribe node.
106
107        @param service: The publish-subscribe service entity.
108        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
109        @param nodeIdentifier: Optional suggestion for the new node's
110                               identifier. If omitted, the creation of an
111                               instant node will be attempted.
112        @type nodeIdentifier: C{unicode}
113        @return: a deferred that fires with the identifier of the newly created
114                 node. Note that this can differ from the suggested identifier
115                 if the publish subscribe service chooses to modify or ignore
116                 the suggested identifier.
117        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
118        """
119
120    def deleteNode(service, nodeIdentifier):
121        """
122        Delete a node.
123
124        @param service: The publish-subscribe service entity.
125        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
126        @param nodeIdentifier: Identifier of the node to be deleted.
127        @type nodeIdentifier: C{unicode}
128        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
129        """
130
131    def subscribe(service, nodeIdentifier, subscriber):
132        """
133        Subscribe to a node with a given JID.
134
135        @param service: The publish-subscribe service entity.
136        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
137        @param nodeIdentifier: Identifier of the node to subscribe to.
138        @type nodeIdentifier: C{unicode}
139        @param subscriber: JID to subscribe to the node.
140        @type subscriber: L{JID<twisted.words.protocols.jabber.jid.JID>}
141        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
142        """
143
144    def unsubscribe(service, nodeIdentifier, subscriber):
145        """
146        Unsubscribe from a node with a given JID.
147
148        @param service: The publish-subscribe service entity.
149        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
150        @param nodeIdentifier: Identifier of the node to unsubscribe from.
151        @type nodeIdentifier: C{unicode}
152        @param subscriber: JID to unsubscribe from the node.
153        @type subscriber: L{JID<twisted.words.protocols.jabber.jid.JID>}
154        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
155        """
156
157    def publish(service, nodeIdentifier, items=[]):
158        """
159        Publish to a node.
160
161        Node that the C{items} parameter is optional, because so-called
162        transient, notification-only nodes do not use items and publish
163        actions only signify a change in some resource.
164
165        @param service: The publish-subscribe service entity.
166        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
167        @param nodeIdentifier: Identifier of the node to publish to.
168        @type nodeIdentifier: C{unicode}
169        @param items: List of item elements.
170        @type items: C{list} of L{Item}
171        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
172        """
173
174
175
176class IPubSubService(Interface):
177    """
178    Interface for an XMPP Publish Subscribe Service.
179
180    All methods that are called as the result of an XMPP request are to
181    return a deferred that fires when the requested action has been performed.
182    Alternatively, exceptions maybe raised directly or by calling C{errback}
183    on the returned deferred.
184    """
185
186    def notifyPublish(service, nodeIdentifier, notifications):
187        """
188        Send out notifications for a publish event.
189
190        @param service: The entity the notifications will originate from.
191        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
192        @param nodeIdentifier: The identifier of the node that was published
193            to.
194        @type nodeIdentifier: C{unicode}
195        @param notifications: The notifications as tuples of subscriber, the
196            list of subscriptions and the list of items to be notified.
197        @type notifications: C{list} of
198            (L{JID<twisted.words.protocols.jabber.jid.JID>}, C{list} of
199            L{Subscription<wokkel.pubsub.Subscription>}, C{list} of
200            L{Element<twisted.words.xish.domish.Element>})
201        """
202
203
204    def notifyDelete(service, nodeIdentifier, subscribers,
205                     redirectURI=None):
206        """
207        Send out node deletion notifications.
208
209        @param service: The entity the notifications will originate from.
210        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
211        @param nodeIdentifier: The identifier of the node that was deleted.
212        @type nodeIdentifier: C{unicode}
213        @param subscribers: The subscribers for which a notification should be
214            sent out.
215        @type subscribers: C{list} of
216            L{JID<twisted.words.protocols.jabber.jid.JID>}
217        @param redirectURI: Optional XMPP URI of another node that subscribers
218            are redirected to.
219        @type redirectURI: C{str}
220        """
221
222    def publish(requestor, service, 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<twisted.words.protocols.jabber.jid.JID>}
228        @param service: The entity the request was addressed to.
229        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
230        @param nodeIdentifier: The identifier of the node to publish to.
231        @type nodeIdentifier: C{unicode}
232        @param items: The items to be published as elements.
233        @type items: C{list} of C{Element<twisted.words.xish.domish.Element>}
234        @return: deferred that fires on success.
235        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
236        """
237
238    def subscribe(requestor, service, nodeIdentifier, subscriber):
239        """
240        Called when a subscribe request has been received.
241
242        @param requestor: The entity the request originated from.
243        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
244        @param service: The entity the request was addressed to.
245        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
246        @param nodeIdentifier: The identifier of the node to subscribe to.
247        @type nodeIdentifier: C{unicode}
248        @param subscriber: The entity to be subscribed.
249        @type subscriber: L{JID<twisted.words.protocols.jabber.jid.JID>}
250        @return: A deferred that fires with a
251                 L{Subscription<wokkel.pubsub.Subscription>}.
252        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
253        """
254
255    def unsubscribe(requestor, service, nodeIdentifier, subscriber):
256        """
257        Called when a subscribe request has been received.
258
259        @param requestor: The entity the request originated from.
260        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
261        @param service: The entity the request was addressed to.
262        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
263        @param nodeIdentifier: The identifier of the node to unsubscribe from.
264        @type nodeIdentifier: C{unicode}
265        @param subscriber: The entity to be unsubscribed.
266        @type subscriber: L{JID<twisted.words.protocols.jabber.jid.JID>}
267        @return: A deferred that fires with C{None} when unsubscription has
268                 succeeded.
269        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
270        """
271
272    def subscriptions(requestor, service):
273        """
274        Called when a subscriptions retrieval request has been received.
275
276        @param requestor: The entity the request originated from.
277        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
278        @param service: The entity the request was addressed to.
279        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
280        @return: A deferred that fires with a C{list} of subscriptions as
281                 L{Subscription<wokkel.pubsub.Subscription>}.
282        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
283        """
284
285    def affiliations(requestor, service):
286        """
287        Called when a affiliations retrieval request has been received.
288
289        @param requestor: The entity the request originated from.
290        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
291        @param service: The entity the request was addressed to.
292        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
293        @return: A deferred that fires with a C{list} of affiliations as
294            C{tuple}s of (node identifier as C{unicode}, affiliation state as
295            C{str}). The affiliation can be C{'owner'}, C{'publisher'}, or
296            C{'outcast'}.
297        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
298        """
299
300    def create(requestor, service, nodeIdentifier):
301        """
302        Called when a node creation request has been received.
303
304        @param requestor: The entity the request originated from.
305        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
306        @param service: The entity the request was addressed to.
307        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
308        @param nodeIdentifier: The suggestion for the identifier of the node
309            to be created. If the request did not include a suggestion for the
310            node identifier, the value is C{None}.
311        @type nodeIdentifier: C{unicode} or C{NoneType}
312        @return: A deferred that fires with a C{unicode} that represents
313                 the identifier of the new node.
314        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
315        """
316
317    def getConfigurationOptions():
318        """
319        Retrieve all known node configuration options.
320
321        The returned dictionary holds the possible node configuration options
322        by option name. The value of each entry represents the specifics for
323        that option in a dictionary:
324
325         - C{'type'} (C{str}): The option's type (see
326           L{Field<wokkel.data_form.Field>}'s doc string for possible values).
327         - C{'label'} (C{unicode}): A human readable label for this option.
328         - C{'options'} (C{dict}): Optional list of possible values for this
329           option.
330
331        Example::
332
333            {
334            "pubsub#persist_items":
335                {"type": "boolean",
336                 "label": "Persist items to storage"},
337            "pubsub#deliver_payloads":
338                {"type": "boolean",
339                 "label": "Deliver payloads with event notifications"},
340            "pubsub#send_last_published_item":
341                {"type": "list-single",
342                 "label": "When to send the last published item",
343                 "options": {
344                     "never": "Never",
345                     "on_sub": "When a new subscription is processed"}
346                }
347            }
348
349        @rtype: C{dict}.
350        """
351
352    def getDefaultConfiguration(requestor, service, nodeType):
353        """
354        Called when a default node configuration request has been received.
355
356        @param requestor: The entity the request originated from.
357        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
358        @param service: The entity the request was addressed to.
359        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
360        @param nodeType: The type of node for which the configuration is
361                         retrieved, C{'leaf'} or C{'collection'}.
362        @type nodeType: C{str}
363        @return: A deferred that fires with a C{dict} representing the default
364                 node configuration. Keys are C{str}s that represent the
365                 field name. Values can be of types C{unicode}, C{int} or
366                 C{bool}.
367        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
368        """
369
370    def getConfiguration(requestor, service, nodeIdentifier):
371        """
372        Called when a node configuration retrieval request has been received.
373
374        @param requestor: The entity the request originated from.
375        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
376        @param service: The entity the request was addressed to.
377        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
378        @param nodeIdentifier: The identifier of the node to retrieve the
379                               configuration from.
380        @type nodeIdentifier: C{unicode}
381        @return: A deferred that fires with a C{dict} representing the node
382            configuration. Keys are C{str}s that represent the field name.
383            Values can be of types C{unicode}, C{int} or C{bool}.
384        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
385        """
386
387    def setConfiguration(requestor, service, nodeIdentifier, options):
388        """
389        Called when a node configuration change request has been received.
390
391        @param requestor: The entity the request originated from.
392        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
393        @param service: The entity the request was addressed to.
394        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
395        @param nodeIdentifier: The identifier of the node to change the
396                               configuration of.
397        @type nodeIdentifier: C{unicode}
398        @return: A deferred that fires with C{None} when the node's
399                 configuration has been changed.
400        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
401        """
402
403    def items(requestor, service, nodeIdentifier, maxItems, itemIdentifiers):
404        """
405        Called when a items retrieval request has been received.
406
407        @param requestor: The entity the request originated from.
408        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
409        @param service: The entity the request was addressed to.
410        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
411        @param nodeIdentifier: The identifier of the node to retrieve items
412                               from.
413        @type nodeIdentifier: C{unicode}
414        """
415
416    def retract(requestor, service, nodeIdentifier, itemIdentifiers):
417        """
418        Called when a item retraction request has been received.
419
420        @param requestor: The entity the request originated from.
421        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
422        @param service: The entity the request was addressed to.
423        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
424        @param nodeIdentifier: The identifier of the node to retract items
425                               from.
426        @type nodeIdentifier: C{unicode}
427        """
428
429    def purge(requestor, service, nodeIdentifier):
430        """
431        Called when a node purge request has been received.
432
433        @param requestor: The entity the request originated from.
434        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
435        @param service: The entity the request was addressed to.
436        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
437        @param nodeIdentifier: The identifier of the node to be purged.
438        @type nodeIdentifier: C{unicode}
439        """
440
441    def delete(requestor, service, nodeIdentifier):
442        """
443        Called when a node deletion request has been received.
444
445        @param requestor: The entity the request originated from.
446        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
447        @param service: The entity the request was addressed to.
448        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
449        @param nodeIdentifier: The identifier of the node to be delete.
450        @type nodeIdentifier: C{unicode}
451        """
452
453
454
455class IPubSubResource(Interface):
456
457    def locateResource(request):
458        """
459        Locate a resource that will handle the request.
460
461        @param request: The publish-subscribe request.
462        @type request: L{wokkel.pubsub.PubSubRequest}
463        """
464
465
466    def getInfo(requestor, service, nodeIdentifier):
467        """
468        Get node type and meta data.
469
470        @param requestor: The entity the request originated from.
471        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
472        @param service: The publish-subscribe service entity.
473        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
474        @param nodeIdentifier: Identifier of the node to request the info for.
475        @type nodeIdentifier: C{unicode}
476        @return: A deferred that fires with a dictionary. If not empty,
477                 it must have the keys C{'type'} and C{'meta-data'} to keep
478                 respectively the node type and a dictionary with the meta
479                 data for that node.
480        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
481        """
482
483
484    def getNodes(requestor, service, nodeIdentifier):
485        """
486        Get all nodes contained by this node.
487
488        @param requestor: The entity the request originated from.
489        @type requestor: L{JID<twisted.words.protocols.jabber.jid.JID>}
490        @param service: The publish-subscribe service entity.
491        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
492        @param nodeIdentifier: Identifier of the node to request the childs
493            for.
494        @type nodeIdentifier: C{unicode}
495        @return: A deferred that fires with a list of child node identifiers.
496        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
497        """
498
499
500    def getConfigurationOptions():
501        """
502        Retrieve all known node configuration options.
503
504        The returned dictionary holds the possible node configuration options
505        by option name. The value of each entry represents the specifics for
506        that option in a dictionary:
507
508         - C{'type'} (C{str}): The option's type (see
509           L{Field<wokkel.data_form.Field>}'s doc string for possible values).
510         - C{'label'} (C{unicode}): A human readable label for this option.
511         - C{'options'} (C{dict}): Optional list of possible values for this
512           option.
513
514        Example::
515
516            {
517            "pubsub#persist_items":
518                {"type": "boolean",
519                 "label": "Persist items to storage"},
520            "pubsub#deliver_payloads":
521                {"type": "boolean",
522                 "label": "Deliver payloads with event notifications"},
523            "pubsub#send_last_published_item":
524                {"type": "list-single",
525                 "label": "When to send the last published item",
526                 "options": {
527                     "never": "Never",
528                     "on_sub": "When a new subscription is processed"}
529                }
530            }
531
532        @rtype: C{dict}.
533        """
534
535
536    def publish(request):
537        """
538        Called when a publish request has been received.
539
540        @param request: The publish-subscribe request.
541        @type request: L{wokkel.pubsub.PubSubRequest}
542        @return: deferred that fires on success.
543        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
544        """
545
546
547    def subscribe(request):
548        """
549        Called when a subscribe request has been received.
550
551        @param request: The publish-subscribe request.
552        @type request: L{wokkel.pubsub.PubSubRequest}
553        @return: A deferred that fires with a
554                 L{Subscription<wokkel.pubsub.Subscription>}.
555        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
556        """
557
558
559    def unsubscribe(request):
560        """
561        Called when a subscribe request has been received.
562
563        @param request: The publish-subscribe request.
564        @type request: L{wokkel.pubsub.PubSubRequest}
565        @return: A deferred that fires with C{None} when unsubscription has
566                 succeeded.
567        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
568        """
569
570
571    def subscriptions(request):
572        """
573        Called when a subscriptions retrieval request has been received.
574
575        @param request: The publish-subscribe request.
576        @type request: L{wokkel.pubsub.PubSubRequest}
577        @return: A deferred that fires with a C{list} of subscriptions as
578                 L{Subscription<wokkel.pubsub.Subscription>}.
579        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
580        """
581
582
583    def affiliations(request):
584        """
585        Called when a affiliations retrieval request has been received.
586
587        @param request: The publish-subscribe request.
588        @type request: L{wokkel.pubsub.PubSubRequest}
589        @return: A deferred that fires with a C{list} of affiliations as
590            C{tuple}s of (node identifier as C{unicode}, affiliation state as
591            C{str}). The affiliation can be C{'owner'}, C{'publisher'}, or
592            C{'outcast'}.
593        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
594        """
595
596
597    def create(request):
598        """
599        Called when a node creation request has been received.
600
601        @param request: The publish-subscribe request.
602        @type request: L{wokkel.pubsub.PubSubRequest}
603        @return: A deferred that fires with a C{unicode} that represents
604                 the identifier of the new node.
605        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
606        """
607
608
609    def default(request):
610        """
611        Called when a default node configuration request has been received.
612
613        @param request: The publish-subscribe request.
614        @type request: L{wokkel.pubsub.PubSubRequest}
615        @return: A deferred that fires with a C{dict} representing the default
616                 node configuration. Keys are C{str}s that represent the
617                 field name. Values can be of types C{unicode}, C{int} or
618                 C{bool}.
619        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
620        """
621
622
623    def configureGet(request):
624        """
625        Called when a node configuration retrieval request has been received.
626
627        @param request: The publish-subscribe request.
628        @type request: L{wokkel.pubsub.PubSubRequest}
629        @return: A deferred that fires with a C{dict} representing the node
630            configuration. Keys are C{str}s that represent the field name.
631            Values can be of types C{unicode}, C{int} or C{bool}.
632        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
633        """
634
635
636    def configureSet(request):
637        """
638        Called when a node configuration change request has been received.
639
640        @param request: The publish-subscribe request.
641        @type request: L{wokkel.pubsub.PubSubRequest}
642        @return: A deferred that fires with C{None} when the node's
643                 configuration has been changed.
644        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
645        """
646
647
648    def items(request):
649        """
650        Called when a items retrieval request has been received.
651
652        @param request: The publish-subscribe request.
653        @type request: L{wokkel.pubsub.PubSubRequest}
654        @return: A deferred that fires with a C{list} of L{pubsub.Item}.
655        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
656        """
657
658
659    def retract(request):
660        """
661        Called when a item retraction request has been received.
662
663        @param request: The publish-subscribe request.
664        @type request: L{wokkel.pubsub.PubSubRequest}
665        @return: A deferred that fires with C{None} when the given items have
666                 been retracted.
667        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
668        """
669
670
671    def purge(request):
672        """
673        Called when a node purge request has been received.
674
675        @param request: The publish-subscribe request.
676        @type request: L{wokkel.pubsub.PubSubRequest}
677        @return: A deferred that fires with C{None} when the node has been
678                 purged.
679        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
680        """
681
682
683    def delete(request):
684        """
685        Called when a node deletion request has been received.
686
687        @param request: The publish-subscribe request.
688        @type request: L{wokkel.pubsub.PubSubRequest}
689        @return: A deferred that fires with C{None} when the node has been
690                 deleted.
691        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
692        """
693
694
695    def affiliationsGet(request):
696        """
697        Called when an owner affiliations retrieval request been received.
698
699        @param request: The publish-subscribe request.
700        @type request: L{wokkel.pubsub.PubSubRequest}
701        @return: A deferred that fires with a C{dict} of affiliations with the
702            entity as key (L{JID<twisted.words.protocols.jabber.jid.JID>}) and
703            the affiliation state as value (C{unicode}).  The affiliation can
704            be C{u'owner'}, C{u'publisher'}, or C{u'outcast'}.
705        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
706
707        @note: Affiliations are always on the bare JID. An implementation of
708        this method MUST NOT return JIDs with a resource part.
709        """
710
711
712    def affiliationsSet(request):
713        """
714        Called when a affiliations modify request has been received.
715
716        @param request: The publish-subscribe request.
717        @type request: L{wokkel.pubsub.PubSubRequest}
718
719        @return: A deferred that fires with C{None} when the affiliation
720            changes were succesfully processed..
721        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
722
723        @note: Affiliations are always on the bare JID. The JIDs in
724            L{wokkel.pubsub.PubSubRequest}'s C{affiliations} attribute are
725            already stripped of any resource.
726        """
727
728
729
730class IMUCClient(Interface):
731    """
732    Multi-User Chat Client.
733
734    A client interface to XEP-045 : http://xmpp.org/extensions/xep-0045.html
735    """
736
737    def receivedSubject(room, user, subject):
738        """
739        The room subject has been received.
740
741        A subject is received when you join a room and when the subject is
742        changed.
743
744        @param room: The room the subject was accepted for.
745        @type room: L{muc.Room}
746
747        @param user: The user that set the subject.
748        @type  user: L{muc.User}
749
750        @param subject: The subject of the given room.
751        @type subject: C{unicode}
752        """
753
754
755    def receivedHistory(room, user, message):
756        """
757        Past messages from a chat room have been received.
758
759        This occurs when you join a room.
760        """
761
762
763    def configure(roomJID, options):
764        """
765        Configure a room.
766
767        @param roomJID: The room to configure.
768        @type roomJID: L{JID<twisted.words.protocols.jabber.jid.JID>}
769
770        @param options: A mapping of field names to values, or C{None} to
771            cancel.
772        @type options: C{dict}
773        """
774
775
776    def getConfiguration(roomJID):
777        """
778        Grab the configuration from the room.
779
780        This sends an iq request to the room.
781
782        @param roomJID: The bare JID of the room.
783        @type roomJID: L{JID<twisted.words.protocols.jabber.jid.JID>}
784
785        @return: A deferred that fires with the room's configuration form as
786            a L{data_form.Form} or C{None} if there are no configuration
787            options available.
788        """
789
790
791    def join(roomJID, nick, historyOptions=None, password=None):
792        """
793        Join a MUC room by sending presence to it.
794
795        @param roomJID: The JID of the room the entity is joining.
796        @type roomJID: L{JID<twisted.words.protocols.jabber.jid.JID>}
797
798        @param nick: The nick name for the entitity joining the room.
799        @type nick: C{unicode}
800
801        @param historyOptions: Options for conversation history sent by the
802            room upon joining.
803        @type historyOptions: L{HistoryOptions}
804
805        @param password: Optional password for the room.
806        @type password: C{unicode}
807
808        @return: A deferred that fires when the entity is in the room or an
809                 error has occurred.
810        """
811
812
813    def nick(roomJID, nick):
814        """
815        Change an entity's nick name in a MUC room.
816
817        See: http://xmpp.org/extensions/xep-0045.html#changenick
818
819        @param roomJID: The JID of the room, i.e. without a resource.
820        @type roomJID: L{JID<twisted.words.protocols.jabber.jid.JID>}
821
822        @param nick: The new nick name within the room.
823        @type nick: C{unicode}
824        """
825
826
827    def leave(roomJID):
828        """
829        Leave a MUC room.
830
831        See: http://xmpp.org/extensions/xep-0045.html#exit
832
833        @param roomJID: The Room JID of the room to leave.
834        @type roomJID: L{JID<twisted.words.protocols.jabber.jid.JID>}
835        """
836
837
838    def userJoinedRoom(room, user):
839        """
840        User has joined a MUC room.
841
842        This method will need to be modified inorder for clients to
843        do something when this event occurs.
844
845        @param room: The room the user joined.
846        @type  room: L{muc.Room}
847
848        @param user: The user that joined the room.
849        @type  user: L{muc.User}
850        """
851
852
853    def groupChat(roomJID, body):
854        """
855        Send a groupchat message.
856        """
857
858
859    def chat(occupantJID, body):
860        """
861        Send a private chat message to a user in a MUC room.
862
863        See: http://xmpp.org/extensions/xep-0045.html#privatemessage
864
865        @param occupantJID: The Room JID of the other user.
866        @type occupantJID: L{JID<twisted.words.protocols.jabber.jid.JID>}
867        """
868
869
870    def register(roomJID, options):
871        """
872        Send a request to register for a room.
873
874        @param roomJID: The bare JID of the room.
875        @type roomJID: L{JID<twisted.words.protocols.jabber.jid.JID>}
876
877        @param options: A mapping of field names to values, or C{None} to
878            cancel.
879        @type options: C{dict}
880        """
881
882
883    def subject(roomJID, subject):
884        """
885        Change the subject of a MUC room.
886
887        See: http://xmpp.org/extensions/xep-0045.html#subject-mod
888
889        @param roomJID: The bare JID of the room.
890        @type roomJID: L{JID<twisted.words.protocols.jabber.jid.JID>}
891
892        @param subject: The subject you want to set.
893        @type subject: C{unicode}
894        """
895
896
897    def voice(roomJID):
898        """
899        Request voice for a moderated room.
900
901        @param roomJID: The room jabber/xmpp entity id.
902        @type roomJID: L{JID<twisted.words.protocols.jabber.jid.JID>}
903        """
904
905
906    def history(roomJID, messages):
907        """
908        Send history to create a MUC based on a one on one chat.
909
910        See: http://xmpp.org/extensions/xep-0045.html#continue
911
912        @param roomJID: The room jabber/xmpp entity id.
913        @type roomJID: L{JID<twisted.words.protocols.jabber.jid.JID>}
914
915        @param messages: The history to send to the room as an ordered list of
916            message, represented by a dictionary with the keys C{'stanza'},
917            holding the original stanza a
918            L{Element<twisted.words.xish.domish.Element>}, and C{'timestamp'}
919            with the timestamp.
920        @type messages: C{list} of
921            L{Element<twisted.words.xish.domish.Element>}
922        """
923
924
925    def ban(roomJID, entity, reason=None, sender=None):
926        """
927        Ban a user from a MUC room.
928
929        @param roomJID: The bare JID of the room.
930        @type roomJID: L{JID<twisted.words.protocols.jabber.jid.JID>}
931
932        @param entity: The bare JID of the entity to be banned.
933        @type entity: L{JID<twisted.words.protocols.jabber.jid.JID>}
934
935        @param reason: The reason for banning the entity.
936        @type reason: C{unicode}
937
938        @param sender: The entity sending the request.
939        @type sender: L{JID<twisted.words.protocols.jabber.jid.JID>}
940        """
941
942
943    def kick(roomJID, nick, reason=None, sender=None):
944        """
945        Kick a user from a MUC room.
946
947        @param roomJID: The bare JID of the room.
948        @type roomJID: L{JID<twisted.words.protocols.jabber.jid.JID>}
949
950        @param nick: The occupant to be banned.
951        @type nick: L{JID<twisted.words.protocols.jabber.jid.JID>} or
952            C{unicode}
953
954        @param reason: The reason given for the kick.
955        @type reason: C{unicode}
956
957        @param sender: The entity sending the request.
958        @type sender: L{JID<twisted.words.protocols.jabber.jid.JID>}
959        """
960
961
962
963class IMUCStatuses(Interface):
964    """
965    Interface for a container of Multi-User Chat status conditions.
966    """
967
968    def __contains__(key):
969        """
970        Return if a status exists in the container.
971        """
972
973
974    def __iter__():
975        """
976        Return an iterator over the status codes.
977        """
978
979
980    def __len__():
981        """
982        Return the number of status conditions.
983        """
984
985
986
987__all__ = ['IXMPPHandler', 'IXMPPHandlerCollection',
988           'IPubSubClient', 'IPubSubService', 'IPubSubResource',
989           'IMUCClient', 'IMUCStatuses']
Note: See TracBrowser for help on using the repository browser.