source: wokkel/iwokkel.py @ 165:76a61f5aa343

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

Cleanups leading up to Wokkel 0.7.0.

As we now depend on Twisted 10.0.0 or higher, the following classes and
interfaces were deprecated:

This also resolves all Pyflakes warnings, changes links for www.xmpp.org to
xmpp.org and fixes the copyright notice in LICENSE to include 2012.

  • Property exe set to *
File size: 32.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.JID}
45        @param target: The target entity to which the request is made.
46        @type target: L{jid.JID}
47        @param nodeIdentifier: The optional identifier of the node at this
48                               entity to retrieve the identify and features of.
49                               The default is 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.JID}
59        @param target: The target entity to which the request is made.
60        @type target: L{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.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: L{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{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.JID}
127        @param nodeIdentifier: Identifier of the node to be deleted.
128        @type nodeIdentifier: L{unicode}
129        @rtype: L{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.JID}
138        @param nodeIdentifier: Identifier of the node to subscribe to.
139        @type nodeIdentifier: L{unicode}
140        @param subscriber: JID to subscribe to the node.
141        @type subscriber: L{jid.JID}
142        @rtype: L{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.JID}
151        @param nodeIdentifier: Identifier of the node to unsubscribe from.
152        @type nodeIdentifier: L{unicode}
153        @param subscriber: JID to unsubscribe from the node.
154        @type subscriber: L{jid.JID}
155        @rtype: L{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.JID}
168        @param nodeIdentifier: Identifier of the node to publish to.
169        @type nodeIdentifier: L{unicode}
170        @param items: List of item elements.
171        @type items: L{list} of L{Item}
172        @rtype: L{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.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
198                              notified.
199        @type notifications: C{list} of (L{jid.JID}, C{list} of
200                             L{Subscription<wokkel.pubsub.Subscription>},
201                             C{list} of L{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.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
215                            be sent out.
216        @type subscribers: C{list} of L{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.JID}
228        @param service: The entity the request was addressed to.
229        @type service: L{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 L{domish} elements.
233        @type items: C{list} of C{domish.Element}
234        @return: deferred that fires on success.
235        @rtype: L{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.JID}
244        @param service: The entity the request was addressed to.
245        @type service: L{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.JID}
250        @return: A deferred that fires with a
251                 L{Subscription<wokkel.pubsub.Subscription>}.
252        @rtype: L{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.JID}
261        @param service: The entity the request was addressed to.
262        @type service: L{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.JID}
267        @return: A deferred that fires with C{None} when unsubscription has
268                 succeeded.
269        @rtype: L{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.JID}
278        @param service: The entity the request was addressed to.
279        @type service: L{jid.JID}
280        @return: A deferred that fires with a C{list} of subscriptions as
281                 L{Subscription<wokkel.pubsub.Subscription>}.
282        @rtype: L{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.JID}
291        @param service: The entity the request was addressed to.
292        @type service: L{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
295                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
296                 or C{'outcast'}.
297        @rtype: L{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.JID}
306        @param service: The entity the request was addressed to.
307        @type service: L{jid.JID}
308        @param nodeIdentifier: The suggestion for the identifier of the node to
309                               be created. If the request did not include a
310                               suggestion for the node identifier, the value
311                               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{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.JID}
359        @param service: The entity the request was addressed to.
360        @type service: L{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{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.JID}
377        @param service: The entity the request was addressed to.
378        @type service: L{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{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.JID}
394        @param service: The entity the request was addressed to.
395        @type service: L{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{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.JID}
410        @param service: The entity the request was addressed to.
411        @type service: L{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.JID}
423        @param service: The entity the request was addressed to.
424        @type service: L{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.JID}
436        @param service: The entity the request was addressed to.
437        @type service: L{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.JID}
448        @param service: The entity the request was addressed to.
449        @type service: L{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.JID}
473        @param service: The publish-subscribe service entity.
474        @type service: L{jid.JID}
475        @param nodeIdentifier: Identifier of the node to request the info for.
476        @type nodeIdentifier: L{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{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.JID}
491        @param service: The publish-subscribe service entity.
492        @type service: L{jid.JID}
493        @param nodeIdentifier: Identifier of the node to request the childs for.
494        @type nodeIdentifier: L{unicode}
495        @return: A deferred that fires with a list of child node identifiers.
496        @rtype: L{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{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{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{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{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
591                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
592                 or C{'outcast'}.
593        @rtype: L{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{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{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{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{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{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{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{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{defer.Deferred}
692        """
693
694
695    def affiliationsGet(request):
696        """
697        Called when a affiliations retrieval request (owner) has 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}) and the affiliation state as value
703            (C{unicode}).  The affiliation can be C{u'owner'}, C{u'publisher'},
704            or C{u'outcast'}.
705        @rtype: L{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        @return: A deferred that fires with C{None} when the affiliation
719            changes were succesfully processed..
720        @rtype: L{defer.Deferred}
721
722        @note: Affiliations are always on the bare JID. The JIDs in
723        L{wokkel.pubsub.PubSubRequest.affiliations} are already stripped of
724        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        A subject is received when you join a room and when the subject is changed. This
739        method is triggered by one of those two events.
740
741        @param room: The room the subject was accepted for.
742        @type room: L{muc.Room}
743
744        @param user: The user that set the subject.
745        @type  user: L{muc.User}
746
747        @param subject: The subject of the given room.
748        @type subject: C{unicode}
749        """
750
751
752    def receivedHistory(room, user, message):
753        """
754        Past messages from a chat room has been received. This occurs when you join a room.
755        """
756
757
758    def configure(roomJID, options):
759        """
760        Configure a room.
761
762        @param roomJID: The room to configure.
763        @type roomJID: L{jid.JID}
764
765        @param options: A mapping of field names to values, or C{None} to cancel.
766        @type options: C{dict}
767        """
768
769
770    def getConfiguration(roomJID):
771        """
772        Grab the configuration from the room.
773
774        This sends an iq request to the room.
775
776        @param roomJID: The bare JID of the room.
777        @type roomJID: L{jid.JID}
778
779        @return: A deferred that fires with the room's configuration form as
780            a L{data_form.Form} or C{None} if there are no configuration
781            options available.
782        """
783
784
785    def join(roomJID, nick, historyOptions=None, password=None):
786        """
787        Join a MUC room by sending presence to it.
788
789        @param roomJID: The JID of the room the entity is joining.
790        @type roomJID: L{jid.JID}
791
792        @param nick: The nick name for the entitity joining the room.
793        @type nick: C{unicode}
794
795        @param historyOptions: Options for conversation history sent by the
796            room upon joining.
797        @type historyOptions: L{HistoryOptions}
798
799        @param password: Optional password for the room.
800        @type password: C{unicode}
801
802        @return: A deferred that fires when the entity is in the room or an
803                 error has occurred.
804        """
805
806
807    def nick(roomJID, nick):
808        """
809        Change an entity's nick name in a MUC room.
810
811        See: http://xmpp.org/extensions/xep-0045.html#changenick
812
813        @param roomJID: The JID of the room, i.e. without a resource.
814        @type roomJID: L{jid.JID}
815
816        @param nick: The new nick name within the room.
817        @type nick: C{unicode}
818        """
819
820
821    def leave(roomJID):
822        """
823        Leave a MUC room.
824
825        See: http://xmpp.org/extensions/xep-0045.html#exit
826
827        @param roomJID: The Room JID of the room to leave.
828        @type roomJID: L{jid.JID}
829        """
830
831
832    def userJoinedRoom(room, user):
833        """
834        User has joined a MUC room.
835
836        This method will need to be modified inorder for clients to
837        do something when this event occurs.
838
839        @param room: The room the user joined.
840        @type  room: L{muc.Room}
841
842        @param user: The user that joined the room.
843        @type  user: L{muc.User}
844        """
845
846
847    def groupChat(roomJID, body):
848        """
849        Send a groupchat message.
850        """
851
852
853    def chat(occupantJID, body):
854        """
855        Send a private chat message to a user in a MUC room.
856
857        See: http://xmpp.org/extensions/xep-0045.html#privatemessage
858
859        @param occupantJID: The Room JID of the other user.
860        @type occupantJID: L{jid.JID}
861        """
862
863
864    def register(roomJID, options):
865        """
866        Send a request to register for a room.
867
868        @param roomJID: The bare JID of the room.
869        @type roomJID: L{jid.JID}
870
871        @param options: A mapping of field names to values, or C{None} to
872            cancel.
873        @type options: C{dict}
874        """
875
876
877    def subject(roomJID, subject):
878        """
879        Change the subject of a MUC room.
880
881        See: http://xmpp.org/extensions/xep-0045.html#subject-mod
882
883        @param roomJID: The bare JID of the room.
884        @type roomJID: L{jid.JID}
885
886        @param subject: The subject you want to set.
887        @type subject: C{unicode}
888        """
889
890
891    def voice(roomJID):
892        """
893        Request voice for a moderated room.
894
895        @param roomJID: The room jabber/xmpp entity id.
896        @type roomJID: L{jid.JID}
897        """
898
899
900    def history(roomJID, messages):
901        """
902        Send history to create a MUC based on a one on one chat.
903
904        See: http://xmpp.org/extensions/xep-0045.html#continue
905
906        @param roomJID: The room jabber/xmpp entity id.
907        @type roomJID: L{jid.JID}
908
909        @param messages: The history to send to the room as an ordered list of
910                         message, represented by a dictionary with the keys
911                         C{'stanza'}, holding the original stanza a
912                         L{domish.Element}, and C{'timestamp'} with the
913                         timestamp.
914        @type messages: L{list} of L{domish.Element}
915        """
916
917
918    def ban(roomJID, entity, reason=None, sender=None):
919        """
920        Ban a user from a MUC room.
921
922        @param roomJID: The bare JID of the room.
923        @type roomJID: L{jid.JID}
924
925        @param entity: The bare JID of the entity to be banned.
926        @type entity: L{jid.JID}
927
928        @param reason: The reason for banning the entity.
929        @type reason: C{unicode}
930
931        @param sender: The entity sending the request.
932        @type sender: L{jid.JID}
933        """
934
935
936    def kick(roomJID, nick, reason=None, sender=None):
937        """
938        Kick a user from a MUC room.
939
940        @param roomJID: The bare JID of the room.
941        @type roomJID: L{jid.JID}
942
943        @param nick: The occupant to be banned.
944        @type nick: L{jid.JID} or C{unicode}
945
946        @param reason: The reason given for the kick.
947        @type reason: C{unicode}
948
949        @param sender: The entity sending the request.
950        @type sender: L{jid.JID}
951        """
952
953
954
955class IMUCStatuses(Interface):
956    """
957    Interface for a container of Multi-User Chat status conditions.
958    """
959
960    def __contains__(key):
961        """
962        Return if a status exists in the container.
963        """
964
965
966    def __iter__():
967        """
968        Return an iterator over the status codes.
969        """
970
971
972    def __len__():
973        """
974        Return the number of status conditions.
975        """
Note: See TracBrowser for help on using the repository browser.