am ca57d1cc: Audio Effects: added methods to effects java classes to store and load current effect settings in a single call.

Merge commit 'ca57d1cc89d65dfbd59c749c5736574cd08c7bd3' into gingerbread-plus-aosp

* commit 'ca57d1cc89d65dfbd59c749c5736574cd08c7bd3':
  Audio Effects: added methods to effects java classes to store and load current effect settings in

5 files changed, 549 insertions, 14 deletions

diff --git a/media/java/android/media/BassBoost.java b/media/java/android/media/BassBoost.java
index ef4ce05..75c2c88 100644
--- a/media/java/android/media/BassBoost.java
+++ b/media/java/android/media/BassBoost.java
@@ -19,17 +19,19 @@ package android.media;
 import android.app.Activity;
 import android.content.Context;
 import android.content.Intent;
+import android.media.AudioEffect;
 import android.os.Bundle;
 import android.util.Log;
+
 import java.nio.ByteOrder;
 import java.nio.ByteBuffer;
 import java.nio.CharBuffer;
+import java.util.StringTokenizer;
 
-import android.media.AudioEffect;
 
 /**
  * Bass boost is an audio effect to boost or amplify low frequencies of the sound. It is comparable
- * to an simple equalizer but limited to one band amplification in the low frequency range.
+ * to a simple equalizer but limited to one band amplification in the low frequency range.
  * <p>An application creates a BassBoost object to instantiate and control a bass boost engine
  * in the audio framework.
  * <p>The methods, parameter types and units exposed by the BassBoost implementation are directly
@@ -210,4 +212,82 @@ public class BassBoost extends AudioEffect {
             }
         }
     }
+
+    /**
+     * The Settings class regroups all bass boost parameters. It is used in
+     * conjuntion with getProperties() and setProperties() methods to backup and restore
+     * all parameters in a single call.
+     */
+    public static class Settings {
+        public short strength;
+
+        public Settings() {
+        }
+
+        /**
+         * Settings class constructor from a key=value; pairs formatted string. The string is
+         * typically returned by Settings.toString() method.
+         * @throws IllegalArgumentException if the string is not correctly formatted.
+         */
+        public Settings(String settings) {
+            StringTokenizer st = new StringTokenizer(settings, "=;");
+            int tokens = st.countTokens();
+            if (st.countTokens() != 3) {
+                throw new IllegalArgumentException("settings: " + settings);
+            }
+            String key = st.nextToken();
+            if (!key.equals("BassBoost")) {
+                throw new IllegalArgumentException(
+                        "invalid settings for BassBoost: " + key);
+            }
+            try {
+                key = st.nextToken();
+                if (!key.equals("strength")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                strength = Short.parseShort(st.nextToken());
+             } catch (NumberFormatException nfe) {
+                throw new IllegalArgumentException("invalid value for key: " + key);
+            }
+        }
+
+        @Override
+        public String toString() {
+            String str = new String (
+                    "BassBoost"+
+                    ";strength="+Short.toString(strength)
+                    );
+            return str;
+        }
+    };
+
+
+    /**
+     * Gets the bass boost properties. This method is useful when a snapshot of current
+     * bass boost settings must be saved by the application.
+     * @return a BassBoost.Settings object containing all current parameters values
+     * @throws IllegalStateException
+     * @throws IllegalArgumentException
+     * @throws UnsupportedOperationException
+     */
+    public BassBoost.Settings getProperties()
+    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
+        Settings settings = new Settings();
+        short[] value = new short[1];
+        checkStatus(getParameter(PARAM_STRENGTH, value));
+        settings.strength = value[0];
+        return settings;
+    }
+
+    /**
+     * Sets the bass boost properties. This method is useful when bass boost settings have to
+     * be applied from a previous backup.
+     * @throws IllegalStateException
+     * @throws IllegalArgumentException
+     * @throws UnsupportedOperationException
+     */
+    public void setProperties(BassBoost.Settings settings)
+    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
+        checkStatus(setParameter(PARAM_STRENGTH, settings.strength));
+    }
 }
diff --git a/media/java/android/media/EnvironmentalReverb.java b/media/java/android/media/EnvironmentalReverb.java
index 88230fc..3cc8452 100644
--- a/media/java/android/media/EnvironmentalReverb.java
+++ b/media/java/android/media/EnvironmentalReverb.java
@@ -19,12 +19,13 @@ package android.media;
 import android.app.Activity;
 import android.content.Context;
 import android.content.Intent;
