source: wokkel/iwokkel.py

Last change on this file was 193:2b4214c8f5de, checked in by Ralph Meijer <ralphm@…>, 2 years ago

imported patch py3-iwokkel.patch

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