This file contains information on some refactorings needed in shtoom.
These are sections of the code that *need* a solid smack to the head
with the big refactoring stick.

Note that these tasks probably make the situation seem gloomier than
it actually is - the code as it is works, but could be done better. 
Most of them are also going to be necessary to move forward in some
areas that are currently blocked.

[xxx work in progress - please give me comments on details if 
you're interested in looking at any of these]

Call
----

The Big One. The Call object is a creeping disaster. More of it's 
logic (the handling of SIP messages) needs to be moved out into the 
Dialog class, and the state machine logic needs to be made explicit. 
This is needed to sanely handle retransmits and the like. The state 
should also become an object, and it can be then responsible for 
handling the retransmits.

Credentials
-----------

There should be a cleaner interface for the handling of credentials. 
It's a bit of a mess right now.

Accept Call? Deferred
---------------------

The UI layer is passed a deferred to use to signal whether an 
incoming call should be accepted or rejected. The UI/app then
triggers .callback() for yes, .errback() for no. This is bogus.
The UI/app should create the deferred itself, and return it. It
should call the callback with True/False for yes/no, and reserve
the .errback for, well, errors.

Here's the current plan: 

  the SIP layer calls the application for the acceptCall. The application
  returns a deferred. 
  the application calls the UI for an incoming call. the UI returns a
  deferred, which returns (something. need to indicate yes, no, no answer,
  ...)
  when the UI deferred is triggered, the application does all the other
  bits (STUN, rtp, &c), then triggers the deferred that it created.


Import testing
--------------

There's a bunch of try: import foo except: foo = None stanzas buried 
in the code. I'd like to move all of that out to a seperate module 
that does *all* of the import tests in one place.

There's now a module shtoom.avail for encapsulating all these icky 
bits. Right now it only has audio codecs in it.

Going forward, it should probably do something like:

try: 
    import foobarbaz
except ImportError:
    # some sort of debugging?
    foobarbaz = None
    _removeModule('foobarbaz')
except: 
    log.err('got a funny exception ...')
    foobarbaz = None
    _removeModule('foobarbaz')

Audio testing and codec testing are implemented in shtoom.avail.audio
and shtoom.avail.codecs, respectively. shtoom.avail.ui is a stub, so
far.


Doug: Leg Refactoring - COMPLETED
---------------------------------

A bunch of the logic in voiceapp needs to move out to the legs. 
This is needed to allow multiple legs in a call (e.g. inbound and
outbound legs). This also gives me an opportunity to refactor and
unit test a lot of the code. Excellent!

More detail: Most everything in doug/voiceapp.py more properly
belongs to the Leg class - mediaPlay/Record &c are leg-specific.

This has been done, as of r809. Leg bridging is implemented, as well.

Audio Jihad - COMPLETED
-----------------------

The audio devices are inside out - they are an object that wraps
a MediaLayer around themselves. This is nuts.

This has been fixed.

SDP/RTP/Payload Types refactoring - COMPLETED
---------------------------------------------

At the moment, the responsibility for the handling of RTP payload
types is smeared over a few pieces of code. This means, for instance,
that we can't handle dynamically allocated payload types (such as, 
for instance, speex). It also makes for nasty code. Ideally, the
code would pass an object to the RTP layer that has both the data
*and* the payload type, and similarly, receive an object from the RTP
layer with both the data and the payload type. This then gets passed
to the AudioLayer object. 

The bits that would need touching are shtoom.app.{doug,phone}, 
shtoom.rtp, shtoom.audio.converters. shtoo.app.base can be ignored,
as it's going away soon.

 the RTP layer is then in charge of all things RTP-ish.
 So the changes are: 
 1. getSDP() and selectFormat() hand off SDP negotiations to the RTPProtocol.
 2. Call object passes the SDP in an ACK to RTP via the app object so it can
 build a PT dictionary
 3. MediaLayer (previously known as MultipleConverter) gets and receives
 RTPPacket objects, that encapsulate an RTP packet, including payload type,
 timestamp and data.
 4. RTPProtocol gets an RTPParser object, that converts RTPPackets to/from
 the wire format.
 5. Optional codec support moves to the new shtoom.avail module (see the
 ``Import testing'' section, below.


This refactoring was completed the branch rtp-sdp-refactor, branched
at r677, and merged at r717.