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 | parent = Attribute("""XML stream manager for this handler""") |
---|
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 | |
---|
29 | def disownHandlerParent(parent): |
---|
30 | """ |
---|
31 | Remove the parent of the handler. |
---|
32 | |
---|
33 | @type parent: L{IXMPPHandlerCollection} |
---|
34 | """ |
---|
35 | |
---|
36 | |
---|
37 | def makeConnection(xs): |
---|
38 | """ |
---|
39 | A connection over the underlying transport of the XML stream has been |
---|
40 | established. |
---|
41 | |
---|
42 | At this point, no traffic has been exchanged over the XML stream |
---|
43 | given in C{xs}. |
---|
44 | |
---|
45 | This should setup L{xmlstream} and call L{connectionMade}. |
---|
46 | |
---|
47 | @type xs: L{XmlStream<twisted.words.protocols.jabber.XmlStream>} |
---|
48 | """ |
---|
49 | |
---|
50 | |
---|
51 | def connectionMade(): |
---|
52 | """ |
---|
53 | Called after a connection has been established. |
---|
54 | |
---|
55 | This method can be used to change properties of the XML Stream, its |
---|
56 | authenticator or the stream manager prior to stream initialization |
---|
57 | (including authentication). |
---|
58 | """ |
---|
59 | |
---|
60 | |
---|
61 | def connectionInitialized(): |
---|
62 | """ |
---|
63 | The XML stream has been initialized. |
---|
64 | |
---|
65 | At this point, authentication was successful, and XML stanzas can be |
---|
66 | exchanged over the XML stream L{xmlstream}. This method can be |
---|
67 | used to setup observers for incoming stanzas. |
---|
68 | """ |
---|
69 | |
---|
70 | |
---|
71 | def connectionLost(reason): |
---|
72 | """ |
---|
73 | The XML stream has been closed. |
---|
74 | |
---|
75 | Subsequent use of L{parent.send} will result in data being queued |
---|
76 | until a new connection has been established. |
---|
77 | |
---|
78 | @type reason: L{twisted.python.failure.Failure} |
---|
79 | """ |
---|
80 | |
---|
81 | |
---|
82 | |
---|
83 | class IXMPPHandlerCollection(Interface): |
---|
84 | """ |
---|
85 | Collection of handlers. |
---|
86 | |
---|
87 | Contain several handlers and manage their connection. |
---|
88 | """ |
---|
89 | |
---|
90 | def __iter__(): |
---|
91 | """ |
---|
92 | Get an iterator over all child handlers. |
---|
93 | """ |
---|
94 | |
---|
95 | |
---|
96 | def addHandler(handler): |
---|
97 | """ |
---|
98 | Add a child handler. |
---|
99 | |
---|
100 | @type handler: L{IXMPPHandler} |
---|
101 | """ |
---|
102 | |
---|
103 | |
---|
104 | def removeHandler(handler): |
---|
105 | """ |
---|
106 | Remove a child handler. |
---|
107 | |
---|
108 | @type handler: L{IXMPPHandler} |
---|
109 | """ |
---|
110 | |
---|
111 | |
---|
112 | |
---|
113 | class IDisco(Interface): |
---|
114 | """ |
---|
115 | Interface for XMPP service discovery. |
---|
116 | """ |
---|
117 | |
---|
118 | def getDiscoInfo(requestor, target, nodeIdentifier=''): |
---|
119 | """ |
---|
120 | Get identity and features from this entity, node. |
---|
121 | |
---|
122 | @param requestor: The entity the request originated from. |
---|
123 | @type requestor: L{jid.JID} |
---|
124 | @param target: The target entity to which the request is made. |
---|
125 | @type target: L{jid.JID} |
---|
126 | @param nodeIdentifier: The optional identifier of the node at this |
---|
127 | entity to retrieve the identify and features of. |
---|
128 | The default is C{''}, meaning the root node. |
---|
129 | @type nodeIdentifier: C{unicode} |
---|
130 | """ |
---|
131 | |
---|
132 | def getDiscoItems(requestor, target, nodeIdentifier=''): |
---|
133 | """ |
---|
134 | Get contained items for this entity, node. |
---|
135 | |
---|
136 | @param requestor: The entity the request originated from. |
---|
137 | @type requestor: L{jid.JID} |
---|
138 | @param target: The target entity to which the request is made. |
---|
139 | @type target: L{jid.JID} |
---|
140 | @param nodeIdentifier: The optional identifier of the node at this |
---|
141 | entity to retrieve the identify and features of. |
---|
142 | The default is C{''}, meaning the root node. |
---|
143 | @type nodeIdentifier: C{unicode} |
---|
144 | """ |
---|
145 | |
---|
146 | |
---|
147 | class IPubSubClient(Interface): |
---|
148 | |
---|
149 | def itemsReceived(event): |
---|
150 | """ |
---|
151 | Called when an items notification has been received for a node. |
---|
152 | |
---|
153 | An item can be an element named C{item} or C{retract}. Respectively, |
---|
154 | they signal an item being published or retracted, optionally |
---|
155 | accompanied with an item identifier in the C{id} attribute. |
---|
156 | |
---|
157 | @param event: The items event. |
---|
158 | @type event: L{ItemsEvent<wokkel.pubsub.ItemsEvent>} |
---|
159 | """ |
---|
160 | |
---|
161 | |
---|
162 | def deleteReceived(event): |
---|
163 | """ |
---|
164 | Called when a deletion notification has been received for a node. |
---|
165 | |
---|
166 | @param event: The items event. |
---|
167 | @type event: L{ItemsEvent<wokkel.pubsub.DeleteEvent>} |
---|
168 | """ |
---|
169 | |
---|
170 | |
---|
171 | def purgeReceived(event): |
---|
172 | """ |
---|
173 | Called when a purge notification has been received for a node. |
---|
174 | |
---|
175 | Upon receiving this notification all items associated should be |
---|
176 | considered retracted. |
---|
177 | |
---|
178 | @param event: The items event. |
---|
179 | @type event: L{ItemsEvent<wokkel.pubsub.PurgeEvent>} |
---|
180 | """ |
---|
181 | |
---|
182 | def createNode(service, nodeIdentifier=None): |
---|
183 | """ |
---|
184 | Create a new publish subscribe node. |
---|
185 | |
---|
186 | @param service: The publish-subscribe service entity. |
---|
187 | @type service: L{jid.JID} |
---|
188 | @param nodeIdentifier: Optional suggestion for the new node's |
---|
189 | identifier. If omitted, the creation of an |
---|
190 | instant node will be attempted. |
---|
191 | @type nodeIdentifier: L{unicode} |
---|
192 | @return: a deferred that fires with the identifier of the newly created |
---|
193 | node. Note that this can differ from the suggested identifier |
---|
194 | if the publish subscribe service chooses to modify or ignore |
---|
195 | the suggested identifier. |
---|
196 | @rtype: L{defer.Deferred} |
---|
197 | """ |
---|
198 | |
---|
199 | def deleteNode(service, nodeIdentifier): |
---|
200 | """ |
---|
201 | Delete a node. |
---|
202 | |
---|
203 | @param service: The publish-subscribe service entity. |
---|
204 | @type service: L{jid.JID} |
---|
205 | @param nodeIdentifier: Identifier of the node to be deleted. |
---|
206 | @type nodeIdentifier: L{unicode} |
---|
207 | @rtype: L{defer.Deferred} |
---|
208 | """ |
---|
209 | |
---|
210 | def subscribe(service, nodeIdentifier, subscriber): |
---|
211 | """ |
---|
212 | Subscribe to a node with a given JID. |
---|
213 | |
---|
214 | @param service: The publish-subscribe service entity. |
---|
215 | @type service: L{jid.JID} |
---|
216 | @param nodeIdentifier: Identifier of the node to subscribe to. |
---|
217 | @type nodeIdentifier: L{unicode} |
---|
218 | @param subscriber: JID to subscribe to the node. |
---|
219 | @type subscriber: L{jid.JID} |
---|
220 | @rtype: L{defer.Deferred} |
---|
221 | """ |
---|
222 | |
---|
223 | def unsubscribe(service, nodeIdentifier, subscriber): |
---|
224 | """ |
---|
225 | Unsubscribe from a node with a given JID. |
---|
226 | |
---|
227 | @param service: The publish-subscribe service entity. |
---|
228 | @type service: L{jid.JID} |
---|
229 | @param nodeIdentifier: Identifier of the node to unsubscribe from. |
---|
230 | @type nodeIdentifier: L{unicode} |
---|
231 | @param subscriber: JID to unsubscribe from the node. |
---|
232 | @type subscriber: L{jid.JID} |
---|
233 | @rtype: L{defer.Deferred} |
---|
234 | """ |
---|
235 | |
---|
236 | def publish(service, nodeIdentifier, items=[]): |
---|
237 | """ |
---|
238 | Publish to a node. |
---|
239 | |
---|
240 | Node that the C{items} parameter is optional, because so-called |
---|
241 | transient, notification-only nodes do not use items and publish |
---|
242 | actions only signify a change in some resource. |
---|
243 | |
---|
244 | @param service: The publish-subscribe service entity. |
---|
245 | @type service: L{jid.JID} |
---|
246 | @param nodeIdentifier: Identifier of the node to publish to. |
---|
247 | @type nodeIdentifier: L{unicode} |
---|
248 | @param items: List of item elements. |
---|
249 | @type items: L{list} of L{Item} |
---|
250 | @rtype: L{defer.Deferred} |
---|
251 | """ |
---|
252 | |
---|
253 | |
---|
254 | class IPubSubService(Interface): |
---|
255 | """ |
---|
256 | Interface for an XMPP Publish Subscribe Service. |
---|
257 | |
---|
258 | All methods that are called as the result of an XMPP request are to |
---|
259 | return a deferred that fires when the requested action has been performed. |
---|
260 | Alternatively, exceptions maybe raised directly or by calling C{errback} |
---|
261 | on the returned deferred. |
---|
262 | """ |
---|
263 | |
---|
264 | def notifyPublish(service, nodeIdentifier, notifications): |
---|
265 | """ |
---|
266 | Send out notifications for a publish event. |
---|
267 | |
---|
268 | @param service: The entity the notifications will originate from. |
---|
269 | @type service: L{jid.JID} |
---|
270 | @param nodeIdentifier: The identifier of the node that was published |
---|
271 | to. |
---|
272 | @type nodeIdentifier: C{unicode} |
---|
273 | @param notifications: The notifications as tuples of subscriber, the |
---|
274 | list of subscriptions and the list of items to be |
---|
275 | notified. |
---|
276 | @type notifications: C{list} of (L{jid.JID}, C{list} of |
---|
277 | L{Subscription<wokkel.pubsub.Subscription>}, |
---|
278 | C{list} of L{domish.Element}) |
---|
279 | """ |
---|
280 | |
---|
281 | def notifyDelete(service, nodeIdentifier, subscribers, |
---|
282 | redirectURI=None): |
---|
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 subscribers: The subscribers for which a notification should |
---|
291 | be sent out. |
---|
292 | @type subscribers: C{list} of L{jid.JID} |
---|
293 | @param redirectURI: Optional XMPP URI of another node that subscribers |
---|
294 | are redirected to. |
---|
295 | @type redirectURI: C{str} |
---|
296 | """ |
---|
297 | |
---|
298 | def publish(requestor, service, nodeIdentifier, items): |
---|
299 | """ |
---|
300 | Called when a publish request has been received. |
---|
301 | |
---|
302 | @param requestor: The entity the request originated from. |
---|
303 | @type requestor: L{jid.JID} |
---|
304 | @param service: The entity the request was addressed to. |
---|
305 | @type service: L{jid.JID} |
---|
306 | @param nodeIdentifier: The identifier of the node to publish to. |
---|
307 | @type nodeIdentifier: C{unicode} |
---|
308 | @param items: The items to be published as L{domish} elements. |
---|
309 | @type items: C{list} of C{domish.Element} |
---|
310 | @return: deferred that fires on success. |
---|
311 | @rtype: L{defer.Deferred} |
---|
312 | """ |
---|
313 | |
---|
314 | def subscribe(requestor, service, nodeIdentifier, subscriber): |
---|
315 | """ |
---|
316 | Called when a subscribe 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 | @param nodeIdentifier: The identifier of the node to subscribe to. |
---|
323 | @type nodeIdentifier: C{unicode} |
---|
324 | @param subscriber: The entity to be subscribed. |
---|
325 | @type subscriber: L{jid.JID} |
---|
326 | @return: A deferred that fires with a |
---|
327 | L{Subscription<wokkel.pubsub.Subscription>}. |
---|
328 | @rtype: L{defer.Deferred} |
---|
329 | """ |
---|
330 | |
---|
331 | def unsubscribe(requestor, service, nodeIdentifier, subscriber): |
---|
332 | """ |
---|
333 | Called when a subscribe request has been received. |
---|
334 | |
---|
335 | @param requestor: The entity the request originated from. |
---|
336 | @type requestor: L{jid.JID} |
---|
337 | @param service: The entity the request was addressed to. |
---|
338 | @type service: L{jid.JID} |
---|
339 | @param nodeIdentifier: The identifier of the node to unsubscribe from. |
---|
340 | @type nodeIdentifier: C{unicode} |
---|
341 | @param subscriber: The entity to be unsubscribed. |
---|
342 | @type subscriber: L{jid.JID} |
---|
343 | @return: A deferred that fires with C{None} when unsubscription has |
---|
344 | succeeded. |
---|
345 | @rtype: L{defer.Deferred} |
---|
346 | """ |
---|
347 | |
---|
348 | def subscriptions(requestor, service): |
---|
349 | """ |
---|
350 | Called when a subscriptions 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 subscriptions as |
---|
357 | L{Subscription<wokkel.pubsub.Subscription>}. |
---|
358 | @rtype: L{defer.Deferred} |
---|
359 | """ |
---|
360 | |
---|
361 | def affiliations(requestor, service): |
---|
362 | """ |
---|
363 | Called when a affiliations retrieval request has been received. |
---|
364 | |
---|
365 | @param requestor: The entity the request originated from. |
---|
366 | @type requestor: L{jid.JID} |
---|
367 | @param service: The entity the request was addressed to. |
---|
368 | @type service: L{jid.JID} |
---|
369 | @return: A deferred that fires with a C{list} of affiliations as |
---|
370 | C{tuple}s of (node identifier as C{unicode}, affiliation state |
---|
371 | as C{str}). The affiliation can be C{'owner'}, C{'publisher'}, |
---|
372 | or C{'outcast'}. |
---|
373 | @rtype: L{defer.Deferred} |
---|
374 | """ |
---|
375 | |
---|
376 | def create(requestor, service, nodeIdentifier): |
---|
377 | """ |
---|
378 | Called when a node creation request has been received. |
---|
379 | |
---|
380 | @param requestor: The entity the request originated from. |
---|
381 | @type requestor: L{jid.JID} |
---|
382 | @param service: The entity the request was addressed to. |
---|
383 | @type service: L{jid.JID} |
---|
384 | @param nodeIdentifier: The suggestion for the identifier of the node to |
---|
385 | be created. If the request did not include a |
---|
386 | suggestion for the node identifier, the value |
---|
387 | is C{None}. |
---|
388 | @type nodeIdentifier: C{unicode} or C{NoneType} |
---|
389 | @return: A deferred that fires with a C{unicode} that represents |
---|
390 | the identifier of the new node. |
---|
391 | @rtype: L{defer.Deferred} |
---|
392 | """ |
---|
393 | |
---|
394 | def getConfigurationOptions(): |
---|
395 | """ |
---|
396 | Retrieve all known node configuration options. |
---|
397 | |
---|
398 | The returned dictionary holds the possible node configuration options |
---|
399 | by option name. The value of each entry represents the specifics for |
---|
400 | that option in a dictionary: |
---|
401 | |
---|
402 | - C{'type'} (C{str}): The option's type (see |
---|
403 | L{Field<wokkel.data_form.Field>}'s doc string for possible values). |
---|
404 | - C{'label'} (C{unicode}): A human readable label for this option. |
---|
405 | - C{'options'} (C{dict}): Optional list of possible values for this |
---|
406 | option. |
---|
407 | |
---|
408 | Example:: |
---|
409 | |
---|
410 | { |
---|
411 | "pubsub#persist_items": |
---|
412 | {"type": "boolean", |
---|
413 | "label": "Persist items to storage"}, |
---|
414 | "pubsub#deliver_payloads": |
---|
415 | {"type": "boolean", |
---|
416 | "label": "Deliver payloads with event notifications"}, |
---|
417 | "pubsub#send_last_published_item": |
---|
418 | {"type": "list-single", |
---|
419 | "label": "When to send the last published item", |
---|
420 | "options": { |
---|
421 | "never": "Never", |
---|
422 | "on_sub": "When a new subscription is processed"} |
---|
423 | } |
---|
424 | } |
---|
425 | |
---|
426 | @rtype: C{dict}. |
---|
427 | """ |
---|
428 | |
---|
429 | def getDefaultConfiguration(requestor, service, nodeType): |
---|
430 | """ |
---|
431 | Called when a default node configuration request has been received. |
---|
432 | |
---|
433 | @param requestor: The entity the request originated from. |
---|
434 | @type requestor: L{jid.JID} |
---|
435 | @param service: The entity the request was addressed to. |
---|
436 | @type service: L{jid.JID} |
---|
437 | @param nodeType: The type of node for which the configuration is |
---|
438 | retrieved, C{'leaf'} or C{'collection'}. |
---|
439 | @type nodeType: C{str} |
---|
440 | @return: A deferred that fires with a C{dict} representing the default |
---|
441 | node configuration. Keys are C{str}s that represent the |
---|
442 | field name. Values can be of types C{unicode}, C{int} or |
---|
443 | C{bool}. |
---|
444 | @rtype: L{defer.Deferred} |
---|
445 | """ |
---|
446 | |
---|
447 | def getConfiguration(requestor, service, nodeIdentifier): |
---|
448 | """ |
---|
449 | Called when a node configuration retrieval request has been received. |
---|
450 | |
---|
451 | @param requestor: The entity the request originated from. |
---|
452 | @type requestor: L{jid.JID} |
---|
453 | @param service: The entity the request was addressed to. |
---|
454 | @type service: L{jid.JID} |
---|
455 | @param nodeIdentifier: The identifier of the node to retrieve the |
---|
456 | configuration from. |
---|
457 | @type nodeIdentifier: C{unicode} |
---|
458 | @return: A deferred that fires with a C{dict} representing the node |
---|
459 | configuration. Keys are C{str}s that represent the field name. |
---|
460 | Values can be of types C{unicode}, C{int} or C{bool}. |
---|
461 | @rtype: L{defer.Deferred} |
---|
462 | """ |
---|
463 | |
---|
464 | def setConfiguration(requestor, service, nodeIdentifier, options): |
---|
465 | """ |
---|
466 | Called when a node configuration change 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 change the |
---|
473 | configuration of. |
---|
474 | @type nodeIdentifier: C{unicode} |
---|
475 | @return: A deferred that fires with C{None} when the node's |
---|
476 | configuration has been changed. |
---|
477 | @rtype: L{defer.Deferred} |
---|
478 | """ |
---|
479 | |
---|
480 | def items(requestor, service, nodeIdentifier, maxItems, itemIdentifiers): |
---|
481 | """ |
---|
482 | Called when a items retrieval request has been received. |
---|
483 | |
---|
484 | @param requestor: The entity the request originated from. |
---|
485 | @type requestor: L{jid.JID} |
---|
486 | @param service: The entity the request was addressed to. |
---|
487 | @type service: L{jid.JID} |
---|
488 | @param nodeIdentifier: The identifier of the node to retrieve items |
---|
489 | from. |
---|
490 | @type nodeIdentifier: C{unicode} |
---|
491 | """ |
---|
492 | |
---|
493 | def retract(requestor, service, nodeIdentifier, itemIdentifiers): |
---|
494 | """ |
---|
495 | Called when a item retraction request has been received. |
---|
496 | |
---|
497 | @param requestor: The entity the request originated from. |
---|
498 | @type requestor: L{jid.JID} |
---|
499 | @param service: The entity the request was addressed to. |
---|
500 | @type service: L{jid.JID} |
---|
501 | @param nodeIdentifier: The identifier of the node to retract items |
---|
502 | from. |
---|
503 | @type nodeIdentifier: C{unicode} |
---|
504 | """ |
---|
505 | |
---|
506 | def purge(requestor, service, nodeIdentifier): |
---|
507 | """ |
---|
508 | Called when a node purge request has been received. |
---|
509 | |
---|
510 | @param requestor: The entity the request originated from. |
---|
511 | @type requestor: L{jid.JID} |
---|
512 | @param service: The entity the request was addressed to. |
---|
513 | @type service: L{jid.JID} |
---|
514 | @param nodeIdentifier: The identifier of the node to be purged. |
---|
515 | @type nodeIdentifier: C{unicode} |
---|
516 | """ |
---|
517 | |
---|
518 | def delete(requestor, service, nodeIdentifier): |
---|
519 | """ |
---|
520 | Called when a node deletion request has been received. |
---|
521 | |
---|
522 | @param requestor: The entity the request originated from. |
---|
523 | @type requestor: L{jid.JID} |
---|
524 | @param service: The entity the request was addressed to. |
---|
525 | @type service: L{jid.JID} |
---|
526 | @param nodeIdentifier: The identifier of the node to be delete. |
---|
527 | @type nodeIdentifier: C{unicode} |
---|
528 | """ |
---|