Author: liori Date: 2007-08-06 17:53:01 +0200 (Mon, 06 Aug 2007) New Revision: 8456
Added: branches/jingle/src/common/jingle.py Log: Jingle: Initial support for jingle and jingle-audio. Code isn't linked with the connection code yet. Inside: * A basic form of jingle framework; the goal is to make code reusable for other jingle uses. * Codec "negotiation" for jingle-audio.
Added: branches/jingle/src/common/jingle.py =================================================================== --- branches/jingle/src/common/jingle.py (rev 0) +++ branches/jingle/src/common/jingle.py 2007-08-06 15:53:01 UTC (rev 8456) @@ -0,0 +1,345 @@ +## +## Copyright (C) 2006 Gajim Team +## +## This program is free software; you can redistribute it and/or modify +## it under the terms of the GNU General Public License as published +## by the Free Software Foundation; version 2 only. +## +## This program is distributed in the hope that it will be useful, +## but WITHOUT ANY WARRANTY; without even the implied warranty of +## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +## GNU General Public License for more details. +## +''' Handles the jingle signalling protocol. ''' + +import xmpp + +class JingleStates(object): + ''' States in which jingle session may exist. ''' + ended=0 + pending=1 + active=2 + +class WrongState(exception): pass +class NoCommonCodec(exception): pass + +class JingleSession(object): + ''' This represents one jingle session. ''' + def __init__(self, con, weinitiate, jid): + ''' con -- connection object, + weinitiate -- boolean, are we the initiator? + jid - jid of the other entity''' + self.contents={} # negotiated contents + self.connection=con # connection to use + # our full jid + self.ourjid=gajim.get_full_jid_from_account(self.connection.name) + self.jid=jid # jid we connect to + # jid we use as the initiator + self.initiator=weinitiate and self.ourjid or self.jid + # jid we use as the responder + self.responder=weinitiate and self.jid or self.ourjid + # are we an initiator? + self.weinitiate=weinitiate + # what state is session in? (one from JingleStates) + self.state=JingleStates.ended + self.sid=con.getAnID() # sessionid + + # callbacks to call on proper contents + # use .prepend() to add new callbacks + self.callbacks=dict((key, [self.__defaultCB]) for key in + ('content-accept', 'content-add', 'content-modify', + 'content-remove', 'session-accept', 'session-info', + 'session-initiate', 'session-terminate', + 'transport-info')) + self.callbacks['iq-result']=[] + self.callbacks['iq-error']=[] + + ''' Middle-level functions to manage contents. Handle local content + cache and send change notifications. ''' + def addContent(self, name, description, transport, profile=None): + ''' Add new content to session. If the session is active, + this will send proper stanza to update session. + The protocol prohibits changing that when pending.''' + if self.state==JingleStates.pending: + raise WrongState + + content={'creator': 'initiator', + 'name': name, + 'description': description, + 'transport': transport} + if profile is not None: + content['profile']=profile + self.contents[('initiator', name)]=content + + if self.state==JingleStates.active: + pass # TODO: send proper stanza, shouldn't be needed now + + ''' Middle-level function to do stanza exchange. ''' + def startSession(self): + ''' Start session. ''' + self.__sessionInitiate(self) + + def sendSessionInfo(self): pass + def sendTransportInfo(self): pass + + ''' Callbacks. ''' + def stanzaCB(self, stanza): + ''' A callback for ConnectionJingle. It gets stanza, then + tries to send it to all internally registered callbacks. + First one to raise xmpp.NodeProcessed breaks function.''' + jingle = stanza.getTag('jingle') + error = stanza.getTag('error') + if error: + # it's an iq-error stanza + callables = 'iq-error' + else if jingle: + # it's a jingle action + action = jingle.getAttr('action') + callables = action + else: + # it's an iq-result (ack) stanza + callables = 'iq-result' + + callables = self.callbacks[callables] + + try: + for callable in callables: + callable(stanza=stanza, jingle=jingle, error=error) + except xmpp.NodeProcessed: + pass + + def __defaultCB(self, stanza, jingle, error): + ''' Default callback for action stanzas -- simple ack + and stop processing. ''' + response = stanza.buildReply('result') + self.connection.send(response) + raise xmpp.NodeProcessed + + ''' Methods that make/send proper pieces of XML. They check if the session + is in appropriate state. ''' + def makeJingle(self, action): + stanza = xmpp.Iq(typ='set', to=xmpp.JID(self.jid)) + jingle = stanza.addChild('jingle', attrs= + 'xmlns': 'http://www.xmpp.org/extensions/xep-0166.html#ns', + 'action': action, + 'initiator': self.initiator, + 'responder': self.responder, + 'sid': self.sid}) + return stanza, jingle + + def appendContent(self, jingle, content, full=True): + ''' Append <content/> element to <jingle/> element, + with (full=True) or without (full=False) <content/> + children. ''' + c=jingle.addChild('content', attrs={ + 'creator': content['creator'], + 'name': content['name']}) + if 'profile' in content: + c['profile']=content['profile'] + if full: + c.addChild(node=content['description']) + c.addChild(node=content['transport']) + return c + + def appendContents(self, jingle, full=True): + ''' Append all <content/> elements to <jingle/>.''' + # TODO: integrate with __appendContent? + # TODO: parameters 'name', 'content'? + for content in self.contents.values(): + self.__appendContent(jingle, content, full=full) + + def __sessionInitiate(self): + assert self.state==JingleStates.ended + + def __sessionAccept(self): + assert self.state==JingleStates.pending + stanza, jingle = self.__jingle('session-accept') + self.__appendContents(jingle, False) + self.connection.send(stanza) + self.state=JingleStates.active + + def __sessionInfo(self, payload=None): + assert self.state!=JingleStates.ended + stanza, jingle = self.__jingle('session-info') + if payload: + jingle.addChild(node=payload) + self.connection.send(stanza) + + def __sessionTerminate(self): + assert self.state!=JingleStates.ended + stanza, jingle = self.__jingle('session-terminate') + self.connection.send(stanza) + + def __contentAdd(self): + assert self.state==JingleStates.active + + def __contentAccept(self): + assert self.state!=JingleStates.ended + + def __contentModify(self): + assert self.state!=JingleStates.ended + + def __contentRemove(self): + assert self.state!=JingleStates.ended + + def __transportInfo(self): + assert self.state!=JingleStates.ended + + '''Callbacks''' + def sessionInitiateCB(self, stanza): + ''' We got a jingle session request from other entity, + therefore we are the receiver... Unpack the data. ''' + jingle = stanza.getTag('jingle') + self.initiator = jingle['initiator'] + self.responder = self.ourjid + self.jid = self.initiator + self.state = JingleStates.pending + self.sid = jingle['sid'] + for element in jingle.iterTags('content'): + content={'creator': 'initiator', + 'name': element['name'] + 'description': element.getTag('description'), + 'transport': element.getTag('transport')} + if element.has_attr('profile'): + content['profile']=element['profile'] + self.contents[('initiator', content['name'])]=content + + def sessionTerminateCB(self, stanza): pass + +class JingleAudioSession(object): + class Codec(object): + ''' This class keeps description of a single codec. ''' + def __init__(self, name, id=None, **params): + ''' Create new codec description. ''' + self.name = name + self.id = id + self.attrs = {'name': self.name, 'id': self.id, 'channels': 1} + for key in ('channels', 'clockrate', 'maxptime', 'ptime'): + if key in params: + self.attrs[key]=params[key] + del params[key] + self.params = params + + def __eq__(a, b): + ''' Compare two codec descriptions. ''' + # TODO: check out what should be tested... + if a.name!=b.name: return False + # ... + return True + + def toXML(self): + return xmpp.Node('payload', + attrs=self.attrs, + payload=(xmpp.Node('parameter', {'name': k, 'value': v}) for k,v in self.params)) + + def __init__(self, con, weinitiate, jid): + JingleSession.__init__(self, con, weinitiate, jid) + if weinitiate: + pass #add voice content + self.callbacks['session-initiate'].prepend( + + self.initiator_codecs=[] + self.responder_codecs=[] + + ''' "Negotiation" of codecs... simply presenting what *we* can do, nothing more... ''' + def getOurCodecs(self, other=None): + ''' Get a list of codecs we support. Try to get them in the same + order as the codecs of our peer. If other!=None, raise + a NoCommonCodec error if no codecs both sides support (None means + we are initiating the connection and we don't know the other + peer's codecs.) ''' + # for now we "understand" only one codec -- speex with clockrate 16000 + # so we have an easy job to do... (codecs sorted in order of preference) + supported_codecs=[ + Codec('speex', clockrate='16000'), + ] + + other_l = other if other is not None else [] + our_l = supported_codecs[:] + out = [] + ids = range(128) + for codec in other: + if codec in our_l: + out.append(codec) + our_l.remove(codec) + try: ids.remove(codec.id) + except ValueError: pass # when id is not a dynamic one + + if other is not None and len(out)==0: + raise NoCommonCodec + + for codec in our_l: + if not codec.id or codec.id not in ids: + codec.id = ids.pop() + out.append(codec) + + return out + + ''' Methods for making proper pieces of XML. ''' + def __codecsList(self, codecs): + ''' Prepares a description element with codecs given as a parameter. ''' + return xmpp.Node('description', + xmlns=xmpp.NS_JINGLE_AUDIO, + payload=(codec.toXML() for codec in codecs)) + +class JingleICEUDPSession(object): + def __init__(self, con, weinitiate, jid): + pass + +class JingleVoiP(JingleSession): + ''' Jingle VoiP sessions consist of audio content transported + over an ICE UDP protocol. ''' + def __init__(*data): + JingleAudioSession.__init__(*data) + JingleICEUDPSession.__init__(*data) + +class ConnectionJingle(object): + ''' This object depends on that it is a part of Connection class. ''' + def __init__(self): + # dictionary: (jid, sessionid) => JingleSession object + self.__sessions = {} + + # dictionary: (jid, iq stanza id) => JingleSession object, + # one time callbacks + self.__iq_responses = {} + + def addJingle(self, jingle): + ''' Add a jingle session to a jingle stanza dispatcher + jingle - a JingleSession object. + ''' + self.__sessions[(jingle.jid, jingle.sid)]=jingle + + def deleteJingle(self, jingle): + ''' Remove a jingle session from a jingle stanza dispatcher ''' + del self.__session[(jingle.jid, jingle.sid)] + + def _jingleCB(self, con, stanza): + ''' The jingle stanza dispatcher. + Route jingle stanza to proper JingleSession object, + or create one if it is a new session. + TODO: Also check if the stanza isn't an error stanza, if so + route it adequatelly.''' + + # get data + jid = stanza.getFrom() + id = stanza.getID() + + if (jid, id) in self.__iq_responses.keys(): + self.__iq_responses[(jid, id)].stanzaCB(stanza) + del self.__iq_responses[(jid, id)] + raise xmpp.NodeProcessed + + jingle = stanza.getTag('jingle') + sid = jingle.getAttr('sid') + + # do we need to create a new jingle object + if (jid, sid) not in self.__sessions: + # we should check its type here... + newjingle = JingleAudioSession(con=self, weinitiate=False, jid=jid) + self.addJingle(newjingle) + + # we already have such session in dispatcher... + return self.__sessions[(jid, sid)].stanzaCB(stanza) + + def addJingleIqCallback(jid, id, jingle): + self.__iq_responses[(jid, id)]=jingle