source: wokkel/iwokkel.py @ 113:cb4051e2f51a

wokkel-muc-client-support-24
Last change on this file since 113:cb4051e2f51a was 113:cb4051e2f51a, checked in by Christopher Zorn <tofu@…>, 12 years ago

some documentation and additions to the interface, also some more abstraction and tests

File size: 21.3 KB
Line 
1# Copyright (c) 2003-2008 Ralph Meijer
2# See LICENSE for details.
3
4"""
5Wokkel interfaces.
6"""
7
8from zope.interface import Attribute, Interface
9
10class IXMPPHandler(Interface):
11    """
12    Interface for XMPP protocol handlers.
13
14    Objects that provide this interface can be added to a stream manager to
15    handle of (part of) an XMPP extension protocol.
16    """
17
18    manager = Attribute("""XML stream manager""")
19    xmlstream = Attribute("""The managed XML stream""")
20
21    def setHandlerParent(parent):
22        """
23        Set the parent of the handler.
24
25        @type parent: L{IXMPPHandlerCollection}
26        """
27
28    def disownHandlerParent(parent):
29        """
30        Remove the parent of the handler.
31
32        @type parent: L{IXMPPHandlerCollection}
33        """
34
35    def makeConnection(xs):
36        """
37        A connection over the underlying transport of the XML stream has been
38        established.
39
40        At this point, no traffic has been exchanged over the XML stream
41        given in C{xs}.
42
43        This should setup L{xmlstream} and call L{connectionMade}.
44
45        @type xs: L{XmlStream<twisted.words.protocols.jabber.XmlStream>}
46        """
47
48    def connectionMade():
49        """
50        Called after a connection has been established.
51
52        This method can be used to change properties of the XML Stream, its
53        authenticator or the stream manager prior to stream initialization
54        (including authentication).
55        """
56
57    def connectionInitialized():
58        """
59        The XML stream has been initialized.
60
61        At this point, authentication was successful, and XML stanzas can be
62        exchanged over the XML stream L{xmlstream}. This method can be
63        used to setup observers for incoming stanzas.
64        """
65
66    def connectionLost(reason):
67        """
68        The XML stream has been closed.
69
70        Subsequent use of L{parent.send} will result in data being queued
71        until a new connection has been established.
72
73        @type reason: L{twisted.python.failure.Failure}
74        """
75
76
77class IXMPPHandlerCollection(Interface):
78    """
79    Collection of handlers.
80
81    Contain several handlers and manage their connection.
82    """
83
84    def __iter__():
85        """
86        Get an iterator over all child handlers.
87        """
88
89    def addHandler(handler):
90        """
91        Add a child handler.
92
93        @type handler: L{IXMPPHandler}
94        """
95
96    def removeHandler(handler):
97        """
98        Remove a child handler.
99
100        @type handler: L{IXMPPHandler}
101        """
102
103
104class IDisco(Interface):
105    """
106    Interface for XMPP service discovery.
107    """
108
109    def getDiscoInfo(requestor, target, nodeIdentifier=''):
110        """
111        Get identity and features from this entity, node.
112
113        @param requestor: The entity the request originated from.
114        @type requestor: L{jid.JID}
115        @param target: The target entity to which the request is made.
116        @type target: L{jid.JID}
117        @param nodeIdentifier: The optional identifier of the node at this
118                               entity to retrieve the identify and features of.
119                               The default is C{''}, meaning the root node.
120        @type nodeIdentifier: C{unicode}
121        """
122
123    def getDiscoItems(requestor, target, nodeIdentifier=''):
124        """
125        Get contained items for this entity, node.
126
127        @param requestor: The entity the request originated from.
128        @type requestor: L{jid.JID}
129        @param target: The target entity to which the request is made.
130        @type target: L{jid.JID}
131        @param nodeIdentifier: The optional identifier of the node at this
132                               entity to retrieve the identify and features of.
133                               The default is C{''}, meaning the root node.
134        @type nodeIdentifier: C{unicode}
135        """
136
137
138class IPubSubClient(Interface):
139
140    def itemsReceived(event):
141        """
142        Called when an items notification has been received for a node.
143
144        An item can be an element named C{item} or C{retract}. Respectively,
145        they signal an item being published or retracted, optionally
146        accompanied with an item identifier in the C{id} attribute.
147
148        @param event: The items event.
149        @type event: L{ItemsEvent<wokkel.pubsub.ItemsEvent>}
150        """
151
152
153    def deleteReceived(event):
154        """
155        Called when a deletion notification has been received for a node.
156
157        @param event: The items event.
158        @type event: L{ItemsEvent<wokkel.pubsub.DeleteEvent>}
159        """
160
161
162    def purgeReceived(event):
163        """
164        Called when a purge notification has been received for a node.
165
166        Upon receiving this notification all items associated should be
167        considered retracted.
168
169        @param event: The items event.
170        @type event: L{ItemsEvent<wokkel.pubsub.PurgeEvent>}
171        """
172
173    def createNode(service, nodeIdentifier=None):
174        """
175        Create a new publish subscribe node.
176
177        @param service: The publish-subscribe service entity.
178        @type service: L{jid.JID}
179        @param nodeIdentifier: Optional suggestion for the new node's
180                               identifier. If omitted, the creation of an
181                               instant node will be attempted.
182        @type nodeIdentifier: L{unicode}
183        @return: a deferred that fires with the identifier of the newly created
184                 node. Note that this can differ from the suggested identifier
185                 if the publish subscribe service chooses to modify or ignore
186                 the suggested identifier.
187        @rtype: L{defer.Deferred}
188        """
189
190    def deleteNode(service, nodeIdentifier):
191        """
192        Delete a node.
193
194        @param service: The publish-subscribe service entity.
195        @type service: L{jid.JID}
196        @param nodeIdentifier: Identifier of the node to be deleted.
197        @type nodeIdentifier: L{unicode}
198        @rtype: L{defer.Deferred}
199        """
200
201    def subscribe(service, nodeIdentifier, subscriber):
202        """
203        Subscribe to a node with a given JID.
204
205        @param service: The publish-subscribe service entity.
206        @type service: L{jid.JID}
207        @param nodeIdentifier: Identifier of the node to subscribe to.
208        @type nodeIdentifier: L{unicode}
209        @param subscriber: JID to subscribe to the node.
210        @type subscriber: L{jid.JID}
211        @rtype: L{defer.Deferred}
212        """
213
214    def unsubscribe(service, nodeIdentifier, subscriber):
215        """
216        Unsubscribe from a node with a given JID.
217
218        @param service: The publish-subscribe service entity.
219        @type service: L{jid.JID}
220        @param nodeIdentifier: Identifier of the node to unsubscribe from.
221        @type nodeIdentifier: L{unicode}
222        @param subscriber: JID to unsubscribe from the node.
223        @type subscriber: L{jid.JID}
224        @rtype: L{defer.Deferred}
225        """
226
227    def publish(service, nodeIdentifier, items=[]):
228        """
229        Publish to a node.
230
231        Node that the C{items} parameter is optional, because so-called
232        transient, notification-only nodes do not use items and publish
233        actions only signify a change in some resource.
234
235        @param service: The publish-subscribe service entity.
236        @type service: L{jid.JID}
237        @param nodeIdentifier: Identifier of the node to publish to.
238        @type nodeIdentifier: L{unicode}
239        @param items: List of item elements.
240        @type items: L{list} of L{Item}
241        @rtype: L{defer.Deferred}
242        """
243
244
245class IPubSubService(Interface):
246    """
247    Interface for an XMPP Publish Subscribe Service.
248
249    All methods that are called as the result of an XMPP request are to
250    return a deferred that fires when the requested action has been performed.
251    Alternatively, exceptions maybe raised directly or by calling C{errback}
252    on the returned deferred.
253    """
254
255    def notifyPublish(service, nodeIdentifier, notifications):
256        """
257        Send out notifications for a publish event.
258
259        @param service: The entity the notifications will originate from.
260        @type service: L{jid.JID}
261        @param nodeIdentifier: The identifier of the node that was published
262                               to.
263        @type nodeIdentifier: C{unicode}
264        @param notifications: The notifications as tuples of subscriber, the
265                              list of subscriptions and the list of items to be
266                              notified.
267        @type notifications: C{list} of (L{jid.JID}, C{list} of
268                             L{Subscription<wokkel.pubsub.Subscription>},
269                             C{list} of L{domish.Element})
270        """
271
272    def notifyDelete(service, nodeIdentifier, subscriptions):
273        """
274        Send out node deletion notifications.
275
276        @param service: The entity the notifications will originate from.
277        @type service: L{jid.JID}
278        @param nodeIdentifier: The identifier of the node that was deleted.
279        @type nodeIdentifier: C{unicode}
280        @param subscriptions: The subscriptions for which a notification should
281                              be sent out.
282        @type subscriptions: C{list} of L{jid.JID}
283        """
284
285    def publish(requestor, service, nodeIdentifier, items):
286        """
287        Called when a publish 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        @param nodeIdentifier: The identifier of the node to publish to.
294        @type nodeIdentifier: C{unicode}
295        @param items: The items to be published as L{domish} elements.
296        @type items: C{list} of C{domish.Element}
297        @return: deferred that fires on success.
298        @rtype: L{defer.Deferred}
299        """
300
301    def subscribe(requestor, service, nodeIdentifier, subscriber):
302        """
303        Called when a subscribe request has been received.
304
305        @param requestor: The entity the request originated from.
306        @type requestor: L{jid.JID}
307        @param service: The entity the request was addressed to.
308        @type service: L{jid.JID}
309        @param nodeIdentifier: The identifier of the node to subscribe to.
310        @type nodeIdentifier: C{unicode}
311        @param subscriber: The entity to be subscribed.
312        @type subscriber: L{jid.JID}
313        @return: A deferred that fires with a
314                 L{Subscription<wokkel.pubsub.Subscription>}.
315        @rtype: L{defer.Deferred}
316        """
317
318    def unsubscribe(requestor, service, nodeIdentifier, subscriber):
319        """
320        Called when a subscribe request has been received.
321
322        @param requestor: The entity the request originated from.
323        @type requestor: L{jid.JID}
324        @param service: The entity the request was addressed to.
325        @type service: L{jid.JID}
326        @param nodeIdentifier: The identifier of the node to unsubscribe from.
327        @type nodeIdentifier: C{unicode}
328        @param subscriber: The entity to be unsubscribed.
329        @type subscriber: L{jid.JID}
330        @return: A deferred that fires with C{None} when unsubscription has
331                 succeeded.
332        @rtype: L{defer.Deferred}
333        """
334
335    def subscriptions(requestor, service):
336        """
337        Called when a subscriptions retrieval request has been received.
338
339        @param requestor: The entity the request originated from.
340        @type requestor: L{jid.JID}
341        @param service: The entity the request was addressed to.
342        @type service: L{jid.JID}
343        @return: A deferred that fires with a C{list} of subscriptions as
344                 L{Subscription<wokkel.pubsub.Subscription>}.
345        @rtype: L{defer.Deferred}
346        """
347
348    def affiliations(requestor, service):
349        """
350        Called when a affiliations retrieval request has been received.
351
352        @param requestor: The entity the request originated from.
353        @type requestor: L{jid.JID}
354        @param service: The entity the request was addressed to.
355        @type service: L{jid.JID}
356        @return: A deferred that fires with a C{list} of affiliations as
357                 C{tuple}s of (node identifier as C{unicode}, affiliation state
358                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
359                 or C{'outcast'}.
360        @rtype: L{defer.Deferred}
361        """
362
363    def create(requestor, service, nodeIdentifier):
364        """
365        Called when a node creation request has been received.
366
367        @param requestor: The entity the request originated from.
368        @type requestor: L{jid.JID}
369        @param service: The entity the request was addressed to.
370        @type service: L{jid.JID}
371        @param nodeIdentifier: The suggestion for the identifier of the node to
372                               be created. If the request did not include a
373                               suggestion for the node identifier, the value
374                               is C{None}.
375        @type nodeIdentifier: C{unicode} or C{NoneType}
376        @return: A deferred that fires with a C{unicode} that represents
377                 the identifier of the new node.
378        @rtype: L{defer.Deferred}
379        """
380
381    def getConfigurationOptions():
382        """
383        Retrieve all known node configuration options.
384
385        The returned dictionary holds the possible node configuration options
386        by option name. The value of each entry represents the specifics for
387        that option in a dictionary:
388
389        - C{'type'} (C{str}): The option's type (see
390          L{Field<wokkel.data_form.Field>}'s doc string for possible values).
391        - C{'label'} (C{unicode}): A human readable label for this option.
392        - C{'options'} (C{dict}): Optional list of possible values for this
393          option.
394
395        Example::
396
397            {
398            "pubsub#persist_items":
399                {"type": "boolean",
400                 "label": "Persist items to storage"},
401            "pubsub#deliver_payloads":
402                {"type": "boolean",
403                 "label": "Deliver payloads with event notifications"},
404            "pubsub#send_last_published_item":
405                {"type": "list-single",
406                 "label": "When to send the last published item",
407                 "options": {
408                     "never": "Never",
409                     "on_sub": "When a new subscription is processed"}
410                }
411            }
412
413        @rtype: C{dict}.
414        """
415
416    def getDefaultConfiguration(requestor, service):
417        """
418        Called when a default node configuration request has been received.
419
420        @param requestor: The entity the request originated from.
421        @type requestor: L{jid.JID}
422        @param service: The entity the request was addressed to.
423        @type service: L{jid.JID}
424        @return: A deferred that fires with a C{dict} representing the default
425                 node configuration. Keys are C{str}s that represent the
426                 field name. Values can be of types C{unicode}, C{int} or
427                 C{bool}.
428        @rtype: L{defer.Deferred}
429        """
430
431    def getConfiguration(requestor, service, nodeIdentifier):
432        """
433        Called when a node configuration retrieval request has been received.
434
435        @param requestor: The entity the request originated from.
436        @type requestor: L{jid.JID}
437        @param service: The entity the request was addressed to.
438        @type service: L{jid.JID}
439        @param nodeIdentifier: The identifier of the node to retrieve the
440                               configuration from.
441        @type nodeIdentifier: C{unicode}
442        @return: A deferred that fires with a C{dict} representing the node
443                 configuration. Keys are C{str}s that represent the field name.
444                 Values can be of types C{unicode}, C{int} or C{bool}.
445        @rtype: L{defer.Deferred}
446        """
447
448    def setConfiguration(requestor, service, nodeIdentifier, options):
449        """
450        Called when a node configuration change request has been received.
451
452        @param requestor: The entity the request originated from.
453        @type requestor: L{jid.JID}
454        @param service: The entity the request was addressed to.
455        @type service: L{jid.JID}
456        @param nodeIdentifier: The identifier of the node to change the
457                               configuration of.
458        @type nodeIdentifier: C{unicode}
459        @return: A deferred that fires with C{None} when the node's
460                 configuration has been changed.
461        @rtype: L{defer.Deferred}
462        """
463
464    def items(requestor, service, nodeIdentifier, maxItems, itemIdentifiers):
465        """
466        Called when a items retrieval request has been received.
467
468        @param requestor: The entity the request originated from.
469        @type requestor: L{jid.JID}
470        @param service: The entity the request was addressed to.
471        @type service: L{jid.JID}
472        @param nodeIdentifier: The identifier of the node to retrieve items
473                               from.
474        @type nodeIdentifier: C{unicode}
475        """
476
477    def retract(requestor, service, nodeIdentifier, itemIdentifiers):
478        """
479        Called when a item retraction request has been received.
480
481        @param requestor: The entity the request originated from.
482        @type requestor: L{jid.JID}
483        @param service: The entity the request was addressed to.
484        @type service: L{jid.JID}
485        @param nodeIdentifier: The identifier of the node to retract items
486                               from.
487        @type nodeIdentifier: C{unicode}
488        """
489
490    def purge(requestor, service, nodeIdentifier):
491        """
492        Called when a node purge request has been received.
493
494        @param requestor: The entity the request originated from.
495        @type requestor: L{jid.JID}
496        @param service: The entity the request was addressed to.
497        @type service: L{jid.JID}
498        @param nodeIdentifier: The identifier of the node to be purged.
499        @type nodeIdentifier: C{unicode}
500        """
501
502    def delete(requestor, service, nodeIdentifier):
503        """
504        Called when a node deletion request has been received.
505
506        @param requestor: The entity the request originated from.
507        @type requestor: L{jid.JID}
508        @param service: The entity the request was addressed to.
509        @type service: L{jid.JID}
510        @param nodeIdentifier: The identifier of the node to be delete.
511        @type nodeIdentifier: C{unicode}
512        """
513
514
515class IMUCClient(Interface):
516    """
517    Multi-User Chat Client
518
519    A client interface to XEP-045 : http://xmpp.org/extensions/xep-0045.html
520
521    """
522
523    def receivedSubject(room, subject):
524        """
525        A subject is received when you join a room and when the subject is changed. This
526        method is triggered by one of those two events.
527
528        @param room: The room the subject was accepted for.
529        @type room: L{muc.Room}
530
531        @param subject: The subject of the given room.
532        @type subject: C{unicode}
533        """
534
535
536    def receivedHistory(room, user, message, history, frm=None):
537        """
538        Past messages from a chat room has been received. This occurs when you join a room.
539
540
541        """
542
543   
544    def disco(entity, type='info'):
545        """Send disco queries to a XMPP entity
546
547        @param entity: A XMPP entity to send the disco request to.
548        @type entity: C{unicode}
549
550        @param type: Optional argument to determine the type of discovery being done.
551        @type type: C{str}
552
553        """
554
555       
556
557    def configure(room_jid, fields=[]):
558        """Configure a room. When a user has administration privledges they can configure
559        a room.
560
561        @param room_jid: A XMPP entity for the room.
562        @type room_jid: L{jid.JID}
563
564        @param fields: A list of fields to change or add to the room's configuration.
565        @type fields: C{list}
566
567        """
568
569    def getConfigureForm(room_jid):
570        """
571        In order to know the fields to change in a room you will need to get the form.
572       
573        @param room_jid: The room you want the configuration form from.
574        @type room_jid: L{jid.JID}
575
576        """
577
578    def join(server, room, nick):
579        """
580        Join a multi-user chat room.
581
582        @param server: The server the room is on.
583        @type server: C{str}
584
585        @param room: The room name.
586        @type room: C{str}
587       
588        @param nick: The nick name you want when you join the room.
589        @type nick: C{str}
590
591        """
592
593
594    def leave(room_jid):
595        """
596        Leave a multi-user chat room.
597
598        @param room_jid: The room you want the configuration form from.
599        @type room_jid: L{jid.JID}
600
601        """
602
603    def userJoinedRoom(room, user):
604        """User has joined the room.
605
606        @param room: The room the user joined.
607        @type  room: L{muc.Room}
608
609        @param user: The user that joined the room.
610        @type  user: L{muc.User}
611
612        """
613   
614
615    def groupChat(to, message, children=None):
616        """Send a groupchat message to a room.
617
618        """
619
620
621    def chat(to, message, children=None):
622        """
623
624        """
625
626
627    def password(to, password):
628        """
629        """
630   
631    def register(to, fields=[]):
632        """
633        """
634
635
636    def subject(to, subject):
637        """
638        """
639
640    def voice(to):
641        """
642        """
643
644
645    def history(to, message_list):
646        """
647        """
648
649    def ban(to, ban_jid, frm, reason=None):
650        """
651        """
652
653
654    def kick(to, kick_jid, frm, reason=None):
655        """
656        """
657
Note: See TracBrowser for help on using the repository browser.