source: wokkel/iwokkel.py @ 166:d9c10a5b5c0d

Last change on this file since 166:d9c10a5b5c0d was 166:d9c10a5b5c0d, checked in by Ralph Meijer <ralphm@…>, 8 years ago

Documentation fixes for pydoctor.

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