Package spade :: Package xmpp :: Module protocol
[hide private]
[frames] | no frames]

Source Code for Module spade.xmpp.protocol

  1  ##   protocol.py  
  2  ## 
  3  ##   Copyright (C) 2003-2005 Alexey "Snake" Nezhdanov 
  4  ## 
  5  ##   This program is free software; you can redistribute it and/or modify 
  6  ##   it under the terms of the GNU General Public License as published by 
  7  ##   the Free Software Foundation; either version 2, or (at your option) 
  8  ##   any later version. 
  9  ## 
 10  ##   This program is distributed in the hope that it will be useful, 
 11  ##   but WITHOUT ANY WARRANTY; without even the implied warranty of 
 12  ##   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
 13  ##   GNU General Public License for more details. 
 14   
 15  # $Id: protocol.py,v 1.53 2006/01/18 21:38:00 normanr Exp $ 
 16   
 17  """ 
 18  Protocol module contains tools that is needed for processing of  
 19  xmpp-related data structures. 
 20  """ 
 21   
 22  from simplexml import Node,ustr 
 23  import time 
 24  NS_ACTIVITY     ='http://jabber.org/protocol/activity'                  # JEP-0108 
 25  NS_ADDRESS      ='http://jabber.org/protocol/address'                   # JEP-0033 
 26  NS_AGENTS       ='jabber:iq:agents' 
 27  NS_AMP          ='http://jabber.org/protocol/amp' 
 28  NS_AMP_ERRORS   =NS_AMP+'#errors' 
 29  NS_AUTH         ='jabber:iq:auth' 
 30  NS_BIND         ='urn:ietf:params:xml:ns:xmpp-bind' 
 31  NS_BROWSE       ='jabber:iq:browse' 
 32  NS_BYTESTREAM   ='http://jabber.org/protocol/bytestreams'               # JEP-0065 
 33  NS_CAPS         ='http://jabber.org/protocol/caps'                      # JEP-0115 
 34  NS_CHATSTATES   ='http://jabber.org/protocol/chatstates'                # JEP-0085 
 35  NS_CLIENT       ='jabber:client' 
 36  NS_COMMANDS     ='http://jabber.org/protocol/commands' 
 37  NS_COMPONENT_ACCEPT='jabber:component:accept' 
 38  NS_COMPONENT_1  ='http://jabberd.jabberstudio.org/ns/component/1.0' 
 39  NS_COMPRESS     ='http://jabber.org/protocol/compress'                  # JEP-0138 
 40  NS_DATA         ='jabber:x:data'                                        # JEP-0004 
 41  NS_DELAY        ='jabber:x:delay' 
 42  NS_DIALBACK     ='jabber:server:dialback' 
 43  NS_DISCO        ='http://jabber.org/protocol/disco' 
 44  NS_DISCO_INFO   =NS_DISCO+'#info' 
 45  NS_DISCO_ITEMS  =NS_DISCO+'#items' 
 46  NS_ENCRYPTED    ='jabber:x:encrypted'                                   # JEP-0027 
 47  NS_EVENT        ='jabber:x:event'                                       # JEP-0022 
 48  NS_FEATURE      ='http://jabber.org/protocol/feature-neg'   
 49  NS_FILE         ='http://jabber.org/protocol/si/profile/file-transfer'  # JEP-0096 
 50  NS_GEOLOC       ='http://jabber.org/protocol/geoloc'                    # JEP-0080 
 51  NS_GROUPCHAT    ='gc-1.0' 
 52  NS_HTTP_BIND    ='http://jabber.org/protocol/httpbind'                  # JEP-0124 
 53  NS_IBB          ='http://jabber.org/protocol/ibb' 
 54  NS_INVISIBLE    ='presence-invisible'                                   # Jabberd2 
 55  NS_IQ           ='iq'                                                   # Jabberd2 
 56  NS_LAST         ='jabber:iq:last' 
 57  NS_MESSAGE      ='message'                                              # Jabberd2 
 58  NS_MOOD         ='http://jabber.org/protocol/mood'                      # JEP-0107 
 59  NS_MUC          ='http://jabber.org/protocol/muc' 
 60  NS_MUC_USER     =NS_MUC+'#user' 
 61  NS_MUC_ADMIN    =NS_MUC+'#admin' 
 62  NS_MUC_OWNER    =NS_MUC+'#owner' 
 63  NS_OFFLINE      ='http://www.jabber.org/jeps/jep-0030.html'             # JEP-0013 
 64  NS_PHYSLOC      ='http://jabber.org/protocol/physloc'                   # JEP-0112 
 65  NS_PRESENCE     ='presence'                                             # Jabberd2 
 66  NS_PRIVACY      ='jabber:iq:privacy' 
 67  NS_PRIVATE      ='jabber:iq:private' 
 68  NS_PUBSUB       ='http://jabber.org/protocol/pubsub'                    # XEP-0060 
 69  NS_PUBSUB_ERRORS=NS_PUBSUB+'#errors' 
 70  NS_PUBSUB_EVENTS=NS_PUBSUB+'#events' 
 71  NS_PUBSUB_OWNER =NS_PUBSUB+'#owner' 
 72  NS_REGISTER     ='jabber:iq:register' 
 73  NS_ROSTER       ='jabber:iq:roster' 
 74  NS_ROSTERX      ='http://jabber.org/protocol/rosterx'                   # JEP-0144 
 75  NS_RPC          ='jabber:iq:rpc'                                        # JEP-0009 
 76  NS_SASL         ='urn:ietf:params:xml:ns:xmpp-sasl' 
 77  NS_SEARCH       ='jabber:iq:search' 
 78  NS_SERVER       ='jabber:server' 
 79  NS_SESSION      ='urn:ietf:params:xml:ns:xmpp-session' 
 80  NS_SI           ='http://jabber.org/protocol/si'                        # JEP-0096 
 81  NS_SI_PUB       ='http://jabber.org/protocol/sipub'                     # JEP-0137 
 82  NS_SIGNED       ='jabber:x:signed'                                      # JEP-0027 
 83  NS_STANZAS      ='urn:ietf:params:xml:ns:xmpp-stanzas' 
 84  NS_STREAMS      ='http://etherx.jabber.org/streams' 
 85  NS_TIME         ='jabber:iq:time' 
 86  NS_TLS          ='urn:ietf:params:xml:ns:xmpp-tls' 
 87  NS_VACATION     ='http://jabber.org/protocol/vacation' 
 88  NS_VCARD        ='vcard-temp' 
 89  NS_VERSION      ='jabber:iq:version' 
 90  NS_WAITINGLIST  ='http://jabber.org/protocol/waitinglist'               # JEP-0130 
 91  NS_XHTML_IM     ='http://jabber.org/protocol/xhtml-im'                  # JEP-0071 
 92  NS_DATA_LAYOUT  ='http://jabber.org/protocol/xdata-layout'              # JEP-0141 
 93  NS_DATA_VALIDATE='http://jabber.org/protocol/xdata-validate'            # JEP-0122 
 94  NS_XMPP_STREAMS ='urn:ietf:params:xml:ns:xmpp-streams' 
 95   
 96  xmpp_stream_error_conditions=""" 
 97  bad-format --  --  -- The entity has sent XML that cannot be processed. 
 98  bad-namespace-prefix --  --  -- The entity has sent a namespace prefix that is unsupported, or has sent no namespace prefix on an element that requires such a prefix. 
 99  conflict --  --  -- The server is closing the active stream for this entity because a new stream has been initiated that conflicts with the existing stream. 
100  connection-timeout --  --  -- The entity has not generated any traffic over the stream for some period of time. 
101  host-gone --  --  -- The value of the 'to' attribute provided by the initiating entity in the stream header corresponds to a hostname that is no longer hosted by the server. 
102  host-unknown --  --  -- The value of the 'to' attribute provided by the initiating entity in the stream header does not correspond to a hostname that is hosted by the server. 
103  improper-addressing --  --  -- A stanza sent between two servers lacks a 'to' or 'from' attribute (or the attribute has no value). 
104  internal-server-error --  --  -- The server has experienced a misconfiguration or an otherwise-undefined internal error that prevents it from servicing the stream. 
105  invalid-from -- cancel --  -- The JID or hostname provided in a 'from' address does not match an authorized JID or validated domain negotiated between servers via SASL or dialback, or between a client and a server via authentication and resource authorization. 
106  invalid-id --  --  -- The stream ID or dialback ID is invalid or does not match an ID previously provided. 
107  invalid-namespace --  --  -- The streams namespace name is something other than "http://etherx.jabber.org/streams" or the dialback namespace name is something other than "jabber:server:dialback". 
108  invalid-xml --  --  -- The entity has sent invalid XML over the stream to a server that performs validation. 
109  not-authorized --  --  -- The entity has attempted to send data before the stream has been authenticated, or otherwise is not authorized to perform an action related to stream negotiation. 
110  policy-violation --  --  -- The entity has violated some local service policy. 
111  remote-connection-failed --  --  -- The server is unable to properly connect to a remote resource that is required for authentication or authorization. 
112  resource-constraint --  --  -- The server lacks the system resources necessary to service the stream. 
113  restricted-xml --  --  -- The entity has attempted to send restricted XML features such as a comment, processing instruction, DTD, entity reference, or unescaped character. 
114  see-other-host --  --  -- The server will not provide service to the initiating entity but is redirecting traffic to another host. 
115  system-shutdown --  --  -- The server is being shut down and all active streams are being closed. 
116  undefined-condition --  --  -- The error condition is not one of those defined by the other conditions in this list. 
117  unsupported-encoding --  --  -- The initiating entity has encoded the stream in an encoding that is not supported by the server. 
118  unsupported-stanza-type --  --  -- The initiating entity has sent a first-level child of the stream that is not supported by the server. 
119  unsupported-version --  --  -- The value of the 'version' attribute provided by the initiating entity in the stream header specifies a version of XMPP that is not supported by the server. 
120  xml-not-well-formed --  --  -- The initiating entity has sent XML that is not well-formed.""" 
121  xmpp_stanza_error_conditions=""" 
122  bad-request -- 400 -- modify -- The sender has sent XML that is malformed or that cannot be processed. 
123  conflict -- 409 -- cancel -- Access cannot be granted because an existing resource or session exists with the same name or address. 
124  feature-not-implemented -- 501 -- cancel -- The feature requested is not implemented by the recipient or server and therefore cannot be processed. 
125  forbidden -- 403 -- auth -- The requesting entity does not possess the required permissions to perform the action. 
126  gone -- 302 -- modify -- The recipient or server can no longer be contacted at this address. 
127  internal-server-error -- 500 -- wait -- The server could not process the stanza because of a misconfiguration or an otherwise-undefined internal server error. 
128  item-not-found -- 404 -- cancel -- The addressed JID or item requested cannot be found. 
129  jid-malformed -- 400 -- modify -- The value of the 'to' attribute in the sender's stanza does not adhere to the syntax defined in Addressing Scheme. 
130  not-acceptable -- 406 -- modify -- The recipient or server understands the request but is refusing to process it because it does not meet criteria defined by the recipient or server. 
131  not-allowed -- 405 -- cancel -- The recipient or server does not allow any entity to perform the action. 
132  not-authorized -- 401 -- auth -- The sender must provide proper credentials before being allowed to perform the action, or has provided improper credentials. 
133  payment-required -- 402 -- auth -- The requesting entity is not authorized to access the requested service because payment is required. 
134  recipient-unavailable -- 404 -- wait -- The intended recipient is temporarily unavailable. 
135  redirect -- 302 -- modify -- The recipient or server is redirecting requests for this information to another entity. 
136  registration-required -- 407 -- auth -- The requesting entity is not authorized to access the requested service because registration is required. 
137  remote-server-not-found -- 404 -- cancel -- A remote server or service specified as part or all of the JID of the intended recipient does not exist. 
138  remote-server-timeout -- 504 -- wait -- A remote server or service specified as part or all of the JID of the intended recipient could not be contacted within a reasonable amount of time. 
139  resource-constraint -- 500 -- wait -- The server or recipient lacks the system resources necessary to service the request. 
140  service-unavailable -- 503 -- cancel -- The server or recipient does not currently provide the requested service. 
141  subscription-required -- 407 -- auth -- The requesting entity is not authorized to access the requested service because a subscription is required. 
142  undefined-condition -- 500 --  --  
143  unexpected-request -- 400 -- wait -- The recipient or server understood the request but was not expecting it at this time (e.g., the request was out of order).""" 
144  sasl_error_conditions=""" 
145  aborted --  --  -- The receiving entity acknowledges an <abort/> element sent by the initiating entity; sent in reply to the <abort/> element. 
146  incorrect-encoding --  --  -- The data provided by the initiating entity could not be processed because the [BASE64]Josefsson, S., The Base16, Base32, and Base64 Data Encodings, July 2003. encoding is incorrect (e.g., because the encoding does not adhere to the definition in Section 3 of [BASE64]Josefsson, S., The Base16, Base32, and Base64 Data Encodings, July 2003.); sent in reply to a <response/> element or an <auth/> element with initial response data. 
147  invalid-authzid --  --  -- The authzid provided by the initiating entity is invalid, either because it is incorrectly formatted or because the initiating entity does not have permissions to authorize that ID; sent in reply to a <response/> element or an <auth/> element with initial response data. 
148  invalid-mechanism --  --  -- The initiating entity did not provide a mechanism or requested a mechanism that is not supported by the receiving entity; sent in reply to an <auth/> element. 
149  mechanism-too-weak --  --  -- The mechanism requested by the initiating entity is weaker than server policy permits for that initiating entity; sent in reply to a <response/> element or an <auth/> element with initial response data. 
150  not-authorized --  --  -- The authentication failed because the initiating entity did not provide valid credentials (this includes but is not limited to the case of an unknown username); sent in reply to a <response/> element or an <auth/> element with initial response data. 
151  temporary-auth-failure --  --  -- The authentication failed because of a temporary error condition within the receiving entity; sent in reply to an <auth/> element or <response/> element.""" 
152   
153  ERRORS,_errorcodes={},{} 
154  for ns,errname,errpool in [(NS_XMPP_STREAMS,'STREAM',xmpp_stream_error_conditions), 
155                             (NS_STANZAS     ,'ERR'   ,xmpp_stanza_error_conditions), 
156                             (NS_SASL        ,'SASL'  ,sasl_error_conditions)]: 
157      for err in errpool.split('\n')[1:]: 
158          cond,code,typ,text=err.split(' -- ') 
159          name=errname+'_'+cond.upper().replace('-','_') 
160          locals()[name]=ns+' '+cond 
161          ERRORS[ns+' '+cond]=[code,typ,text] 
162          if code: _errorcodes[code]=cond 
163  del ns,errname,errpool,err,cond,code,typ,text 
164   
165 -def isResultNode(node):
166 """ Returns true if the node is a positive reply. """ 167 return node and node.getType()=='result'
168 -def isErrorNode(node):
169 """ Returns true if the node is a negative reply. """ 170 return node and node.getType()=='error'
171
172 -class NodeProcessed(Exception):
173 """ Exception that should be raised by handler when the handling should be stopped. """
174 -class StreamError(Exception):
175 """ Base exception class for stream errors."""
176 -class BadFormat(StreamError): pass
177 -class BadNamespacePrefix(StreamError): pass
178 -class Conflict(StreamError): pass
179 -class ConnectionTimeout(StreamError): pass
180 -class HostGone(StreamError): pass
181 -class HostUnknown(StreamError): pass
182 -class ImproperAddressing(StreamError): pass
183 -class InternalServerError(StreamError): pass
184 -class InvalidFrom(StreamError): pass
185 -class InvalidID(StreamError): pass
186 -class InvalidNamespace(StreamError): pass
187 -class InvalidXML(StreamError): pass
188 -class NotAuthorized(StreamError): pass
189 -class PolicyViolation(StreamError): pass
190 -class RemoteConnectionFailed(StreamError): pass
191 -class ResourceConstraint(StreamError): pass
192 -class RestrictedXML(StreamError): pass
193 -class SeeOtherHost(StreamError): pass
194 -class SystemShutdown(StreamError): pass
195 -class UndefinedCondition(StreamError): pass
196 -class UnsupportedEncoding(StreamError): pass
197 -class UnsupportedStanzaType(StreamError): pass
198 -class UnsupportedVersion(StreamError): pass
199 -class XMLNotWellFormed(StreamError): pass
200 201 stream_exceptions = {'bad-format': BadFormat, 202 'bad-namespace-prefix': BadNamespacePrefix, 203 'conflict': Conflict, 204 'connection-timeout': ConnectionTimeout, 205 'host-gone': HostGone, 206 'host-unknown': HostUnknown, 207 'improper-addressing': ImproperAddressing, 208 'internal-server-error': InternalServerError, 209 'invalid-from': InvalidFrom, 210 'invalid-id': InvalidID, 211 'invalid-namespace': InvalidNamespace, 212 'invalid-xml': InvalidXML, 213 'not-authorized': NotAuthorized, 214 'policy-violation': PolicyViolation, 215 'remote-connection-failed': RemoteConnectionFailed, 216 'resource-constraint': ResourceConstraint, 217 'restricted-xml': RestrictedXML, 218 'see-other-host': SeeOtherHost, 219 'system-shutdown': SystemShutdown, 220 'undefined-condition': UndefinedCondition, 221 'unsupported-encoding': UnsupportedEncoding, 222 'unsupported-stanza-type': UnsupportedStanzaType, 223 'unsupported-version': UnsupportedVersion, 224 'xml-not-well-formed': XMLNotWellFormed} 225
226 -class JID:
227 """ JID object. JID can be built from string, modified, compared, serialised into string. """
228 - def __init__(self, jid=None, node='', domain='', resource=''):
229 """ Constructor. JID can be specified as string (jid argument) or as separate parts. 230 Examples: 231 JID('node@domain/resource') 232 JID(node='node',domain='domain.org') 233 """ 234 if not jid and not domain: raise ValueError('JID must contain at least domain name') 235 elif type(jid)==type(self): self.node,self.domain,self.resource=jid.node,jid.domain,jid.resource 236 elif domain: self.node,self.domain,self.resource=node,domain,resource 237 else: 238 if jid.find('@')+1: self.node,jid=jid.split('@',1) 239 else: self.node='' 240 if jid.find('/')+1: self.domain,self.resource=jid.split('/',1) 241 else: self.domain,self.resource=jid,''
242 - def getNode(self):
243 """ Return the node part of the JID """ 244 return self.node
245 - def setNode(self,node):
246 """ Set the node part of the JID to new value. Specify None to remove the node part.""" 247 self.node=node.lower()
248 - def getDomain(self):
249 """ Return the domain part of the JID """ 250 return self.domain
251 - def setDomain(self,domain):
252 """ Set the domain part of the JID to new value.""" 253 self.domain=domain.lower()
254 - def getResource(self):
255 """ Return the resource part of the JID """ 256 return self.resource
257 - def setResource(self,resource):
258 """ Set the resource part of the JID to new value. Specify None to remove the resource part.""" 259 self.resource=resource
260 - def getStripped(self):
261 """ Return the bare representation of JID. I.e. string value w/o resource. """ 262 return self.__str__(0)
263 - def __eq__(self, other):
264 """ Compare the JID to another instance or to string for equality. """ 265 try: other=JID(other) 266 except ValueError: return 0 267 return self.resource==other.resource and self.__str__(0) == other.__str__(0)
268 - def __ne__(self, other):
269 """ Compare the JID to another instance or to string for non-equality. """ 270 return not self.__eq__(other)
271 - def bareMatch(self, other):
272 """ Compare the node and domain parts of the JID's for equality. """ 273 return self.__str__(0) == JID(other).__str__(0)
274 - def __str__(self,wresource=1):
275 """ Serialise JID into string. """ 276 if self.node: jid=self.node+'@'+self.domain 277 else: jid=self.domain 278 if wresource and self.resource: return jid+'/'+self.resource 279 return jid
280 - def __hash__(self):
281 """ Produce hash of the JID, Allows to use JID objects as keys of the dictionary. """ 282 return hash(self.__str__())
283
284 -class Protocol(Node):
285 """ A "stanza" object class. Contains methods that are common for presences, iqs and messages. """
286 - def __init__(self, name=None, to=None, typ=None, frm=None, attrs={}, payload=[], timestamp=None, xmlns=None, node=None):
287 """ Constructor, name is the name of the stanza i.e. 'message' or 'presence' or 'iq'. 288 to is the value of 'to' attribure, 'typ' - 'type' attribute 289 frn - from attribure, attrs - other attributes mapping, payload - same meaning as for simplexml payload definition 290 timestamp - the time value that needs to be stamped over stanza 291 xmlns - namespace of top stanza node 292 node - parsed or unparsed stanza to be taken as prototype. 293 """ 294 if not attrs: attrs={} 295 if to: attrs['to']=to 296 if frm: attrs['from']=frm 297 if typ: attrs['type']=typ 298 Node.__init__(self, tag=name, attrs=attrs, payload=payload, node=node) 299 if not node and xmlns: self.setNamespace(xmlns) 300 if self['to']: self.setTo(self['to']) 301 if self['from']: self.setFrom(self['from']) 302 if node and type(self)==type(node) and self.__class__==node.__class__ and self.attrs.has_key('id'): del self.attrs['id'] 303 self.timestamp=None 304 for x in self.getTags('x',namespace=NS_DELAY): 305 try: 306 if not self.getTimestamp() or x.getAttr('stamp')<self.getTimestamp(): self.setTimestamp(x.getAttr('stamp')) 307 except: pass 308 if timestamp is not None: self.setTimestamp(timestamp) # To auto-timestamp stanza just pass timestamp=''
309 - def getTo(self):
310 """ Return value of the 'to' attribute. """ 311 try: return self['to'] 312 except: return None
313 - def getFrom(self):
314 """ Return value of the 'from' attribute. """ 315 try: return self['from'] 316 except: return None
317 - def getTimestamp(self):
318 """ Return the timestamp in the 'yyyymmddThhmmss' format. """ 319 return self.timestamp
320 - def getID(self):
321 """ Return the value of the 'id' attribute. """ 322 return self.getAttr('id')
323 - def setTo(self,val):
324 """ Set the value of the 'to' attribute. """ 325 self.setAttr('to', JID(val))
326 - def getType(self):
327 """ Return the value of the 'type' attribute. """ 328 return self.getAttr('type')
329 - def setFrom(self,val):
330 """ Set the value of the 'from' attribute. """ 331 self.setAttr('from', JID(val))
332 - def setType(self,val):
333 """ Set the value of the 'type' attribute. """ 334 self.setAttr('type', val)
335 - def setID(self,val):
336 """ Set the value of the 'id' attribute. """ 337 self.setAttr('id', val)
338 - def getError(self):
339 """ Return the error-condition (if present) or the textual description of the error (otherwise). """ 340 errtag=self.getTag('error') 341 if errtag: 342 for tag in errtag.getChildren(): 343 if tag.getName()<>'text': return tag.getName() 344 return errtag.getData()
345 - def getErrorCode(self):
346 """ Return the error code. Obsolette. """ 347 return self.getTagAttr('error','code')
348 - def setError(self,error,code=None):
349 """ Set the error code. Obsolette. Use error-conditions instead. """ 350 if code: 351 if str(code) in _errorcodes.keys(): error=ErrorNode(_errorcodes[str(code)],text=error) 352 else: error=ErrorNode(ERR_UNDEFINED_CONDITION,code=code,typ='cancel',text=error) 353 elif type(error) in [type(''),type(u'')]: error=ErrorNode(error) 354 self.setType('error') 355 self.addChild(node=error)
356 - def setTimestamp(self,val=None):
357 """Set the timestamp. timestamp should be the yyyymmddThhmmss string.""" 358 if not val: val=time.strftime('%Y%m%dT%H:%M:%S', time.gmtime()) 359 self.timestamp=val 360 self.setTag('x',{'stamp':self.timestamp},namespace=NS_DELAY)
361 - def getProperties(self):
362 """ Return the list of namespaces to which belongs the direct childs of element""" 363 props=[] 364 for child in self.getChildren(): 365 prop=child.getNamespace() 366 if prop not in props: props.append(prop) 367 return props
368 - def __setitem__(self,item,val):
369 """ Set the item 'item' to the value 'val'.""" 370 if item in ['to','from']: val=JID(val) 371 return self.setAttr(item,val)
372
373 -class Message(Protocol):
374 """ XMPP Message stanza - "push" mechanism."""
375 - def __init__(self, to=None, body=None, typ=None, subject=None, attrs={}, frm=None, payload=[], timestamp=None, xmlns=NS_CLIENT, node=None):
376 """ Create message object. You can specify recipient, text of message, type of message 377 any additional attributes, sender of the message, any additional payload (f.e. jabber:x:delay element) and namespace in one go. 378 Alternatively you can pass in the other XML object as the 'node' parameted to replicate it as message. """ 379 Protocol.__init__(self, 'message', to=to, typ=typ, attrs=attrs, frm=frm, payload=payload, timestamp=timestamp, xmlns=xmlns, node=node) 380 if body: self.setBody(body) 381 if subject: self.setSubject(subject)
382 - def getBody(self):
383 """ Returns text of the message. """ 384 return self.getTagData('body')
385 - def getSubject(self):
386 """ Returns subject of the message. """ 387 return self.getTagData('subject')
388 - def getThread(self):
389 """ Returns thread of the message. """ 390 return self.getTagData('thread')
391 - def setBody(self,val):
392 """ Sets the text of the message. """ 393 self.setTagData('body',val)
394 - def setSubject(self,val):
395 """ Sets the subject of the message. """ 396 self.setTagData('subject',val)
397 - def setThread(self,val):
398 """ Sets the thread of the message. """ 399 self.setTagData('thread',val)
400 - def buildReply(self,text=None):
401 """ Builds and returns another message object with specified text. 402 The to, from and thread properties of new message are pre-set as reply to this message. """ 403 m=Message(to=self.getFrom(),frm=self.getTo(),body=text) 404 th=self.getThread() 405 if th: m.setThread(th) 406 return m
407
408 -class Presence(Protocol):
409 """ XMPP Presence object."""
410 - def __init__(self, to=None, typ=None, priority=None, show=None, status=None, attrs={}, frm=None, timestamp=None, payload=[], xmlns=NS_CLIENT, node=None):
411 """ Create presence object. You can specify recipient, type of message, priority, show and status values 412 any additional attributes, sender of the presence, timestamp, any additional payload (f.e. jabber:x:delay element) and namespace in one go. 413 Alternatively you can pass in the other XML object as the 'node' parameted to replicate it as presence. """ 414 Protocol.__init__(self, 'presence', to=to, typ=typ, attrs=attrs, frm=frm, payload=payload, timestamp=timestamp, xmlns=xmlns, node=node) 415 if priority: self.setPriority(priority) 416 if show: self.setShow(show) 417 if status: self.setStatus(status)
418 - def getPriority(self):
419 """ Returns the priority of the message. """ 420 return self.getTagData('priority')
421 - def getShow(self):
422 """ Returns the show value of the message. """ 423 return self.getTagData('show')
424 - def getStatus(self):
425 """ Returns the status string of the message. """ 426 return self.getTagData('status')
427 - def setPriority(self,val):
428 """ Sets the priority of the message. """ 429 self.setTagData('priority',val)
430 - def setShow(self,val):
431 """ Sets the show value of the message. """ 432 self.setTagData('show',val)
433 - def setStatus(self,val):
434 """ Sets the status string of the message. """ 435 self.setTagData('status',val)
436
437 - def _muc_getItemAttr(self,tag,attr):
438 for xtag in self.getTags('x'): 439 for child in xtag.getTags(tag): 440 return child.getAttr(attr)
441 - def _muc_getSubTagDataAttr(self,tag,attr):
442 for xtag in self.getTags('x'): 443 for child in xtag.getTags('item'): 444 for cchild in child.getTags(tag): 445 return cchild.getData(),cchild.getAttr(attr) 446 return None,None
447 - def getRole(self):
448 """Returns the presence role (for groupchat)""" 449 return self._muc_getItemAttr('item','role')
450 - def getAffiliation(self):
451 """Returns the presence affiliation (for groupchat)""" 452 return self._muc_getItemAttr('item','affiliation')
453 - def getNick(self):
454 """Returns the nick value (for nick change in groupchat)""" 455 return self._muc_getItemAttr('item','nick')
456 - def getJid(self):
457 """Returns the presence jid (for groupchat)""" 458 return self._muc_getItemAttr('item','jid')
459 - def getReason(self):
460 """Returns the reason of the presence (for groupchat)""" 461 return self._muc_getSubTagDataAttr('reason','')[0]
462 - def getActor(self):
463 """Returns the reason of the presence (for groupchat)""" 464 return self._muc_getSubTagDataAttr('actor','jid')[1]
465 - def getStatusCode(self):
466 """Returns the status code of the presence (for groupchat)""" 467 return self._muc_getItemAttr('status','code')
468
469 -class Iq(Protocol):
470 """ XMPP Iq object - get/set dialog mechanism. """
471 - def __init__(self, typ=None, queryNS=None, attrs={}, to=None, frm=None, payload=[], xmlns=NS_CLIENT, node=None):
472 """ Create Iq object. You can specify type, query namespace 473 any additional attributes, recipient of the iq, sender of the iq, any additional payload (f.e. jabber:x:data node) and namespace in one go. 474 Alternatively you can pass in the other XML object as the 'node' parameted to replicate it as an iq. """ 475 Protocol.__init__(self, 'iq', to=to, typ=typ, attrs=attrs, frm=frm, xmlns=xmlns, node=node) 476 if payload: self.setQueryPayload(payload) 477 if queryNS: self.setQueryNS(queryNS)
478 - def getQueryNS(self):
479 """ Return the namespace of the 'query' child element.""" 480 tag=self.getTag('query') 481 if tag: return tag.getNamespace()
482 - def getQuerynode(self):
483 """ Return the 'node' attribute value of the 'query' child element.""" 484 return self.getTagAttr('query','node')
485 - def getQueryPayload(self):
486 """ Return the 'query' child element payload.""" 487 tag=self.getTag('query') 488 if tag: return tag.getPayload()
489 - def getQueryChildren(self):
490 """ Return the 'query' child element child nodes.""" 491 tag=self.getTag('query') 492 if tag: return tag.getChildren()
493 - def setQueryNS(self,namespace):
494 """ Set the namespace of the 'query' child element.""" 495 self.setTag('query').setNamespace(namespace)
496 - def setQueryPayload(self,payload):
497 """ Set the 'query' child element payload.""" 498 self.setTag('query').setPayload(payload)
499 - def setQuerynode(self,node):
500 """ Set the 'node' attribute value of the 'query' child element.""" 501 self.setTagAttr('query','node',node)
502 - def buildReply(self,typ):
503 """ Builds and returns another Iq object of specified type. 504 The to, from and query child node of new Iq are pre-set as reply to this Iq. """ 505 iq=Iq(typ,to=self.getFrom(),frm=self.getTo(),attrs={'id':self.getID()}) 506 if self.getTag('query'): iq.setQueryNS(self.getQueryNS()) 507 return iq
508
509 -class ErrorNode(Node):
510 """ XMPP-style error element. 511 In the case of stanza error should be attached to XMPP stanza. 512 In the case of stream-level errors should be used separately. """
513 - def __init__(self,name,code=None,typ=None,text=None):
514 """ Create new error node object. 515 Mandatory parameter: name - name of error condition. 516 Optional parameters: code, typ, text. Used for backwards compartibility with older jabber protocol.""" 517 if ERRORS.has_key(name): 518 cod,type,txt=ERRORS[name] 519 ns=name.split()[0] 520 else: cod,ns,type,txt='500',NS_STANZAS,'cancel','' 521 if typ: type=typ 522 if code: cod=code 523 if text: txt=text 524 Node.__init__(self,'error',{},[Node(name)]) 525 if type: self.setAttr('type',type) 526 if not cod: self.setName('stream:error') 527 if txt: self.addChild(node=Node(ns+' text',{},[txt])) 528 if cod: self.setAttr('code',cod)
529
530 -class Error(Protocol):
531 """ Used to quickly transform received stanza into error reply."""
532 - def __init__(self,node,error,reply=1):
533 """ Create error reply basing on the received 'node' stanza and the 'error' error condition. 534 If the 'node' is not the received stanza but locally created ('to' and 'from' fields needs not swapping) 535 specify the 'reply' argument as false.""" 536 if reply: Protocol.__init__(self,to=node.getFrom(),frm=node.getTo(),node=node) 537 else: Protocol.__init__(self,node=node) 538 self.setError(error) 539 if node.getType()=='error': self.__str__=self.__dupstr__
540 - def __dupstr__(self,dup1=None,dup2=None):
541 """ Dummy function used as preventor of creating error node in reply to error node. 542 I.e. you will not be able to serialise "double" error into string. 543 """ 544 return ''
545
546 -class DataField(Node):
547 """ This class is used in the DataForm class to describe the single data item. 548 If you are working with jabber:x:data (JEP-0004, JEP-0068, JEP-0122) 549 then you will need to work with instances of this class. """
550 - def __init__(self,name=None,value=None,typ=None,required=0,desc=None,options=[],node=None):
551 """ Create new data field of specified name,value and type. 552 Also 'required','desc' and 'options' fields can be set. 553 Alternatively other XML object can be passed in as the 'node' parameted to replicate it as a new datafiled. 554 """ 555 Node.__init__(self,'field',node=node) 556 if name: self.setVar(name) 557 if type(value) in [list,tuple]: self.setValues(value) 558 elif value: self.setValue(value) 559 if typ: self.setType(typ) 560 elif not typ and not node: self.setType('text-single') 561 if required: self.setRequired(required) 562 if desc: self.setDesc(desc) 563 if options: self.setOptions(options)
564 - def setRequired(self,req=1):
565 """ Change the state of the 'required' flag. """ 566 if req: self.setTag('required') 567 else: 568 try: self.delChild('required') 569 except ValueError: return
570 - def isRequired(self):
571 """ Returns in this field a required one. """ 572 return self.getTag('required')
573 - def setDesc(self,desc):
574 """ Set the description of this field. """ 575 self.setTagData('desc',desc)
576 - def getDesc(self):
577 """ Return the description of this field. """ 578 return self.getTagData('desc')
579 - def setValue(self,val):
580 """ Set the value of this field. """ 581 self.setTagData('value',val)
582 - def getValue(self):
583 return self.getTagData('value')
584 - def setValues(self,lst):
585 """ Set the values of this field as values-list. 586 Replaces all previous filed values! If you need to just add a value - use addValue method.""" 587 while self.getTag('value'): self.delChild('value') 588 for val in lst: self.addValue(val)
589 - def addValue(self,val):
590 """ Add one more value to this field. Used in 'get' iq's or such.""" 591 self.addChild('value',{},[val])
592 - def getValues(self):
593 """ Return the list of values associated with this field.""" 594 ret=[] 595 for tag in self.getTags('value'): ret.append(tag.getData()) 596 return ret
597 - def getOptions(self):
598 """ Return label-option pairs list associated with this field.""" 599 ret=[] 600 for tag in self.getTags('option'): ret.append([tag.getAttr('label'),tag.getTagData('value')]) 601 return ret
602 - def setOptions(self,lst):
603 """ Set label-option pairs list associated with this field.""" 604 while self.getTag('option'): self.delChild('option') 605 for opt in lst: self.addOption(opt)
606 - def addOption(self,opt):
607 """ Add one more label-option pair to this field.""" 608 if type(opt) in [str,unicode]: self.addChild('option').setTagData('value',opt) 609 else: self.addChild('option',{'label':opt[0]}).setTagData('value',opt[1])
610 - def getType(self):
611 """ Get type of this field. """ 612 return self.getAttr('type')
613 - def setType(self,val):
614 """ Set type of this field. """ 615 return self.setAttr('type',val)
616 - def getVar(self):
617 """ Get 'var' attribute value of this field. """ 618 return self.getAttr('var')
619 - def setVar(self,val):
620 """ Set 'var' attribute value of this field. """ 621 return self.setAttr('var',val)
622
623 -class DataForm(Node):
624 """ DataForm class. Used for manipulating dataforms in XMPP. 625 Relevant JEPs: 0004, 0068, 0122. 626 Can be used in disco, pub-sub and many other applications."""
627 - def __init__(self, typ=None, data=[], title=None, node=None):
628 """ 629 Create new dataform of type 'typ'. 'data' is the list of DataField 630 instances that this dataform contains, 'title' - the title string. 631 You can specify the 'node' argument as the other node to be used as 632 base for constructing this dataform. 633 634 title and instructions is optional and SHOULD NOT contain newlines. 635 Several instructions MAY be present. 636 'typ' can be one of ('form' | 'submit' | 'cancel' | 'result' ) 637 'typ' of reply iq can be ( 'result' | 'set' | 'set' | 'result' ) respectively. 638 'cancel' form can not contain any fields. All other forms contains AT LEAST one field. 639 'title' MAY be included in forms of type "form" and "result" 640 """ 641 Node.__init__(self,'x',node=node) 642 if node: 643 newkids=[] 644 for n in self.getChildren(): 645 if n.getName()=='field': newkids.append(DataField(node=n)) 646 else: newkids.append(n) 647 self.kids=newkids 648 if typ: self.setType(typ) 649 self.setNamespace(NS_DATA) 650 if title: self.setTitle(title) 651 if type(data)==type({}): 652 newdata=[] 653 for name in data.keys(): newdata.append(DataField(name,data[name])) 654 data=newdata 655 for child in data: 656 if type(child) in [type(''),type(u'')]: self.addInstructions(child) 657 elif child.__class__.__name__=='DataField': self.kids.append(child) 658 else: self.kids.append(DataField(node=child))
659 - def getType(self):
660 """ Return the type of dataform. """ 661 return self.getAttr('type')
662 - def setType(self,typ):
663 """ Set the type of dataform. """ 664 self.setAttr('type',typ)
665 - def getTitle(self):
666 """ Return the title of dataform. """ 667 return self.getTagData('title')
668 - def setTitle(self,text):
669 """ Set the title of dataform. """ 670 self.setTagData('title',text)
671 - def getInstructions(self):
672 """ Return the instructions of dataform. """ 673 return self.getTagData('instructions')
674 - def setInstructions(self,text):
675 """ Set the instructions of dataform. """ 676 self.setTagData('instructions',text)
677 - def addInstructions(self,text):
678 """ Add one more instruction to the dataform. """ 679 self.addChild('instructions',{},[text])
680 - def getField(self,name):
681 """ Return the datafield object with name 'name' (if exists). """ 682 return self.getTag('field',attrs={'var':name})
683 - def setField(self,name):
684 """ Create if nessessary or get the existing datafield object with name 'name' and return it. """ 685 f=self.getField(name) 686 if f: return f 687 return self.addChild(node=DataField(name))
688 - def asDict(self):
689 """ Represent dataform as simple dictionary mapping of datafield names to their values.""" 690 ret={} 691 for field in self.getTags('field'): 692 name=field.getAttr('var') 693 typ=field.getType() 694 if isinstance(typ,(str,unicode)) and typ[-6:]=='-multi': 695 val=[] 696 for i in field.getTags('value'): val.append(i.getData()) 697 else: val=field.getTagData('value') 698 ret[name]=val 699 if self.getTag('instructions'): ret['instructions']=self.getInstructions() 700 return ret
701 - def __getitem__(self,name):
702 """ Simple dictionary interface for getting datafields values by their names.""" 703 item=self.getField(name) 704 if item: return item.getValue() 705 raise IndexError('No such field')
706 - def __setitem__(self,name,val):
707 """ Simple dictionary interface for setting datafields values by their names.""" 708 return self.setField(name).setValue(val)
709