source: wokkel/iwokkel.py @ 10:a5e3c32d23ca

Last change on this file since 10:a5e3c32d23ca was 10:a5e3c32d23ca, checked in by Ralph Meijer <ralphm@…>, 14 years ago

Add unsubscribe method to PubSubClient?.

Author: ralphm
Fixes #4.

File size: 16.1 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 C{self.xmlstream} and call L{connectionMade}.
44
45        @type xs: L{XmlStream<twisted.words.protocols.jabber.XmlStream>}
46        """
47
48    def connectionMade(self):
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 C{self.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 C{self.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
76class IXMPPHandlerCollection(Interface):
77    """
78    Collection of handlers.
79
80    Contain several handlers and manage their connection.
81    """
82
83    def __iter__():
84        """
85        Get an iterator over all child handlers.
86        """
87
88    def addHandler(handler):
89        """
90        Add a child handler.
91
92        @type handler: L{IXMPPHandler}
93        """
94
95    def removeHandler(handler):
96        """
97        Remove a child handler.
98
99        @type handler: L{IXMPPHandler}
100        """
101
102class IDisco(Interface):
103    """
104    Interface for XMPP service discovery.
105    """
106
107    def getDiscoInfo(requestor, target, nodeIdentifier=None):
108        """
109        Get identity and features from this entity, node.
110
111        @param requestor: The entity the request originated from.
112        @type requestor: L{jid.JID}
113        @param target: The target entity to which the request is made.
114        @type target: L{jid.JID}
115        @param nodeIdentifier: The optional identifier of the node at this
116                               entity to retrieve the identify and features of.
117                               The default is C{None}, meaning the root node.
118        @type nodeIdentifier: C{unicode}
119        """
120
121    def getDiscoItems(requestor, target, nodeIdentifier=None):
122        """
123        Get contained items for this entity, node.
124
125        @param requestor: The entity the request originated from.
126        @type requestor: L{jid.JID}
127        @param target: The target entity to which the request is made.
128        @type target: L{jid.JID}
129        @param nodeIdentifier: The optional identifier of the node at this
130                               entity to retrieve the identify and features of.
131                               The default is C{None}, meaning the root node.
132        @type nodeIdentifier: C{unicode}
133        """
134
135
136class IPubSubClient(Interface):
137
138    def itemsReceived(recipient, service, nodeIdentifier, items):
139        """
140        Called when items have been received from a node.
141
142        @param recipient: The entity to which the notification was sent.
143        @type recipient: L{jid.JID}
144        @param service: The entity from which the notification was received.
145        @type service: L{jid.JID}
146        @param nodeIdentifier: Identifier of the node the items belong to.
147        @type nodeIdentifier: C{unicode}
148        @param items: List of received items as domish elements.
149        @type items: C{list} of L{domish.Element}
150        """
151
152    def createNode(service, nodeIdentifier=None):
153        """
154        Create a new publish subscribe node.
155
156        @param service: The publish-subscribe service entity.
157        @type service: L{jid.JID}
158        @param nodeIdentifier: Optional suggestion for the new node's
159                               identifier. If omitted, the creation of an
160                               instant node will be attempted.
161        @type nodeIdentifier: L{unicode}
162        @return: a deferred that fires with the identifier of the newly created
163                 node. Note that this can differ from the suggested identifier
164                 if the publish subscribe service chooses to modify or ignore
165                 the suggested identifier.
166        @rtype: L{defer.Deferred}
167        """
168
169    def deleteNode(service, nodeIdentifier):
170        """
171        Delete a node.
172
173        @param service: The publish-subscribe service entity.
174        @type service: L{jid.JID}
175        @param nodeIdentifier: Identifier of the node to be deleted.
176        @type nodeIdentifier: L{unicode}
177        @rtype: L{defer.Deferred}
178        """
179
180    def subscribe(service, nodeIdentifier, subscriber):
181        """
182        Subscribe to a node with a given JID.
183
184        @param service: The publish-subscribe service entity.
185        @type service: L{jid.JID}
186        @param nodeIdentifier: Identifier of the node to subscribe to.
187        @type nodeIdentifier: L{unicode}
188        @param subscriber: JID to subscribe to the node.
189        @type subscriber: L{jid.JID}
190        @rtype: L{defer.Deferred}
191        """
192
193    def unsubscribe(service, nodeIdentifier, subscriber):
194        """
195        Unsubscribe from a node with a given JID.
196
197        @param service: The publish-subscribe service entity.
198        @type service: L{jid.JID}
199        @param nodeIdentifier: Identifier of the node to unsubscribe from.
200        @type nodeIdentifier: L{unicode}
201        @param subscriber: JID to unsubscribe from the node.
202        @type subscriber: L{jid.JID}
203        @rtype: L{defer.Deferred}
204        """
205
206    def publish(service, nodeIdentifier, items=[]):
207        """
208        Publish to a node.
209
210        Node that the C{items} parameter is optional, because so-called
211        transient, notification-only nodes do not use items and publish
212        actions only signify a change in some resource.
213
214        @param service: The publish-subscribe service entity.
215        @type service: L{jid.JID}
216        @param nodeIdentifier: Identifier of the node to publish to.
217        @type nodeIdentifier: L{unicode}
218        @param items: List of item elements.
219        @type items: L{list} of L{Item}
220        @rtype: L{defer.Deferred}
221        """
222
223
224class IPubSubService(Interface):
225    """
226    Interface for an XMPP Publish Subscribe Service.
227
228    All methods that are called as the result of an XMPP request are to
229    return a deferred that fires when the requested action has been performed.
230    Alternatively, exceptions maybe raised directly or by calling C{errback}
231    on the returned deferred.
232    """
233
234    def notifyPublish(service, nodeIdentifier, notifications):
235        """
236        Send out notifications for a publish event.
237
238        @param service: The entity the notifications will originate from.
239        @type service: L{jid.JID}
240        @param nodeIdentifier: The identifier of the node that was published
241                               to.
242        @type nodeIdentifier: C{unicode}
243        @param notifications: The notifications as tuples of subscriber and
244                              the list of items to be notified.
245        @type notifications: C{list} of (L{jid.JID}, C{list} of
246                             L{domish.Element})
247        """
248
249    def publish(requestor, service, nodeIdentifier, items):
250        """
251        Called when a publish request has been received.
252
253        @param requestor: The entity the request originated from.
254        @type requestor: L{jid.JID}
255        @param service: The entity the request was addressed to.
256        @type service: L{jid.JID}
257        @param nodeIdentifier: The identifier of the node to publish to.
258        @type nodeIdentifier: C{unicode}
259        @param items: The items to be published as L{domish} elements.
260        @type items: C{list} of C{domish.Element}
261        @return: deferred that fires on success.
262        @rtype: L{defer.Deferred}
263        """
264
265    def subscribe(requestor, service, nodeIdentifier, subscriber):
266        """
267        Called when a subscribe request has been received.
268
269        @param requestor: The entity the request originated from.
270        @type requestor: L{jid.JID}
271        @param service: The entity the request was addressed to.
272        @type service: L{jid.JID}
273        @param nodeIdentifier: The identifier of the node to subscribe to.
274        @type nodeIdentifier: C{unicode}
275        @param subscriber: The entity to be subscribed.
276        @type subscriber: L{jid.JID}
277        @return: A deferred that fires with a C{str} representing the
278                 subscription state, C{'subscribed'} or C{'pending'}.
279        @rtype: L{defer.Deferred}
280        """
281
282    def unsubscribe(requestor, service, nodeIdentifier, subscriber):
283        """
284        Called when a subscribe request has been received.
285
286        @param requestor: The entity the request originated from.
287        @type requestor: L{jid.JID}
288        @param service: The entity the request was addressed to.
289        @type service: L{jid.JID}
290        @param nodeIdentifier: The identifier of the node to unsubscribe from.
291        @type nodeIdentifier: C{unicode}
292        @param subscriber: The entity to be unsubscribed.
293        @type subscriber: L{jid.JID}
294        @return: A deferred that fires with C{None} when unsubscription has
295                 succeeded.
296        @rtype: L{defer.Deferred}
297        """
298
299    def subscriptions(requestor, service):
300        """
301        Called when a subscriptions retrieval request has been received.
302
303        @param requestor: The entity the request originated from.
304        @type requestor: L{jid.JID}
305        @param service: The entity the request was addressed to.
306        @type service: L{jid.JID}
307        @return: A deferred that fires with a C{list} of suscriptions as
308                 C{tuple}s of (node identifier as C{unicode}, subscriber as
309                 L{jid.JID}, subscription state as C{str}). The subscription
310                 state can be C{'subscribed'} or C{'pending'}.
311        @rtype: L{defer.Deferred}
312        """
313
314    def affiliations(requestor, service):
315        """
316        Called when a affiliations retrieval request has been received.
317
318        @param requestor: The entity the request originated from.
319        @type requestor: L{jid.JID}
320        @param service: The entity the request was addressed to.
321        @type service: L{jid.JID}
322        @return: A deferred that fires with a C{list} of affiliations as
323                 C{tuple}s of (node identifier as C{unicode}, affiliation state
324                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
325                 or C{'outcast'}.
326        @rtype: L{defer.Deferred}
327        """
328
329    def create(requestor, service, nodeIdentifier):
330        """
331        Called when a node creation request has been received.
332
333        @param requestor: The entity the request originated from.
334        @type requestor: L{jid.JID}
335        @param service: The entity the request was addressed to.
336        @type service: L{jid.JID}
337        @param nodeIdentifier: The suggestion for the identifier of the node to
338                               be created. If the request did not include a
339                               suggestion for the node identifier, the value
340                               is C{None}.
341        @type nodeIdentifier: C{unicode} or C{NoneType}
342        @return: A deferred that fires with a C{unicode} that represents
343                 the identifier of the new node.
344        @rtype: L{defer.Deferred}
345        """
346
347    def getDefaultConfiguration(requestor, service):
348        """
349        Called when a default node configuration request has been received.
350
351        @param requestor: The entity the request originated from.
352        @type requestor: L{jid.JID}
353        @param service: The entity the request was addressed to.
354        @type service: L{jid.JID}
355        @return: A deferred that fires with a C{dict} representing the default
356                 node configuration. Keys are C{str}s that represent the
357                 field name. Values can be of types C{unicode}, C{int} or
358                 C{bool}.
359        @rtype: L{defer.Deferred}
360        """
361
362    def getConfiguration(requestor, service, nodeIdentifier):
363        """
364        Called when a node configuration retrieval request has been received.
365
366        @param requestor: The entity the request originated from.
367        @type requestor: L{jid.JID}
368        @param service: The entity the request was addressed to.
369        @type service: L{jid.JID}
370        @param nodeIdentifier: The identifier of the node to retrieve the
371                               configuration from.
372        @type nodeIdentifier: C{unicode}
373        @return: A deferred that fires with a C{dict} representing the node
374                 configuration. Keys are C{str}s that represent the field name.
375                 Values can be of types C{unicode}, C{int} or C{bool}.
376        @rtype: L{defer.Deferred}
377        """
378
379    def setConfiguration(requestor, service, nodeIdentifier, options):
380        """
381        Called when a node configuration change request has been received.
382
383        @param requestor: The entity the request originated from.
384        @type requestor: L{jid.JID}
385        @param service: The entity the request was addressed to.
386        @type service: L{jid.JID}
387        @param nodeIdentifier: The identifier of the node to change the
388                               configuration of.
389        @type nodeIdentifier: C{unicode}
390        @return: A deferred that fires with C{None} when the node's
391                 configuration has been changed.
392        @rtype: L{defer.Deferred}
393        """
394
395    def items(requestor, service, nodeIdentifier, maxItems, itemIdentifiers):
396        """
397        Called when a items retrieval request has been received.
398
399        @param requestor: The entity the request originated from.
400        @type requestor: L{jid.JID}
401        @param service: The entity the request was addressed to.
402        @type service: L{jid.JID}
403        @param nodeIdentifier: The identifier of the node to retrieve items
404                               from.
405        @type nodeIdentifier: C{unicode}
406        """
407
408    def retract(requestor, service, nodeIdentifier, itemIdentifiers):
409        """
410        Called when a item retraction request has been received.
411
412        @param requestor: The entity the request originated from.
413        @type requestor: L{jid.JID}
414        @param service: The entity the request was addressed to.
415        @type service: L{jid.JID}
416        @param nodeIdentifier: The identifier of the node to retract items
417                               from.
418        @type nodeIdentifier: C{unicode}
419        """
420
421    def purge(requestor, service, nodeIdentifier):
422        """
423        Called when a node purge request has been received.
424
425        @param requestor: The entity the request originated from.
426        @type requestor: L{jid.JID}
427        @param service: The entity the request was addressed to.
428        @type service: L{jid.JID}
429        @param nodeIdentifier: The identifier of the node to be purged.
430        @type nodeIdentifier: C{unicode}
431        """
432
433    def delete(requestor, service, nodeIdentifier):
434        """
435        Called when a node deletion request has been received.
436
437        @param requestor: The entity the request originated from.
438        @type requestor: L{jid.JID}
439        @param service: The entity the request was addressed to.
440        @type service: L{jid.JID}
441        @param nodeIdentifier: The identifier of the node to be delete.
442        @type nodeIdentifier: C{unicode}
443        """
Note: See TracBrowser for help on using the repository browser.