1 | # Copyright (c) 2003-2008 Ralph Meijer |
---|
2 | # See LICENSE for details. |
---|
3 | |
---|
4 | """ |
---|
5 | Wokkel interfaces. |
---|
6 | """ |
---|
7 | |
---|
8 | from zope.interface import Attribute, Interface |
---|
9 | |
---|
10 | class 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 | |
---|
77 | class 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 | |
---|
104 | class IDisco(Interface): |
---|
105 | """ |
---|
106 | Interface for XMPP service discovery. |
---|
107 | """ |
---|
108 | |
---|
109 | def getDiscoInfo(requestor, target, nodeIdentifier=None): |
---|
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{None}, meaning the root node. |
---|
120 | @type nodeIdentifier: C{unicode} |
---|
121 | """ |
---|
122 | |
---|
123 | def getDiscoItems(requestor, target, nodeIdentifier=None): |
---|
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{None}, meaning the root node. |
---|
134 | @type nodeIdentifier: C{unicode} |
---|
135 | """ |
---|
136 | |
---|
137 | |
---|
138 | class IPubSubClient(Interface): |
---|
139 | |
---|
140 | def itemsReceived(recipient, service, nodeIdentifier, items): |
---|
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 recipient: The entity to which the notification was sent. |
---|
149 | @type recipient: L{jid.JID} |
---|
150 | @param service: The entity from which the notification was received. |
---|
151 | @type service: L{jid.JID} |
---|
152 | @param nodeIdentifier: Identifier of the node the items belong to. |
---|
153 | @type nodeIdentifier: C{unicode} |
---|
154 | @param items: List of received items as domish elements. |
---|
155 | @type items: C{list} of L{domish.Element} |
---|
156 | """ |
---|
157 | |
---|
158 | def deleteReceived(recipient, service, nodeIdentifier, items): |
---|
159 | """ |
---|
160 | Called when a deletion notification has been received for a node. |
---|
161 | |
---|
162 | @param recipient: The entity to which the notification was sent. |
---|
163 | @type recipient: L{jid.JID} |
---|
164 | @param service: The entity from which the notification was received. |
---|
165 | @type service: L{jid.JID} |
---|
166 | @param nodeIdentifier: Identifier of the node that has been deleted. |
---|
167 | @type nodeIdentifier: C{unicode} |
---|
168 | """ |
---|
169 | |
---|
170 | def purgeReceived(recipient, service, nodeIdentifier, items): |
---|
171 | """ |
---|
172 | Called when a purge notification has been received for a node. |
---|
173 | |
---|
174 | Upon receiving this notification all items associated should be |
---|
175 | considered retracted. |
---|
176 | |
---|
177 | @param recipient: The entity to which the notification was sent. |
---|
178 | @type recipient: L{jid.JID} |
---|
179 | @param service: The entity from which the notification was received. |
---|
180 | @type service: L{jid.JID} |
---|
181 | @param nodeIdentifier: Identifier of the node that has been purged. |
---|
182 | @type nodeIdentifier: C{unicode} |
---|
183 | """ |
---|
184 | |
---|
185 | def createNode(service, nodeIdentifier=None): |
---|
186 | """ |
---|
187 | Create a new publish subscribe node. |
---|
188 | |
---|
189 | @param service: The publish-subscribe service entity. |
---|
190 | @type service: L{jid.JID} |
---|
191 | @param nodeIdentifier: Optional suggestion for the new node's |
---|
192 | identifier. If omitted, the creation of an |
---|
193 | instant node will be attempted. |
---|
194 | @type nodeIdentifier: L{unicode} |
---|
195 | @return: a deferred that fires with the identifier of the newly created |
---|
196 | node. Note that this can differ from the suggested identifier |
---|
197 | if the publish subscribe service chooses to modify or ignore |
---|
198 | the suggested identifier. |
---|
199 | @rtype: L{defer.Deferred} |
---|
200 | """ |
---|
201 | |
---|
202 | def deleteNode(service, nodeIdentifier): |
---|
203 | """ |
---|
204 | Delete a node. |
---|
205 | |
---|
206 | @param service: The publish-subscribe service entity. |
---|
207 | @type service: L{jid.JID} |
---|
208 | @param nodeIdentifier: Identifier of the node to be deleted. |
---|
209 | @type nodeIdentifier: L{unicode} |
---|
210 | @rtype: L{defer.Deferred} |
---|
211 | """ |
---|
212 | |
---|
213 | def subscribe(service, nodeIdentifier, subscriber): |
---|
214 | """ |
---|
215 | Subscribe to a node with a given JID. |
---|
216 | |
---|
217 | @param service: The publish-subscribe service entity. |
---|
218 | @type service: L{jid.JID} |
---|
219 | @param nodeIdentifier: Identifier of the node to subscribe to. |
---|
220 | @type nodeIdentifier: L{unicode} |
---|
221 | @param subscriber: JID to subscribe to the node. |
---|
222 | @type subscriber: L{jid.JID} |
---|
223 | @rtype: L{defer.Deferred} |
---|
224 | """ |
---|
225 | |
---|
226 | def unsubscribe(service, nodeIdentifier, subscriber): |
---|
227 | """ |
---|
228 | Unsubscribe from a node with a given JID. |
---|
229 | |
---|
230 | @param service: The publish-subscribe service entity. |
---|
231 | @type service: L{jid.JID} |
---|
232 | @param nodeIdentifier: Identifier of the node to unsubscribe from. |
---|
233 | @type nodeIdentifier: L{unicode} |
---|
234 | @param subscriber: JID to unsubscribe from the node. |
---|
235 | @type subscriber: L{jid.JID} |
---|
236 | @rtype: L{defer.Deferred} |
---|
237 | """ |
---|
238 | |
---|
239 | def publish(service, nodeIdentifier, items=[]): |
---|
240 | """ |
---|
241 | Publish to a node. |
---|
242 | |
---|
243 | Node that the C{items} parameter is optional, because so-called |
---|
244 | transient, notification-only nodes do not use items and publish |
---|
245 | actions only signify a change in some resource. |
---|
246 | |
---|
247 | @param service: The publish-subscribe service entity. |
---|
248 | @type service: L{jid.JID} |
---|
249 | @param nodeIdentifier: Identifier of the node to publish to. |
---|
250 | @type nodeIdentifier: L{unicode} |
---|
251 | @param items: List of item elements. |
---|
252 | @type items: L{list} of L{Item} |
---|
253 | @rtype: L{defer.Deferred} |
---|
254 | """ |
---|
255 | |
---|
256 | |
---|
257 | class IPubSubService(Interface): |
---|
258 | """ |
---|
259 | Interface for an XMPP Publish Subscribe Service. |
---|
260 | |
---|
261 | All methods that are called as the result of an XMPP request are to |
---|
262 | return a deferred that fires when the requested action has been performed. |
---|
263 | Alternatively, exceptions maybe raised directly or by calling C{errback} |
---|
264 | on the returned deferred. |
---|
265 | """ |
---|
266 | |
---|
267 | def notifyPublish(service, nodeIdentifier, notifications): |
---|
268 | """ |
---|
269 | Send out notifications for a publish event. |
---|
270 | |
---|
271 | @param service: The entity the notifications will originate from. |
---|
272 | @type service: L{jid.JID} |
---|
273 | @param nodeIdentifier: The identifier of the node that was published |
---|
274 | to. |
---|
275 | @type nodeIdentifier: C{unicode} |
---|
276 | @param notifications: The notifications as tuples of subscriber and |
---|
277 | the list of items to be notified. |
---|
278 | @type notifications: C{list} of (L{jid.JID}, C{list} of |
---|
279 | L{domish.Element}) |
---|
280 | """ |
---|
281 | |
---|
282 | def notifyDelete(service, nodeIdentifier, recipients): |
---|
283 | """ |
---|
284 | Send out node deletion notifications. |
---|
285 | |
---|
286 | @param service: The entity the notifications will originate from. |
---|
287 | @type service: L{jid.JID} |
---|
288 | @param nodeIdentifier: The identifier of the node that was deleted. |
---|
289 | @type nodeIdentifier: C{unicode} |
---|
290 | @param recipients: The entities that the notification is sent to. |
---|
291 | @type notifications: C{list} of L{jid.JID} |
---|
292 | """ |
---|
293 | |
---|
294 | def publish(requestor, service, nodeIdentifier, items): |
---|
295 | """ |
---|
296 | Called when a publish request has been received. |
---|
297 | |
---|
298 | @param requestor: The entity the request originated from. |
---|
299 | @type requestor: L{jid.JID} |
---|
300 | @param service: The entity the request was addressed to. |
---|
301 | @type service: L{jid.JID} |
---|
302 | @param nodeIdentifier: The identifier of the node to publish to. |
---|
303 | @type nodeIdentifier: C{unicode} |
---|
304 | @param items: The items to be published as L{domish} elements. |
---|
305 | @type items: C{list} of C{domish.Element} |
---|
306 | @return: deferred that fires on success. |
---|
307 | @rtype: L{defer.Deferred} |
---|
308 | """ |
---|
309 | |
---|
310 | def subscribe(requestor, service, nodeIdentifier, subscriber): |
---|
311 | """ |
---|
312 | Called when a subscribe request has been received. |
---|
313 | |
---|
314 | @param requestor: The entity the request originated from. |
---|
315 | @type requestor: L{jid.JID} |
---|
316 | @param service: The entity the request was addressed to. |
---|
317 | @type service: L{jid.JID} |
---|
318 | @param nodeIdentifier: The identifier of the node to subscribe to. |
---|
319 | @type nodeIdentifier: C{unicode} |
---|
320 | @param subscriber: The entity to be subscribed. |
---|
321 | @type subscriber: L{jid.JID} |
---|
322 | @return: A deferred that fires with a C{str} representing the |
---|
323 | subscription state, C{'subscribed'} or C{'pending'}. |
---|
324 | @rtype: L{defer.Deferred} |
---|
325 | """ |
---|
326 | |
---|
327 | def unsubscribe(requestor, service, nodeIdentifier, subscriber): |
---|
328 | """ |
---|
329 | Called when a subscribe request has been received. |
---|
330 | |
---|
331 | @param requestor: The entity the request originated from. |
---|
332 | @type requestor: L{jid.JID} |
---|
333 | @param service: The entity the request was addressed to. |
---|
334 | @type service: L{jid.JID} |
---|
335 | @param nodeIdentifier: The identifier of the node to unsubscribe from. |
---|
336 | @type nodeIdentifier: C{unicode} |
---|
337 | @param subscriber: The entity to be unsubscribed. |
---|
338 | @type subscriber: L{jid.JID} |
---|
339 | @return: A deferred that fires with C{None} when unsubscription has |
---|
340 | succeeded. |
---|
341 | @rtype: L{defer.Deferred} |
---|
342 | """ |
---|
343 | |
---|
344 | def subscriptions(requestor, service): |
---|
345 | """ |
---|
346 | Called when a subscriptions retrieval request has been received. |
---|
347 | |
---|
348 | @param requestor: The entity the request originated from. |
---|
349 | @type requestor: L{jid.JID} |
---|
350 | @param service: The entity the request was addressed to. |
---|
351 | @type service: L{jid.JID} |
---|
352 | @return: A deferred that fires with a C{list} of suscriptions as |
---|
353 | C{tuple}s of (node identifier as C{unicode}, subscriber as |
---|
354 | L{jid.JID}, subscription state as C{str}). The subscription |
---|
355 | state can be C{'subscribed'} or C{'pending'}. |
---|
356 | @rtype: L{defer.Deferred} |
---|
357 | """ |
---|
358 | |
---|
359 | def affiliations(requestor, service): |
---|
360 | """ |
---|
361 | Called when a affiliations retrieval request has been received. |
---|
362 | |
---|
363 | @param requestor: The entity the request originated from. |
---|
364 | @type requestor: L{jid.JID} |
---|
365 | @param service: The entity the request was addressed to. |
---|
366 | @type service: L{jid.JID} |
---|
367 | @return: A deferred that fires with a C{list} of affiliations as |
---|
368 | C{tuple}s of (node identifier as C{unicode}, affiliation state |
---|
369 | as C{str}). The affiliation can be C{'owner'}, C{'publisher'}, |
---|
370 | or C{'outcast'}. |
---|
371 | @rtype: L{defer.Deferred} |
---|
372 | """ |
---|
373 | |
---|
374 | def create(requestor, service, nodeIdentifier): |
---|
375 | """ |
---|
376 | Called when a node creation request has been received. |
---|
377 | |
---|
378 | @param requestor: The entity the request originated from. |
---|
379 | @type requestor: L{jid.JID} |
---|
380 | @param service: The entity the request was addressed to. |
---|
381 | @type service: L{jid.JID} |
---|
382 | @param nodeIdentifier: The suggestion for the identifier of the node to |
---|
383 | be created. If the request did not include a |
---|
384 | suggestion for the node identifier, the value |
---|
385 | is C{None}. |
---|
386 | @type nodeIdentifier: C{unicode} or C{NoneType} |
---|
387 | @return: A deferred that fires with a C{unicode} that represents |
---|
388 | the identifier of the new node. |
---|
389 | @rtype: L{defer.Deferred} |
---|
390 | """ |
---|
391 | |
---|
392 | def getDefaultConfiguration(requestor, service): |
---|
393 | """ |
---|
394 | Called when a default node configuration request has been received. |
---|
395 | |
---|
396 | @param requestor: The entity the request originated from. |
---|
397 | @type requestor: L{jid.JID} |
---|
398 | @param service: The entity the request was addressed to. |
---|
399 | @type service: L{jid.JID} |
---|
400 | @return: A deferred that fires with a C{dict} representing the default |
---|
401 | node configuration. Keys are C{str}s that represent the |
---|
402 | field name. Values can be of types C{unicode}, C{int} or |
---|
403 | C{bool}. |
---|
404 | @rtype: L{defer.Deferred} |
---|
405 | """ |
---|
406 | |
---|
407 | def getConfiguration(requestor, service, nodeIdentifier): |
---|
408 | """ |
---|
409 | Called when a node configuration retrieval request has been received. |
---|
410 | |
---|
411 | @param requestor: The entity the request originated from. |
---|
412 | @type requestor: L{jid.JID} |
---|
413 | @param service: The entity the request was addressed to. |
---|
414 | @type service: L{jid.JID} |
---|
415 | @param nodeIdentifier: The identifier of the node to retrieve the |
---|
416 | configuration from. |
---|
417 | @type nodeIdentifier: C{unicode} |
---|
418 | @return: A deferred that fires with a C{dict} representing the node |
---|
419 | configuration. Keys are C{str}s that represent the field name. |
---|
420 | Values can be of types C{unicode}, C{int} or C{bool}. |
---|
421 | @rtype: L{defer.Deferred} |
---|
422 | """ |
---|
423 | |
---|
424 | def setConfiguration(requestor, service, nodeIdentifier, options): |
---|
425 | """ |
---|
426 | Called when a node configuration change request has been received. |
---|
427 | |
---|
428 | @param requestor: The entity the request originated from. |
---|
429 | @type requestor: L{jid.JID} |
---|
430 | @param service: The entity the request was addressed to. |
---|
431 | @type service: L{jid.JID} |
---|
432 | @param nodeIdentifier: The identifier of the node to change the |
---|
433 | configuration of. |
---|
434 | @type nodeIdentifier: C{unicode} |
---|
435 | @return: A deferred that fires with C{None} when the node's |
---|
436 | configuration has been changed. |
---|
437 | @rtype: L{defer.Deferred} |
---|
438 | """ |
---|
439 | |
---|
440 | def items(requestor, service, nodeIdentifier, maxItems, itemIdentifiers): |
---|
441 | """ |
---|
442 | Called when a items retrieval request has been received. |
---|
443 | |
---|
444 | @param requestor: The entity the request originated from. |
---|
445 | @type requestor: L{jid.JID} |
---|
446 | @param service: The entity the request was addressed to. |
---|
447 | @type service: L{jid.JID} |
---|
448 | @param nodeIdentifier: The identifier of the node to retrieve items |
---|
449 | from. |
---|
450 | @type nodeIdentifier: C{unicode} |
---|
451 | """ |
---|
452 | |
---|
453 | def retract(requestor, service, nodeIdentifier, itemIdentifiers): |
---|
454 | """ |
---|
455 | Called when a item retraction request has been received. |
---|
456 | |
---|
457 | @param requestor: The entity the request originated from. |
---|
458 | @type requestor: L{jid.JID} |
---|
459 | @param service: The entity the request was addressed to. |
---|
460 | @type service: L{jid.JID} |
---|
461 | @param nodeIdentifier: The identifier of the node to retract items |
---|
462 | from. |
---|
463 | @type nodeIdentifier: C{unicode} |
---|
464 | """ |
---|
465 | |
---|
466 | def purge(requestor, service, nodeIdentifier): |
---|
467 | """ |
---|
468 | Called when a node purge request has been received. |
---|
469 | |
---|
470 | @param requestor: The entity the request originated from. |
---|
471 | @type requestor: L{jid.JID} |
---|
472 | @param service: The entity the request was addressed to. |
---|
473 | @type service: L{jid.JID} |
---|
474 | @param nodeIdentifier: The identifier of the node to be purged. |
---|
475 | @type nodeIdentifier: C{unicode} |
---|
476 | """ |
---|
477 | |
---|
478 | def delete(requestor, service, nodeIdentifier): |
---|
479 | """ |
---|
480 | Called when a node deletion request has been received. |
---|
481 | |
---|
482 | @param requestor: The entity the request originated from. |
---|
483 | @type requestor: L{jid.JID} |
---|
484 | @param service: The entity the request was addressed to. |
---|
485 | @type service: L{jid.JID} |
---|
486 | @param nodeIdentifier: The identifier of the node to be delete. |
---|
487 | @type nodeIdentifier: C{unicode} |
---|
488 | """ |
---|