+import android.media.AudioEffect;
 import android.os.Bundle;
 import android.util.Log;
+
 import java.nio.ByteOrder;
 import java.nio.ByteBuffer;
-
-import android.media.AudioEffect;
+import java.util.StringTokenizer;
 
 /**
  * A sound generated within a room travels in many directions. The listener first hears the
@@ -107,6 +108,9 @@ public class EnvironmentalReverb extends AudioEffect {
      */
     public static final int PARAM_DENSITY = 9;
 
+    // used by setProperties()/getProperties
+    private static final int PARAM_PROPERTIES = 10;
+
     /**
      * Registered listener for parameter changes
      */
@@ -142,7 +146,6 @@ public class EnvironmentalReverb extends AudioEffect {
     public EnvironmentalReverb(int priority, int audioSession)
     throws IllegalArgumentException, UnsupportedOperationException, RuntimeException {
         super(EFFECT_TYPE_ENV_REVERB, EFFECT_TYPE_NULL, priority, audioSession);
-        Log.e(TAG, "contructor");
     }
 
     /**
@@ -501,4 +504,169 @@ public class EnvironmentalReverb extends AudioEffect {
             }
         }
     }
+
+    /**
+     * The Settings class regroups all environmental reverb parameters. It is used in
+     * conjuntion with getProperties() and setProperties() methods to backup and restore
+     * all parameters in a single call.
+     */
+    public static class Settings {
+        public short roomLevel;
+        public short roomHFLevel;
+        public int decayTime;
+        public short decayHFRatio;
+        public short reflectionsLevel;
+        public int reflectionsDelay;
+        public short reverbLevel;
+        public int reverbDelay;
+        public short diffusion;
+        public short density;
+
+        public Settings() {
+        }
+
+        /**
+         * Settings class constructor from a key=value; pairs formatted string. The string is
+         * typically returned by Settings.toString() method.
+         * @throws IllegalArgumentException if the string is not correctly formatted.
+         */
+        public Settings(String settings) {
+            StringTokenizer st = new StringTokenizer(settings, "=;");
+            int tokens = st.countTokens();
+            if (st.countTokens() != 21) {
+                throw new IllegalArgumentException("settings: " + settings);
+            }
+            String key = st.nextToken();
+            if (!key.equals("EnvironmentalReverb")) {
+                throw new IllegalArgumentException(
+                        "invalid settings for EnvironmentalReverb: " + key);
+            }
+
+            try {
+                key = st.nextToken();
+                if (!key.equals("roomLevel")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                roomLevel = Short.parseShort(st.nextToken());
+                key = st.nextToken();
+                if (!key.equals("roomHFLevel")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                roomHFLevel = Short.parseShort(st.nextToken());
+                key = st.nextToken();
+                if (!key.equals("decayTime")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                decayTime = Integer.parseInt(st.nextToken());
+                key = st.nextToken();
+                if (!key.equals("decayHFRatio")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                decayHFRatio = Short.parseShort(st.nextToken());
+                key = st.nextToken();
+                if (!key.equals("reflectionsLevel")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                reflectionsLevel = Short.parseShort(st.nextToken());
+                key = st.nextToken();
+                if (!key.equals("reflectionsDelay")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                reflectionsDelay = Integer.parseInt(st.nextToken());
+                key = st.nextToken();
+                if (!key.equals("reverbLevel")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                reverbLevel = Short.parseShort(st.nextToken());
+                key = st.nextToken();
+                if (!key.equals("reverbDelay")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                reverbDelay = Integer.parseInt(st.nextToken());
+                key = st.nextToken();
+                if (!key.equals("diffusion")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                diffusion = Short.parseShort(st.nextToken());
+                key = st.nextToken();
+                if (!key.equals("density")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                density = Short.parseShort(st.nextToken());
+             } catch (NumberFormatException nfe) {
+                throw new IllegalArgumentException("invalid value for key: " + key);
+            }
+        }
+
+        @Override
+        public String toString() {
+            return new String (
+                    "EnvironmentalReverb"+
+                    ";roomLevel="+Short.toString(roomLevel)+
+                    ";roomHFLevel="+Short.toString(roomHFLevel)+
+                    ";decayTime="+Integer.toString(decayTime)+
+                    ";decayHFRatio="+Short.toString(decayHFRatio)+
+                    ";reflectionsLevel="+Short.toString(reflectionsLevel)+
+                    ";reflectionsDelay="+Integer.toString(reflectionsDelay)+
+                    ";reverbLevel="+Short.toString(reverbLevel)+
+                    ";reverbDelay="+Integer.toString(reverbDelay)+
+                    ";diffusion="+Short.toString(diffusion)+
+                    ";density="+Short.toString(density)
+                    );
+        }
+    };
+
+    // Keep this in sync with sizeof(s_reverb_settings) defined in
+    // frameworks/base/include/media/EffectEnvironmentalReverbApi.h
+    static private int PROPERTY_SIZE = 26;
+
+    /**
+     * Gets the environmental reverb properties. This method is useful when a snapshot of current
+     * reverb settings must be saved by the application.
+     * @return an EnvironmentalReverb.Settings object containing all current parameters values
+     * @throws IllegalStateException
+     * @throws IllegalArgumentException
+     * @throws UnsupportedOperationException
+     */
+    public EnvironmentalReverb.Settings getProperties()
+    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
+        byte[] param = new byte[PROPERTY_SIZE];
+        checkStatus(getParameter(PARAM_PROPERTIES, param));
+        Settings settings = new Settings();
+        settings.roomLevel = byteArrayToShort(param, 0);
+        settings.roomHFLevel = byteArrayToShort(param, 2);
+        settings.decayTime = byteArrayToInt(param, 4);
+        settings.decayHFRatio = byteArrayToShort(param, 8);
+        settings.reflectionsLevel = byteArrayToShort(param, 10);
+        settings.reflectionsDelay = byteArrayToInt(param, 12);
+        settings.reverbLevel = byteArrayToShort(param, 16);
+        settings.reverbDelay = byteArrayToInt(param, 18);
+        settings.diffusion = byteArrayToShort(param, 22);
+        settings.density = byteArrayToShort(param, 24);
+        return settings;
+    }
+
+    /**
+     * Sets the environmental reverb properties. This method is useful when reverb settings have to
+     * be applied from a previous backup.
+     * @throws IllegalStateException
+     * @throws IllegalArgumentException
+     * @throws UnsupportedOperationException
+     */
+    public void setProperties(EnvironmentalReverb.Settings settings)
+    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
+
+        byte[] param = concatArrays(shortToByteArray(settings.roomLevel),
+                                    shortToByteArray(settings.roomHFLevel),
+                                    intToByteArray(settings.decayTime),
+                                    shortToByteArray(settings.decayHFRatio),
+                                    shortToByteArray(settings.reflectionsLevel),
+                                    intToByteArray(settings.reflectionsDelay),
+                                    shortToByteArray(settings.reverbLevel),
+                                    intToByteArray(settings.reverbDelay),
+                                    shortToByteArray(settings.diffusion),
+                                    shortToByteArray(settings.density));
+
+        checkStatus(setParameter(PARAM_PROPERTIES, param));
+    }
 }
diff --git a/media/java/android/media/Equalizer.java b/media/java/android/media/Equalizer.java
index 082f694..21c37bb 100644
--- a/media/java/android/media/Equalizer.java
+++ b/media/java/android/media/Equalizer.java
@@ -19,13 +19,15 @@ package android.media;
 import android.app.Activity;
 import android.content.Context;
 import android.content.Intent;
+import android.media.AudioEffect;
 import android.os.Bundle;
 import android.util.Log;
+
 import java.nio.ByteOrder;
 import java.nio.ByteBuffer;
 import java.nio.CharBuffer;
+import java.util.StringTokenizer;
 
-import android.media.AudioEffect;
 
 /**
  * An Equalizer is used to alter the frequency response of a particular music source or of the main
@@ -87,12 +89,19 @@ public class Equalizer extends AudioEffect {
      * Request preset name. Parameter ID for OnParameterChangeListener
      */
     public static final int PARAM_GET_PRESET_NAME = 8;
+    // used by setProperties()/getProperties
+    private static final int PARAM_PROPERTIES = 9;
     /**
      * maximum size for perset name
      */
     public static final int PARAM_STRING_SIZE_MAX = 32;
 
     /**
+     * Number of bands implemented by Equalizer engine
+     */
+    private short mNumBands = 0;
+
+    /**
      * Number of presets implemented by Equalizer engine
      */
     private int mNumPresets;
@@ -136,6 +145,8 @@ public class Equalizer extends AudioEffect {
            UnsupportedOperationException, RuntimeException {
         super(EFFECT_TYPE_EQUALIZER, EFFECT_TYPE_NULL, priority, audioSession);
 
+        getNumberOfBands();
+
         mNumPresets = (int)getNumberOfPresets();
 
         if (mNumPresets != 0) {
@@ -150,7 +161,6 @@ public class Equalizer extends AudioEffect {
                 while (value[length] != 0) length++;
                 try {
                     mPresetNames[i] = new String(value, 0, length, "ISO-8859-1");
-                    Log.e(TAG, "preset #: "+i+" name: "+mPresetNames[i]+" length: "+length);
                 } catch (java.io.UnsupportedEncodingException e) {
                     Log.e(TAG, "preset name decode error");
                 }
@@ -167,11 +177,15 @@ public class Equalizer extends AudioEffect {
      */
     public short getNumberOfBands()
     throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
+        if (mNumBands != 0) {
+            return mNumBands;
+        }
         int[] param = new int[1];
         param[0] = PARAM_NUM_BANDS;
         short[] value = new short[1];
         checkStatus(getParameter(param, value));
-        return value[0];
+        mNumBands = value[0];
+        return mNumBands;
     }
 
     /**
@@ -440,4 +454,120 @@ public class Equalizer extends AudioEffect {
         }
     }
 
+    /**
+     * The Settings class regroups all equalizer parameters. It is used in
+     * conjuntion with getProperties() and setProperties() methods to backup and restore
+     * all parameters in a single call.
+     */
+    public static class Settings {
+        public short curPreset;
+        public short numBands = 0;
+        public short[] bandLevels = null;
+
+        public Settings() {
+        }
+
+        /**
+         * Settings class constructor from a key=value; pairs formatted string. The string is
+         * typically returned by Settings.toString() method.
+         * @throws IllegalArgumentException if the string is not correctly formatted.
+         */
+        public Settings(String settings) {
+            StringTokenizer st = new StringTokenizer(settings, "=;");
+            int tokens = st.countTokens();
+            if (st.countTokens() < 5) {
+                throw new IllegalArgumentException("settings: " + settings);
+            }
+            String key = st.nextToken();
+            if (!key.equals("Equalizer")) {
+                throw new IllegalArgumentException(
+                        "invalid settings for Equalizer: " + key);
+            }
+            try {
+                key = st.nextToken();
+                if (!key.equals("curPreset")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                curPreset = Short.parseShort(st.nextToken());
+                key = st.nextToken();
+                if (!key.equals("numBands")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                numBands = Short.parseShort(st.nextToken());
+                if (st.countTokens() != numBands*2) {
+                    throw new IllegalArgumentException("settings: " + settings);
+                }
+                bandLevels = new short[numBands];
+                for (int i = 0; i < numBands; i++) {
+                    key = st.nextToken();
+                    if (!key.equals("band"+(i+1)+"Level")) {
+                        throw new IllegalArgumentException("invalid key name: " + key);
+                    }
+                    bandLevels[i] = Short.parseShort(st.nextToken());
+                }
+             } catch (NumberFormatException nfe) {
+                throw new IllegalArgumentException("invalid value for key: " + key);
+            }
+        }
+
+        @Override
+        public String toString() {
+
+            String str = new String (
+                    "Equalizer"+
+                    ";curPreset="+Short.toString(curPreset)+
+                    ";numBands="+Short.toString(numBands)
+                    );
+            for (int i = 0; i < numBands; i++) {
+                str = str.concat(";band"+(i+1)+"Level="+Short.toString(bandLevels[i]));
+            }
+            return str;
+        }
+    };
+
+
+    /**
+     * Gets the equalizer properties. This method is useful when a snapshot of current
+     * equalizer settings must be saved by the application.
+     * @return an Equalizer.Settings object containing all current parameters values
+     * @throws IllegalStateException
+     * @throws IllegalArgumentException
+     * @throws UnsupportedOperationException
+     */
+    public Equalizer.Settings getProperties()
+    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
+        byte[] param = new byte[4 + mNumBands * 2];
+        checkStatus(getParameter(PARAM_PROPERTIES, param));
+        Settings settings = new Settings();
+        settings.curPreset = byteArrayToShort(param, 0);
+        settings.numBands = byteArrayToShort(param, 2);
+        settings.bandLevels = new short[mNumBands];
+        for (int i = 0; i < mNumBands; i++) {
+            settings.bandLevels[i] = byteArrayToShort(param, 4 + 2*i);
+        }
+        return settings;
+    }
+
+    /**
+     * Sets the equalizer properties. This method is useful when equalizer settings have to
+     * be applied from a previous backup.
+     * @throws IllegalStateException
+     * @throws IllegalArgumentException
+     * @throws UnsupportedOperationException
+     */
+    public void setProperties(Equalizer.Settings settings)
+    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
+        if (settings.numBands != settings.bandLevels.length ||
+            settings.numBands != mNumBands) {
+            throw new IllegalArgumentException("settings invalid band count: " +settings.numBands);
+        }
+
+        byte[] param = concatArrays(shortToByteArray(settings.curPreset),
+                                    shortToByteArray(mNumBands));
+        for (int i = 0; i < mNumBands; i++) {
+            param = concatArrays(param,
+                                 shortToByteArray(settings.bandLevels[i]));
+        }
+        checkStatus(setParameter(PARAM_PROPERTIES, param));
+    }
 }
diff --git a/media/java/android/media/PresetReverb.java b/media/java/android/media/PresetReverb.java
index 83a01a4..c7d7037 100644
--- a/media/java/android/media/PresetReverb.java
+++ b/media/java/android/media/PresetReverb.java
@@ -19,12 +19,14 @@ package android.media;
 import android.app.Activity;
 import android.content.Context;
 import android.content.Intent;
+import android.media.AudioEffect;
 import android.os.Bundle;
 import android.util.Log;
+
 import java.nio.ByteOrder;
 import java.nio.ByteBuffer;
+import java.util.StringTokenizer;
 
-import android.media.AudioEffect;
 
 /**
  * A sound generated within a room travels in many directions. The listener first hears the
@@ -116,7 +118,6 @@ public class PresetReverb extends AudioEffect {
     public PresetReverb(int priority, int audioSession)
     throws IllegalArgumentException, UnsupportedOperationException, RuntimeException {
         super(EFFECT_TYPE_PRESET_REVERB, EFFECT_TYPE_NULL, priority, audioSession);
-        Log.e(TAG, "contructor");
     }
 
     /**
@@ -144,10 +145,8 @@ public class PresetReverb extends AudioEffect {
      */
     public short getPreset()
     throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
-        int[] param = new int[1];
-        param[0] = PARAM_PRESET;
         short[] value = new short[1];
-        checkStatus(getParameter(param, value));
+        checkStatus(getParameter(PARAM_PRESET, value));
         return value[0];
     }
 
@@ -216,4 +215,82 @@ public class PresetReverb extends AudioEffect {
             }
         }
     }
+
+    /**
+     * The Settings class regroups all preset reverb parameters. It is used in
+     * conjuntion with getProperties() and setProperties() methods to backup and restore
+     * all parameters in a single call.
+     */
+    public static class Settings {
+        public short preset;
+
+        public Settings() {
+        }
+
+        /**
+         * Settings class constructor from a key=value; pairs formatted string. The string is
+         * typically returned by Settings.toString() method.
+         * @throws IllegalArgumentException if the string is not correctly formatted.
+         */
+        public Settings(String settings) {
+            StringTokenizer st = new StringTokenizer(settings, "=;");
+            int tokens = st.countTokens();
+            if (st.countTokens() != 3) {
+                throw new IllegalArgumentException("settings: " + settings);
+            }
+            String key = st.nextToken();
+            if (!key.equals("PresetReverb")) {
+                throw new IllegalArgumentException(
+                        "invalid settings for PresetReverb: " + key);
+            }
+            try {
+                key = st.nextToken();
+                if (!key.equals("preset")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                preset = Short.parseShort(st.nextToken());
+             } catch (NumberFormatException nfe) {
+                throw new IllegalArgumentException("invalid value for key: " + key);
+            }
+        }
+
+        @Override
+        public String toString() {
+            String str = new String (
+                    "PresetReverb"+
+                    ";preset="+Short.toString(preset)
+                    );
+            return str;
+        }
+    };
+
+
+    /**
+     * Gets the preset reverb properties. This method is useful when a snapshot of current
+     * preset reverb settings must be saved by the application.
+     * @return a PresetReverb.Settings object containing all current parameters values
+     * @throws IllegalStateException
+     * @throws IllegalArgumentException
+     * @throws UnsupportedOperationException
+     */
+    public PresetReverb.Settings getProperties()
+    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
+        Settings settings = new Settings();
+        short[] value = new short[1];
+        checkStatus(getParameter(PARAM_PRESET, value));
+        settings.preset = value[0];
+        return settings;
+    }
+
+    /**
+     * Sets the preset reverb properties. This method is useful when preset reverb settings have to
+     * be applied from a previous backup.
+     * @throws IllegalStateException
+     * @throws IllegalArgumentException
+     * @throws UnsupportedOperationException
+     */
+    public void setProperties(PresetReverb.Settings settings)
+    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
+        checkStatus(setParameter(PARAM_PRESET, settings.preset));
+    }
 }
diff --git a/media/java/android/media/Virtualizer.java b/media/java/android/media/Virtualizer.java
index 9f71297..2c8909e 100644
--- a/media/java/android/media/Virtualizer.java
+++ b/media/java/android/media/Virtualizer.java
@@ -19,13 +19,15 @@ package android.media;
 import android.app.Activity;
 import android.content.Context;
 import android.content.Intent;
+import android.media.AudioEffect;
 import android.os.Bundle;
 import android.util.Log;
+
 import java.nio.ByteOrder;
 import java.nio.ByteBuffer;
 import java.nio.CharBuffer;
+import java.util.StringTokenizer;
 
-import android.media.AudioEffect;
 
 /**
  * An audio virtualizer is a general name for an effect to spatialize audio channels. The exact
@@ -211,4 +213,82 @@ public class Virtualizer extends AudioEffect {
             }
         }
     }
+
+    /**
+     * The Settings class regroups all virtualizer parameters. It is used in
+     * conjuntion with getProperties() and setProperties() methods to backup and restore
+     * all parameters in a single call.
+     */
+    public static class Settings {
+        public short strength;
+
+        public Settings() {
+        }
+
+        /**
+         * Settings class constructor from a key=value; pairs formatted string. The string is
+         * typically returned by Settings.toString() method.
+         * @throws IllegalArgumentException if the string is not correctly formatted.
+         */
+        public Settings(String settings) {
+            StringTokenizer st = new StringTokenizer(settings, "=;");
+            int tokens = st.countTokens();
+            if (st.countTokens() != 3) {
+                throw new IllegalArgumentException("settings: " + settings);
+            }
+            String key = st.nextToken();
+            if (!key.equals("Virtualizer")) {
+                throw new IllegalArgumentException(
+                        "invalid settings for Virtualizer: " + key);
+            }
+            try {
+                key = st.nextToken();
+                if (!key.equals("strength")) {
+                    throw new IllegalArgumentException("invalid key name: " + key);
+                }
+                strength = Short.parseShort(st.nextToken());
+             } catch (NumberFormatException nfe) {
+                throw new IllegalArgumentException("invalid value for key: " + key);
+            }
+        }
+
+        @Override
+        public String toString() {
+            String str = new String (
+                    "Virtualizer"+
+                    ";strength="+Short.toString(strength)
+                    );
+            return str;
+        }
+    };
+
+
+    /**
+     * Gets the virtualizer properties. This method is useful when a snapshot of current
+     * virtualizer settings must be saved by the application.
+     * @return a Virtualizer.Settings object containing all current parameters values
+     * @throws IllegalStateException
+     * @throws IllegalArgumentException
+     * @throws UnsupportedOperationException
+     */
+    public Virtualizer.Settings getProperties()
+    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
+        Settings settings = new Settings();
+        short[] value = new short[1];
+        checkStatus(getParameter(PARAM_STRENGTH, value));
+        settings.strength = value[0];
+        return settings;
+    }
+
+    /**
+     * Sets the virtualizer properties. This method is useful when virtualizer settings have to
+     * be applied from a previous backup.
+     * @throws IllegalStateException
+     * @throws IllegalArgumentException
+     * @throws UnsupportedOperationException
+     */
+    public void setProperties(Virtualizer.Settings settings)
+    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
+        checkStatus(setParameter(PARAM_STRENGTH, settings.strength));
+    }
 }