/**
 * ====================================================================
 * recordermodule.cpp
 *
 * Python API to recording and playing, based on the sound example
 * app in Series 60 SDK.
 *
 * Implements currently following Python type:
 * 
 * Player
 *
 *    play(times, time_between, callback)
 *      times, how many times the sound file is played, time_between
 *      in microseconds prior playing again. callback gets called with
 *      previous state, current state and error code (0 = no error).
 *  
 *    stop()
 *    
 *    record()
 *      only ".wav"-files can be recorded.
 *    
 *    open_file(filename)
 *      creates the file if it does not exist already.
 *    
 *    close_file()
 *    
 *    int state()
 *      the possible states are in the module dictionary.
 *
 *    bind(callable)
 *      callable called with (previousState, currentState, errorCode) when
 *      state is changed.
 *    
 *    int max_volume()
 *      the maximum volume supported by the device.
 *
 *    set_volume(volume)
 *      set the volume (integer).
 *
 *    int current_volume()
 *      get the current volume set.
 *
 *    int duration()
 *      the duration of the file opened. 
 *
 *    set_position(int)
 *      set the position in microseconds, affects when play() is called 
 *      next time.
 *
 *    int current_position()
 *      get the current position in microseconds.
 *
 * Calling record() cannot happen after calling play(), open_file() must
 * preceed record().
 *
 * Playing file and not stopping the playing prior exiting the Python script
 * will leave the sound playing on, stop() needs to be called explicitly.
 *
 * Recording always appends to the end of the opened file. You must delete 
 * the file explicitly if you want to start from the beginning.
 *
 * TODO add here also phone uplink recording and/or playing, see:
 *       iMdaAudioRecorderUtility->
 *       SetAudioDeviceMode( CMdaAudioRecorderUtility::ETelephonyNonMixed);
 *      and "Developer Library