1 | # Copyright (c) 2003-2007 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 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 | |
---|
63 | class 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 | class IPubSubService(Interface): |
---|
93 | """ |
---|
94 | Interface for an XMPP Publish Subscribe Service. |
---|
95 | |
---|
96 | All methods that are called as the result of an XMPP request are to |
---|
97 | return a deferred that fires when the requested action has been performed. |
---|
98 | Alternatively, exceptions maybe raised directly or by calling C{errback} |
---|
99 | on the returned deferred. |
---|
100 | """ |
---|
101 | |
---|
102 | def notifyPublish(entity, nodeIdentifier, notifications): |
---|
103 | """ |
---|
104 | Send out notifications for a publish event. |
---|
105 | |
---|
106 | @param entity: The entity the notifications will originate from. |
---|
107 | @type entity: L{jid.JID} |
---|
108 | @param nodeIdentifier: The identifier of the node that was published |
---|
109 | to. |
---|
110 | @type nodeIdentifier: C{unicode} |
---|
111 | @param notifications: The notifications as tuples of subscriber and |
---|
112 | the list of items to be notified. |
---|
113 | @type notifications: C{list} of (L{jid.JID}, C{list} of |
---|
114 | L{domish.Element}) |
---|
115 | """ |
---|
116 | |
---|
117 | def publish(requestor, nodeIdentifier, items): |
---|
118 | """ |
---|
119 | Called when a publish request has been received. |
---|
120 | |
---|
121 | @param requestor: The entity the request originated from. |
---|
122 | @type requestor: L{jid.JID} |
---|
123 | @param nodeIdentifier: The identifier of the node to publish to. |
---|
124 | @type nodeIdentifier: C{unicode} |
---|
125 | @param items: The items to be published as L{domish} elements. |
---|
126 | @type items: C{list} of C{domish.Element} |
---|
127 | @return: deferred that fires on success. |
---|
128 | @rtype: L{defer.Deferred} |
---|
129 | """ |
---|
130 | |
---|
131 | def subscribe(requestor, nodeIdentifier, subscriber): |
---|
132 | """ |
---|
133 | Called when a subscribe request has been received. |
---|
134 | |
---|
135 | @param requestor: The entity the request originated from. |
---|
136 | @type requestor: L{jid.JID} |
---|
137 | @param nodeIdentifier: The identifier of the node to subscribe to. |
---|
138 | @type nodeIdentifier: C{unicode} |
---|
139 | @param subscriber: The entity to be subscribed. |
---|
140 | @type subscriber: L{jid.JID} |
---|
141 | @return: A deferred that fires with a C{str} representing the |
---|
142 | subscription state, C{'subscribed'} or C{'pending'}. |
---|
143 | @rtype: L{defer.Deferred} |
---|
144 | """ |
---|
145 | |
---|
146 | def unsubscribe(requestor, nodeIdentifier, subscriber): |
---|
147 | """ |
---|
148 | Called when a subscribe request has been received. |
---|
149 | |
---|
150 | @param requestor: The entity the request originated from. |
---|
151 | @type requestor: L{jid.JID} |
---|
152 | @param nodeIdentifier: The identifier of the node to unsubscribe from. |
---|
153 | @type nodeIdentifier: C{unicode} |
---|
154 | @param subscriber: The entity to be unsubscribed. |
---|
155 | @type subscriber: L{jid.JID} |
---|
156 | @return: A deferred that fires with C{None} when unsubscription has |
---|
157 | succeeded. |
---|
158 | @rtype: L{defer.Deferred} |
---|
159 | """ |
---|
160 | |
---|
161 | def subscriptions(requestor): |
---|
162 | """ |
---|
163 | Called when a subscriptions retrieval request has been received. |
---|
164 | |
---|
165 | @param requestor: The entity the request originated from. |
---|
166 | @type requestor: L{jid.JID} |
---|
167 | @return: A deferred that fires with a C{list} of suscriptions as |
---|
168 | C{tuple}s of (node identifier as C{unicode}, subscriber as |
---|
169 | L{jid.JID}, subscription state as C{str}). The subscription |
---|
170 | state can be C{'subscribed'} or C{'pending'}. |
---|
171 | @rtype: L{defer.Deferred} |
---|
172 | """ |
---|
173 | |
---|
174 | def affiliations(requestor): |
---|
175 | """ |
---|
176 | Called when a affiliations retrieval request has been received. |
---|
177 | |
---|
178 | @param requestor: The entity the request originated from. |
---|
179 | @type requestor: L{jid.JID} |
---|
180 | @return: A deferred that fires with a C{list} of affiliations as |
---|
181 | C{tuple}s of (node identifier as C{unicode}, affiliation state |
---|
182 | as C{str}). The affiliation can be C{'owner'}, C{'publisher'}, |
---|
183 | or C{'outcast'}. |
---|
184 | @rtype: L{defer.Deferred} |
---|
185 | """ |
---|
186 | |
---|
187 | def create(requestor, nodeIdentifier): |
---|
188 | """ |
---|
189 | Called when a node creation request has been received. |
---|
190 | |
---|
191 | @param requestor: The entity the request originated from. |
---|
192 | @type requestor: L{jid.JID} |
---|
193 | @param nodeIdentifier: The suggestion for the identifier of the node to |
---|
194 | be created. If the request did not include a |
---|
195 | suggestion for the node identifier, the value |
---|
196 | is C{None}. |
---|
197 | @type nodeIdentifier: C{unicode} or C{NoneType} |
---|
198 | @return: A deferred that fires with a C{unicode} that represents |
---|
199 | the identifier of the new node. |
---|
200 | @rtype: L{defer.Deferred} |
---|
201 | """ |
---|
202 | |
---|
203 | def getDefaultConfiguration(requestor): |
---|
204 | """ |
---|
205 | Called when a default node configuration request has been received. |
---|
206 | |
---|
207 | @param requestor: The entity the request originated from. |
---|
208 | @type requestor: L{jid.JID} |
---|
209 | @return: A deferred that fires with a C{dict} representing the default |
---|
210 | node configuration. Keys are C{str}s that represent the |
---|
211 | field name. Values can be of types C{unicode}, C{int} or |
---|
212 | C{bool}. |
---|
213 | @rtype: L{defer.Deferred} |
---|
214 | """ |
---|
215 | |
---|
216 | def getConfiguration(requestor, nodeIdentifier): |
---|
217 | """ |
---|
218 | Called when a node configuration retrieval request has been received. |
---|
219 | |
---|
220 | @param requestor: The entity the request originated from. |
---|
221 | @type requestor: L{jid.JID} |
---|
222 | @param nodeIdentifier: The identifier of the node to retrieve the |
---|
223 | configuration from. |
---|
224 | @type nodeIdentifier: C{unicode} |
---|
225 | @return: A deferred that fires with a C{dict} representing the node |
---|
226 | configuration. Keys are C{str}s that represent the field name. |
---|
227 | Values can be of types C{unicode}, C{int} or C{bool}. |
---|
228 | @rtype: L{defer.Deferred} |
---|
229 | """ |
---|
230 | |
---|
231 | def setConfiguration(requestor, nodeIdentifier, options): |
---|
232 | """ |
---|
233 | Called when a node configuration change request has been received. |
---|
234 | |
---|
235 | @param requestor: The entity the request originated from. |
---|
236 | @type requestor: L{jid.JID} |
---|
237 | @param nodeIdentifier: The identifier of the node to change the |
---|
238 | configuration of. |
---|
239 | @type nodeIdentifier: C{unicode} |
---|
240 | @return: A deferred that fires with C{None} when the node's |
---|
241 | configuration has been changed. |
---|
242 | @rtype: L{defer.Deferred} |
---|
243 | """ |
---|
244 | |
---|
245 | def items(requestor, nodeIdentifier, maxItems, itemIdentifiers): |
---|
246 | """ |
---|
247 | Called when a items retrieval request has been received. |
---|
248 | |
---|
249 | @param requestor: The entity the request originated from. |
---|
250 | @type requestor: L{jid.JID} |
---|
251 | @param nodeIdentifier: The identifier of the node to retrieve items |
---|
252 | from. |
---|
253 | @type nodeIdentifier: C{unicode} |
---|
254 | """ |
---|
255 | |
---|
256 | def retract(requestor, nodeIdentifier, itemIdentifiers): |
---|
257 | """ |
---|
258 | Called when a item retraction request has been received. |
---|
259 | |
---|
260 | @param requestor: The entity the request originated from. |
---|
261 | @type requestor: L{jid.JID} |
---|
262 | @param nodeIdentifier: The identifier of the node to retract items |
---|
263 | from. |
---|
264 | @type nodeIdentifier: C{unicode} |
---|
265 | """ |
---|
266 | |
---|
267 | def purge(requestor, nodeIdentifier): |
---|
268 | """ |
---|
269 | Called when a node purge request has been received. |
---|
270 | |
---|
271 | @param requestor: The entity the request originated from. |
---|
272 | @type requestor: L{jid.JID} |
---|
273 | @param nodeIdentifier: The identifier of the node to be purged. |
---|
274 | @type nodeIdentifier: C{unicode} |
---|
275 | """ |
---|
276 | |
---|
277 | def delete(requestor, nodeIdentifier): |
---|
278 | """ |
---|
279 | Called when a node deletion request has been received. |
---|
280 | |
---|
281 | @param requestor: The entity the request originated from. |
---|
282 | @type requestor: L{jid.JID} |
---|
283 | @param nodeIdentifier: The identifier of the node to be delete. |
---|
284 | @type nodeIdentifier: C{unicode} |
---|
285 | """ |
---|
286 | |
---|
287 | |
---|