source: wokkel/iwokkel.py @ 6:283b6997cf7d

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

Support services on a JID.

Author: ralphm
Fixes #2.

File size: 15.7 KB
Line 
1# Copyright (c) 2003-2007 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 publish(service, nodeIdentifier, items=[]):
194        """
195        Publish to a node.
196
197        Node that the C{items} parameter is optional, because so-called
198        transient, notification-only nodes do not use items and publish
199        actions only signify a change in some resource.
200
201        @param service: The publish-subscribe service entity.
202        @type service: L{jid.JID}
203        @param nodeIdentifier: Identifier of the node to publish to.
204        @type nodeIdentifier: L{unicode}
205        @param items: List of item elements.
206        @type items: L{list} of L{Item}
207        @rtype: L{defer.Deferred}
208        """
209
210
211class IPubSubService(Interface):
212    """
213    Interface for an XMPP Publish Subscribe Service.
214
215    All methods that are called as the result of an XMPP request are to
216    return a deferred that fires when the requested action has been performed.
217    Alternatively, exceptions maybe raised directly or by calling C{errback}
218    on the returned deferred.
219    """
220
221    def notifyPublish(service, nodeIdentifier, notifications):
222        """
223        Send out notifications for a publish event.
224
225        @param service: The entity the notifications will originate from.
226        @type service: L{jid.JID}
227        @param nodeIdentifier: The identifier of the node that was published
228                               to.
229        @type nodeIdentifier: C{unicode}
230        @param notifications: The notifications as tuples of subscriber and
231                              the list of items to be notified.
232        @type notifications: C{list} of (L{jid.JID}, C{list} of
233                             L{domish.Element})
234        """
235
236    def publish(requestor, service, nodeIdentifier, items):
237        """
238        Called when a publish request has been received.
239
240        @param requestor: The entity the request originated from.
241        @type requestor: L{jid.JID}
242        @param service: The entity the request was addressed to.
243        @type service: L{jid.JID}
244        @param nodeIdentifier: The identifier of the node to publish to.
245        @type nodeIdentifier: C{unicode}
246        @param items: The items to be published as L{domish} elements.
247        @type items: C{list} of C{domish.Element}
248        @return: deferred that fires on success.
249        @rtype: L{defer.Deferred}
250        """
251
252    def subscribe(requestor, service, nodeIdentifier, subscriber):
253        """
254        Called when a subscribe request has been received.
255
256        @param requestor: The entity the request originated from.
257        @type requestor: L{jid.JID}
258        @param service: The entity the request was addressed to.
259        @type service: L{jid.JID}
260        @param nodeIdentifier: The identifier of the node to subscribe to.
261        @type nodeIdentifier: C{unicode}
262        @param subscriber: The entity to be subscribed.
263        @type subscriber: L{jid.JID}
264        @return: A deferred that fires with a C{str} representing the
265                 subscription state, C{'subscribed'} or C{'pending'}.
266        @rtype: L{defer.Deferred}
267        """
268
269    def unsubscribe(requestor, service, nodeIdentifier, subscriber):
270        """
271        Called when a subscribe request has been received.
272
273        @param requestor: The entity the request originated from.
274        @type requestor: L{jid.JID}
275        @param service: The entity the request was addressed to.
276        @type service: L{jid.JID}
277        @param nodeIdentifier: The identifier of the node to unsubscribe from.
278        @type nodeIdentifier: C{unicode}
279        @param subscriber: The entity to be unsubscribed.
280        @type subscriber: L{jid.JID}
281        @return: A deferred that fires with C{None} when unsubscription has
282                 succeeded.
283        @rtype: L{defer.Deferred}
284        """
285
286    def subscriptions(requestor, service):
287        """
288        Called when a subscriptions retrieval request has been received.
289
290        @param requestor: The entity the request originated from.
291        @type requestor: L{jid.JID}
292        @param service: The entity the request was addressed to.
293        @type service: L{jid.JID}
294        @return: A deferred that fires with a C{list} of suscriptions as
295                 C{tuple}s of (node identifier as C{unicode}, subscriber as
296                 L{jid.JID}, subscription state as C{str}). The subscription
297                 state can be C{'subscribed'} or C{'pending'}.
298        @rtype: L{defer.Deferred}
299        """
300
301    def affiliations(requestor, service):
302        """
303        Called when a affiliations retrieval 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        @return: A deferred that fires with a C{list} of affiliations as
310                 C{tuple}s of (node identifier as C{unicode}, affiliation state
311                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
312                 or C{'outcast'}.
313        @rtype: L{defer.Deferred}
314        """
315
316    def create(requestor, service, nodeIdentifier):
317        """
318        Called when a node creation request has been received.
319
320        @param requestor: The entity the request originated from.
321        @type requestor: L{jid.JID}
322        @param service: The entity the request was addressed to.
323        @type service: L{jid.JID}
324        @param nodeIdentifier: The suggestion for the identifier of the node to
325                               be created. If the request did not include a
326                               suggestion for the node identifier, the value
327                               is C{None}.
328        @type nodeIdentifier: C{unicode} or C{NoneType}
329        @return: A deferred that fires with a C{unicode} that represents
330                 the identifier of the new node.
331        @rtype: L{defer.Deferred}
332        """
333
334    def getDefaultConfiguration(requestor, service):
335        """
336        Called when a default node configuration request has been received.
337
338        @param requestor: The entity the request originated from.
339        @type requestor: L{jid.JID}
340        @param service: The entity the request was addressed to.
341        @type service: L{jid.JID}
342        @return: A deferred that fires with a C{dict} representing the default
343                 node configuration. Keys are C{str}s that represent the
344                 field name. Values can be of types C{unicode}, C{int} or
345                 C{bool}.
346        @rtype: L{defer.Deferred}
347        """
348
349    def getConfiguration(requestor, service, nodeIdentifier):
350        """
351        Called when a node configuration retrieval request has been received.
352
353        @param requestor: The entity the request originated from.
354        @type requestor: L{jid.JID}
355        @param service: The entity the request was addressed to.
356        @type service: L{jid.JID}
357        @param nodeIdentifier: The identifier of the node to retrieve the
358                               configuration from.
359        @type nodeIdentifier: C{unicode}
360        @return: A deferred that fires with a C{dict} representing the node
361                 configuration. Keys are C{str}s that represent the field name.
362                 Values can be of types C{unicode}, C{int} or C{bool}.
363        @rtype: L{defer.Deferred}
364        """
365
366    def setConfiguration(requestor, service, nodeIdentifier, options):
367        """
368        Called when a node configuration change request has been received.
369
370        @param requestor: The entity the request originated from.
371        @type requestor: L{jid.JID}
372        @param service: The entity the request was addressed to.
373        @type service: L{jid.JID}
374        @param nodeIdentifier: The identifier of the node to change the
375                               configuration of.
376        @type nodeIdentifier: C{unicode}
377        @return: A deferred that fires with C{None} when the node's
378                 configuration has been changed.
379        @rtype: L{defer.Deferred}
380        """
381
382    def items(requestor, service, nodeIdentifier, maxItems, itemIdentifiers):
383        """
384        Called when a items retrieval request has been received.
385
386        @param requestor: The entity the request originated from.
387        @type requestor: L{jid.JID}
388        @param service: The entity the request was addressed to.
389        @type service: L{jid.JID}
390        @param nodeIdentifier: The identifier of the node to retrieve items
391                               from.
392        @type nodeIdentifier: C{unicode}
393        """
394
395    def retract(requestor, service, nodeIdentifier, itemIdentifiers):
396        """
397        Called when a item retraction 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 retract items
404                               from.
405        @type nodeIdentifier: C{unicode}
406        """
407
408    def purge(requestor, service, nodeIdentifier):
409        """
410        Called when a node purge 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 be purged.
417        @type nodeIdentifier: C{unicode}
418        """
419
420    def delete(requestor, service, nodeIdentifier):
421        """
422        Called when a node deletion request has been received.
423
424        @param requestor: The entity the request originated from.
425        @type requestor: L{jid.JID}
426        @param service: The entity the request was addressed to.
427        @type service: L{jid.JID}
428        @param nodeIdentifier: The identifier of the node to be delete.
429        @type nodeIdentifier: C{unicode}
430        """
Note: See TracBrowser for help on using the repository browser.