source: wokkel/iwokkel.py @ 2:47f1cb624f14

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

Add in pubsub client support, client helpers and generic XMPP subprotocol handlers.

File size: 12.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 makeConnection(xs):
22        """
23        A connection over the underlying transport of the XML stream has been
24        established.
25
26        At this point, no traffic has been exchanged over the XML stream
27        given in C{xs}.
28
29        This should setup C{self.xmlstream} and call L{connectionMade}.
30
31        @type xs: L{XmlStream<twisted.words.protocols.jabber.XmlStream>}
32        """
33
34    def connectionMade(self):
35        """
36        Called after a connection has been established.
37
38        This method can be used to change properties of the XML Stream, its
39        authenticator or the stream manager prior to stream initialization
40        (including authentication).
41        """
42
43    def connectionInitialized():
44        """
45        The XML stream has been initialized.
46
47        At this point, authentication was successful, and XML stanzas can be
48        exchanged over the XML stream C{self.xmlstream}. This method can be
49        used to setup observers for incoming stanzas.
50        """
51
52    def connectionLost(reason):
53        """
54        The XML stream has been closed.
55
56        Subsequent use of C{self.parent.send} will result in data being queued
57        until a new connection has been established.
58
59        @type reason: L{twisted.python.failure.Failure}
60        """
61
62
63class IDisco(Interface):
64    """
65    Interface for XMPP service discovery.
66    """
67
68    def getDiscoInfo(target, requestor, nodeIdentifier=None):
69        """
70        Get identity and features from this entity, node.
71
72        @param requestor: The entity the request originated from.
73        @type requestor: L{jid.JID}
74        @param nodeIdentifier: The optional identifier of the node at this
75                               entity to retrieve the identify and features of.
76                               The default is C{None}, meaning the root node.
77        @type nodeIdentifier: C{unicode}
78        """
79
80    def getDiscoItems(target, requestor, nodeIdentifier=None):
81        """
82        Get contained items for this entity, node.
83
84        @param requestor: The entity the request originated from.
85        @type requestor: L{jid.JID}
86        @param nodeIdentifier: The optional identifier of the node at this
87                               entity to retrieve the identify and features of.
88                               The default is C{None}, meaning the root node.
89        @type nodeIdentifier: C{unicode}
90        """
91
92
93class IPubSubClient(Interface):
94
95    def itemsReceived(notifier, node, items):
96        """
97        Called when items have been received from a node.
98
99        @param notifier: the entity from which the notification was received.
100        @type notifier: L{jid.JID}
101        @param node: identifier of the node the items belong to.
102        @type node: C{unicode}
103        @param items: list of received items as domish elements.
104        @type items: C{list} of L{domish.Element}
105        """
106
107    def createNode(node=None):
108        """
109        Create a new publish subscribe node.
110
111        @param node: optional suggestion for the new node's identifier. If
112                     omitted, the creation of an instant node will be
113                     attempted.
114        @type node: L{unicode}
115        @return: a deferred that fires with the identifier of the newly created
116                 node. Note that this can differ from the suggested identifier
117                 if the publish subscribe service chooses to modify or ignore
118                 the suggested identifier.
119        @rtype: L{defer.Deferred}
120        """
121
122    def deleteNode(node):
123        """
124        Delete a node.
125
126        @param node: identifier of the node to be deleted.
127        @type node: L{unicode}
128        @rtype: L{defer.Deferred}
129        """
130
131    def subscribe(node, subscriber):
132        """
133        Subscribe to a node with a given JID.
134
135        @param node: identifier of the node to subscribe to.
136        @type node: L{unicode}
137        @param subscriber: JID to subscribe to the node.
138        @type subscriber: L{jid.JID}
139        @rtype: L{defer.Deferred}
140        """
141
142    def publish(requestor, node, items=[]):
143        """
144        Publish to a node.
145
146        Node that the C{items} parameter is optional, because so-called
147        transient, notification-only nodes do not use items and publish
148        actions only signify a change in some resource.
149
150        @param node: identifier of the node to publish to.
151        @type node: L{unicode}
152        @param items: list of item elements.
153        @type items: L{list} of L{Item}
154        @rtype: L{defer.Deferred}
155        """
156
157
158class IPubSubService(Interface):
159    """
160    Interface for an XMPP Publish Subscribe Service.
161
162    All methods that are called as the result of an XMPP request are to
163    return a deferred that fires when the requested action has been performed.
164    Alternatively, exceptions maybe raised directly or by calling C{errback}
165    on the returned deferred.
166    """
167
168    def notifyPublish(entity, nodeIdentifier, notifications):
169        """
170        Send out notifications for a publish event.
171
172        @param entity: The entity the notifications will originate from.
173        @type entity: L{jid.JID}
174        @param nodeIdentifier: The identifier of the node that was published
175                               to.
176        @type nodeIdentifier: C{unicode}
177        @param notifications: The notifications as tuples of subscriber and
178                              the list of items to be notified.
179        @type notifications: C{list} of (L{jid.JID}, C{list} of
180                             L{domish.Element})
181        """
182
183    def publish(requestor, nodeIdentifier, items):
184        """
185        Called when a publish request has been received.
186
187        @param requestor: The entity the request originated from.
188        @type requestor: L{jid.JID}
189        @param nodeIdentifier: The identifier of the node to publish to.
190        @type nodeIdentifier: C{unicode}
191        @param items: The items to be published as L{domish} elements.
192        @type items: C{list} of C{domish.Element}
193        @return: deferred that fires on success.
194        @rtype: L{defer.Deferred}
195        """
196
197    def subscribe(requestor, nodeIdentifier, subscriber):
198        """
199        Called when a subscribe request has been received.
200
201        @param requestor: The entity the request originated from.
202        @type requestor: L{jid.JID}
203        @param nodeIdentifier: The identifier of the node to subscribe to.
204        @type nodeIdentifier: C{unicode}
205        @param subscriber: The entity to be subscribed.
206        @type subscriber: L{jid.JID}
207        @return: A deferred that fires with a C{str} representing the
208                 subscription state, C{'subscribed'} or C{'pending'}.
209        @rtype: L{defer.Deferred}
210        """
211
212    def unsubscribe(requestor, nodeIdentifier, subscriber):
213        """
214        Called when a subscribe request has been received.
215
216        @param requestor: The entity the request originated from.
217        @type requestor: L{jid.JID}
218        @param nodeIdentifier: The identifier of the node to unsubscribe from.
219        @type nodeIdentifier: C{unicode}
220        @param subscriber: The entity to be unsubscribed.
221        @type subscriber: L{jid.JID}
222        @return: A deferred that fires with C{None} when unsubscription has
223                 succeeded.
224        @rtype: L{defer.Deferred}
225        """
226
227    def subscriptions(requestor):
228        """
229        Called when a subscriptions retrieval request has been received.
230
231        @param requestor: The entity the request originated from.
232        @type requestor: L{jid.JID}
233        @return: A deferred that fires with a C{list} of suscriptions as
234                 C{tuple}s of (node identifier as C{unicode}, subscriber as
235                 L{jid.JID}, subscription state as C{str}). The subscription
236                 state can be C{'subscribed'} or C{'pending'}.
237        @rtype: L{defer.Deferred}
238        """
239
240    def affiliations(requestor):
241        """
242        Called when a affiliations retrieval request has been received.
243
244        @param requestor: The entity the request originated from.
245        @type requestor: L{jid.JID}
246        @return: A deferred that fires with a C{list} of affiliations as
247                 C{tuple}s of (node identifier as C{unicode}, affiliation state
248                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
249                 or C{'outcast'}.
250        @rtype: L{defer.Deferred}
251        """
252
253    def create(requestor, nodeIdentifier):
254        """
255        Called when a node creation request has been received.
256
257        @param requestor: The entity the request originated from.
258        @type requestor: L{jid.JID}
259        @param nodeIdentifier: The suggestion for the identifier of the node to
260                               be created. If the request did not include a
261                               suggestion for the node identifier, the value
262                               is C{None}.
263        @type nodeIdentifier: C{unicode} or C{NoneType}
264        @return: A deferred that fires with a C{unicode} that represents
265                 the identifier of the new node.
266        @rtype: L{defer.Deferred}
267        """
268
269    def getDefaultConfiguration(requestor):
270        """
271        Called when a default node configuration request has been received.
272
273        @param requestor: The entity the request originated from.
274        @type requestor: L{jid.JID}
275        @return: A deferred that fires with a C{dict} representing the default
276                 node configuration. Keys are C{str}s that represent the
277                 field name. Values can be of types C{unicode}, C{int} or
278                 C{bool}.
279        @rtype: L{defer.Deferred}
280        """
281
282    def getConfiguration(requestor, nodeIdentifier):
283        """
284        Called when a node configuration retrieval request has been received.
285
286        @param requestor: The entity the request originated from.
287        @type requestor: L{jid.JID}
288        @param nodeIdentifier: The identifier of the node to retrieve the
289                               configuration from.
290        @type nodeIdentifier: C{unicode}
291        @return: A deferred that fires with a C{dict} representing the node
292                 configuration. Keys are C{str}s that represent the field name.
293                 Values can be of types C{unicode}, C{int} or C{bool}.
294        @rtype: L{defer.Deferred}
295        """
296
297    def setConfiguration(requestor, nodeIdentifier, options):
298        """
299        Called when a node configuration change request has been received.
300
301        @param requestor: The entity the request originated from.
302        @type requestor: L{jid.JID}
303        @param nodeIdentifier: The identifier of the node to change the
304                               configuration of.
305        @type nodeIdentifier: C{unicode}
306        @return: A deferred that fires with C{None} when the node's
307                 configuration has been changed.
308        @rtype: L{defer.Deferred}
309        """
310
311    def items(requestor, nodeIdentifier, maxItems, itemIdentifiers):
312        """
313        Called when a items retrieval request has been received.
314
315        @param requestor: The entity the request originated from.
316        @type requestor: L{jid.JID}
317        @param nodeIdentifier: The identifier of the node to retrieve items
318                               from.
319        @type nodeIdentifier: C{unicode}
320        """
321
322    def retract(requestor, nodeIdentifier, itemIdentifiers):
323        """
324        Called when a item retraction request has been received.
325
326        @param requestor: The entity the request originated from.
327        @type requestor: L{jid.JID}
328        @param nodeIdentifier: The identifier of the node to retract items
329                               from.
330        @type nodeIdentifier: C{unicode}
331        """
332
333    def purge(requestor, nodeIdentifier):
334        """
335        Called when a node purge request has been received.
336
337        @param requestor: The entity the request originated from.
338        @type requestor: L{jid.JID}
339        @param nodeIdentifier: The identifier of the node to be purged.
340        @type nodeIdentifier: C{unicode}
341        """
342
343    def delete(requestor, nodeIdentifier):
344        """
345        Called when a node deletion request has been received.
346
347        @param requestor: The entity the request originated from.
348        @type requestor: L{jid.JID}
349        @param nodeIdentifier: The identifier of the node to be delete.
350        @type nodeIdentifier: C{unicode}
351        """
352
353
Note: See TracBrowser for help on using the repository browser.