| blob | 224a594eebdf4a2530d46ab544c9dc489e256ab6 |
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.
15 # $Id: protocol.py,v 1.58 2007/05/13 17:55:46 normanr Exp $
17 """
18 Protocol module contains tools that is needed for processing of
19 xmpp-related data structures.
20 """
23 import time
135 bad-format -- -- -- The entity has sent XML that cannot be processed.
136 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.
137 conflict -- -- -- The server is closing the active stream for this entity because a new stream has been initiated that conflicts with the existing stream.
138 connection-timeout -- -- -- The entity has not generated any traffic over the stream for some period of time.
139 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.
140 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.
141 improper-addressing -- -- -- A stanza sent between two servers lacks a 'to' or 'from' attribute (or the attribute has no value).
142 internal-server-error -- -- -- The server has experienced a misconfiguration or an otherwise-undefined internal error that prevents it from servicing the stream.
143 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.
144 invalid-id -- -- -- The stream ID or dialback ID is invalid or does not match an ID previously provided.
145 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".
146 invalid-xml -- -- -- The entity has sent invalid XML over the stream to a server that performs validation.
147 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.
148 policy-violation -- -- -- The entity has violated some local service policy.
149 remote-connection-failed -- -- -- The server is unable to properly connect to a remote resource that is required for authentication or authorization.
150 resource-constraint -- -- -- The server lacks the system resources necessary to service the stream.
151 restricted-xml -- -- -- The entity has attempted to send restricted XML features such as a comment, processing instruction, DTD, entity reference, or unescaped character.
152 see-other-host -- -- -- The server will not provide service to the initiating entity but is redirecting traffic to another host.
153 system-shutdown -- -- -- The server is being shut down and all active streams are being closed.
154 undefined-condition -- -- -- The error condition is not one of those defined by the other conditions in this list.
155 unsupported-encoding -- -- -- The initiating entity has encoded the stream in an encoding that is not supported by the server.
156 unsupported-stanza-type -- -- -- The initiating entity has sent a first-level child of the stream that is not supported by the server.
157 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.
158 xml-not-well-formed -- -- -- The initiating entity has sent XML that is not well-formed."""
160 bad-request -- 400 -- modify -- The sender has sent XML that is malformed or that cannot be processed.
161 conflict -- 409 -- cancel -- Access cannot be granted because an existing resource or session exists with the same name or address.
162 feature-not-implemented -- 501 -- cancel -- The feature requested is not implemented by the recipient or server and therefore cannot be processed.
163 forbidden -- 403 -- auth -- The requesting entity does not possess the required permissions to perform the action.
164 gone -- 302 -- modify -- The recipient or server can no longer be contacted at this address.
165 internal-server-error -- 500 -- wait -- The server could not process the stanza because of a misconfiguration or an otherwise-undefined internal server error.
166 item-not-found -- 404 -- cancel -- The addressed JID or item requested cannot be found.
167 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.
168 not-acceptable -- 406 -- cancel -- 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.
169 not-allowed -- 405 -- cancel -- The recipient or server does not allow any entity to perform the action.
170 not-authorized -- 401 -- auth -- The sender must provide proper credentials before being allowed to perform the action, or has provided improper credentials.
171 payment-required -- 402 -- auth -- The requesting entity is not authorized to access the requested service because payment is required.
172 recipient-unavailable -- 404 -- wait -- The intended recipient is temporarily unavailable.
173 redirect -- 302 -- modify -- The recipient or server is redirecting requests for this information to another entity.
174 registration-required -- 407 -- auth -- The requesting entity is not authorized to access the requested service because registration is required.
175 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.
176 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.
177 resource-constraint -- 500 -- wait -- The server or recipient lacks the system resources necessary to service the request.
178 service-unavailable -- 503 -- cancel -- The server or recipient does not currently provide the requested service.
179 subscription-required -- 407 -- auth -- The requesting entity is not authorized to access the requested service because a subscription is required.
180 undefined-condition -- 500 -- --
181 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)."""
183 aborted -- -- -- The receiving entity acknowledges an <abort/> element sent by the initiating entity; sent in reply to the <abort/> element.
184 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.
185 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.
186 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.
187 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.
188 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.
189 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."""
204 """ Returns true if the node is a positive reply. """
207 """ Returns true if the node is a negative reply. """
211 """ Exception that should be raised by handler when the handling should be stopped. """
213 """ Base exception class for stream errors."""
265 """ JID object. JID can be built from string, modified, compared, serialised into string. """
267 """ Constructor. JID can be specified as string (jid argument) or as separate parts.
268 Examples:
269 JID('node@domain/resource')
270 JID(node='node',domain='domain.org')
271 """
273 elif type(jid)==type(self): self.node,self.domain,self.resource=jid.node,jid.domain,jid.resource
281 """ Return the node part of the JID """
284 """ Set the node part of the JID to new value. Specify None to remove the node part."""
287 """ Return the domain part of the JID """
290 """ Set the domain part of the JID to new value."""
293 """ Return the resource part of the JID """
296 """ Set the resource part of the JID to new value. Specify None to remove the resource part."""
299 """ Return the bare representation of JID. I.e. string value w/o resource. """
302 """ Compare the JID to another instance or to string for equality. """
307 """ Compare the JID to another instance or to string for non-equality. """
310 """ Compare the node and domain parts of the JID's for equality. """
313 """ Serialise JID into string. """
317 return jid
319 """ Produce hash of the JID, Allows to use JID objects as keys of the dictionary. """
323 """ A "stanza" object class. Contains methods that are common for presences, iqs and messages. """
324 def __init__(self, name=None, to=None, typ=None, frm=None, attrs={}, payload=[], timestamp=None, xmlns=None, node=None):
325 """ Constructor, name is the name of the stanza i.e. 'message' or 'presence' or 'iq'.
326 to is the value of 'to' attribure, 'typ' - 'type' attribute
327 frn - from attribure, attrs - other attributes mapping, payload - same meaning as for simplexml payload definition
328 timestamp - the time value that needs to be stamped over stanza
329 xmlns - namespace of top stanza node
330 node - parsed or unparsed stana to be taken as prototype.
331 """
340 if node and type(self)==type(node) and self.__class__==node.__class__ and self.attrs.has_key('id'): del self.attrs['id']
344 if not self.getTimestamp() or x.getAttr('stamp')<self.getTimestamp(): self.setTimestamp(x.getAttr('stamp'))
346 if timestamp is not None: self.setTimestamp(timestamp) # To auto-timestamp stanza just pass timestamp=''
348 """ Return value of the 'to' attribute. """
352 """ Return value of the 'from' attribute. """
356 """ Return the timestamp in the 'yyyymmddThhmmss' format. """
359 """ Return the value of the 'id' attribute. """
362 """ Set the value of the 'to' attribute. """
365 """ Return the value of the 'type' attribute. """
368 """ Set the value of the 'from' attribute. """
371 """ Set the value of the 'type' attribute. """
374 """ Set the value of the 'id' attribute. """
377 """ Return the error-condition (if present) or the textual description of the error (otherwise). """
384 """ Return the error code. Obsolette. """
387 """ Set the error code. Obsolette. Use error-conditions instead. """
395 """Set the timestamp. timestamp should be the yyyymmddThhmmss string."""
400 """ Return the list of namespaces to which belongs the direct childs of element"""
401 props=[]
405 return props
407 """ Set the item 'item' to the value 'val'."""
412 """ XMPP Message stanza - "push" mechanism."""
413 def __init__(self, to=None, body=None, typ=None, subject=None, attrs={}, frm=None, payload=[], timestamp=None, xmlns=NS_CLIENT, node=None):
414 """ Create message object. You can specify recipient, text of message, type of message
415 any additional attributes, sender of the message, any additional payload (f.e. jabber:x:delay element) and namespace in one go.
416 Alternatively you can pass in the other XML object as the 'node' parameted to replicate it as message. """
417 Protocol.__init__(self, 'message', to=to, typ=typ, attrs=attrs, frm=frm, payload=payload, timestamp=timestamp, xmlns=xmlns, node=node)
421 """ Returns text of the message. """
424 """ Returns subject of the message. """
427 """ Returns thread of the message. """
430 """ Sets the text of the message. """
433 """ Sets the subject of the message. """
436 """ Sets the thread of the message. """
439 """ Builds and returns another message object with specified text.
440 The to, from and thread properties of new message are pre-set as reply to this message. """
444 return m
447 """ XMPP Presence object."""
448 def __init__(self, to=None, typ=None, priority=None, show=None, status=None, attrs={}, frm=None, timestamp=None, payload=[], xmlns=NS_CLIENT, node=None):
449 """ Create presence object. You can specify recipient, type of message, priority, show and status values
450 any additional attributes, sender of the presence, timestamp, any additional payload (f.e. jabber:x:delay element) and namespace in one go.
451 Alternatively you can pass in the other XML object as the 'node' parameted to replicate it as presence. """
452 Protocol.__init__(self, 'presence', to=to, typ=typ, attrs=attrs, frm=frm, payload=payload, timestamp=timestamp, xmlns=xmlns, node=node)
457 """ Returns the priority of the message. """
460 """ Returns the show value of the message. """
463 """ Returns the status string of the message. """
466 """ Sets the priority of the message. """
469 """ Sets the show value of the message. """
472 """ Sets the status string of the message. """
486 """Returns the presence role (for groupchat)"""
489 """Returns the presence affiliation (for groupchat)"""
492 """Returns the nick value (for nick change in groupchat)"""
495 """Returns the presence jid (for groupchat)"""
498 """Returns the reason of the presence (for groupchat)"""
501 """Returns the reason of the presence (for groupchat)"""
504 """Returns the status code of the presence (for groupchat)"""
508 """ XMPP Iq object - get/set dialog mechanism. """
509 def __init__(self, typ=None, queryNS=None, attrs={}, to=None, frm=None, payload=[], xmlns=NS_CLIENT, node=None):
510 """ Create Iq object. You can specify type, query namespace
511 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.
512 Alternatively you can pass in the other XML object as the 'node' parameted to replicate it as an iq. """
517 """ Return the namespace of the 'query' child element."""
521 """ Return the 'node' attribute value of the 'query' child element."""
524 """ Return the 'query' child element payload."""
528 """ Return the 'query' child element child nodes."""
532 """ Set the namespace of the 'query' child element."""
535 """ Set the 'query' child element payload."""
538 """ Set the 'node' attribute value of the 'query' child element."""
541 """ Builds and returns another Iq object of specified type.
542 The to, from and query child node of new Iq are pre-set as reply to this Iq. """
545 return iq
548 """ XMPP-style error element.
549 In the case of stanza error should be attached to XMPP stanza.
550 In the case of stream-level errors should be used separately. """
552 """ Create new error node object.
553 Mandatory parameter: name - name of error condition.
554 Optional parameters: code, typ, text. Used for backwards compartibility with older jabber protocol."""
569 """ Used to quickly transform received stanza into error reply."""
571 """ Create error reply basing on the received 'node' stanza and the 'error' error condition.
572 If the 'node' is not the received stanza but locally created ('to' and 'from' fields needs not swapping)
573 specify the 'reply' argument as false."""
579 """ Dummy function used as preventor of creating error node in reply to error node.
580 I.e. you will not be able to serialise "double" error into string.
581 """
585 """ This class is used in the DataForm class to describe the single data item.
586 If you are working with jabber:x:data (XEP-0004, XEP-0068, XEP-0122)
587 then you will need to work with instances of this class. """
588 def __init__(self,name=None,value=None,typ=None,required=0,label=None,desc=None,options=[],node=None):
589 """ Create new data field of specified name,value and type.
590 Also 'required','desc' and 'options' fields can be set.
591 Alternatively other XML object can be passed in as the 'node' parameted to replicate it as a new datafiled.
592 """
604 """ Change the state of the 'required' flag. """
610 """ Returns in this field a required one. """
613 """ Set the label of this field. """
616 """ Return the label of this field. """
619 """ Set the description of this field. """
622 """ Return the description of this field. """
625 """ Set the value of this field. """
630 """ Set the values of this field as values-list.
631 Replaces all previous filed values! If you need to just add a value - use addValue method."""
635 """ Add one more value to this field. Used in 'get' iq's or such."""
638 """ Return the list of values associated with this field."""
639 ret=[]
641 return ret
643 """ Return label-option pairs list associated with this field."""
644 ret=[]
646 return ret
648 """ Set label-option pairs list associated with this field."""
652 """ Add one more label-option pair to this field."""
656 """ Get type of this field. """
659 """ Set type of this field. """
662 """ Get 'var' attribute value of this field. """
665 """ Set 'var' attribute value of this field. """
669 """ DataForm class. Used for manipulating dataforms in XMPP.
670 Relevant XEPs: 0004, 0068, 0122.
671 Can be used in disco, pub-sub and many other applications."""
673 """
674 Create new dataform of type 'typ'. 'data' is the list of DataField
675 instances that this dataform contains, 'title' - the title string.
676 You can specify the 'node' argument as the other node to be used as
677 base for constructing this dataform.
679 title and instructions is optional and SHOULD NOT contain newlines.
680 Several instructions MAY be present.
681 'typ' can be one of ('form' | 'submit' | 'cancel' | 'result' )
682 'typ' of reply iq can be ( 'result' | 'set' | 'set' | 'result' ) respectively.
683 'cancel' form can not contain any fields. All other forms contains AT LEAST one field.
684 'title' MAY be included in forms of type "form" and "result"
685 """
688 newkids=[]
697 newdata=[]
699 data=newdata
705 """ Return the type of dataform. """
708 """ Set the type of dataform. """
711 """ Return the title of dataform. """
714 """ Set the title of dataform. """
717 """ Return the instructions of dataform. """
720 """ Set the instructions of dataform. """
723 """ Add one more instruction to the dataform. """
726 """ Return the datafield object with name 'name' (if exists). """
729 """ Create if nessessary or get the existing datafield object with name 'name' and return it. """
734 """ Represent dataform as simple dictionary mapping of datafield names to their values."""
735 ret={}
740 val=[]
745 return ret
747 """ Simple dictionary interface for getting datafields values by their names."""
752 """ Simple dictionary interface for setting datafields values by their names."""