1 /*

     2 * Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  This class implements

    15  *                javax.microedition.amms.control.tuner.TunerControl

    16  *

    17 */

    18 

    19 

    20 package com.nokia.amms.control.tuner;

    21 

    22 import javax.microedition.media.MediaException;

    23 import javax.microedition.media.Control;

    24 import com.nokia.microedition.media.InternalPlayer;

    25 import com.nokia.microedition.media.PlayerImpl;

    26 import com.nokia.microedition.media.Locator;

    27 import com.nokia.microedition.media.ManagerImpl;

    28 import com.nokia.microedition.media.control.ControlImpl;

    29 import com.nokia.mj.impl.rt.legacy.NativeError;

    30 

    31 public class TunerControlImpl

    32         extends ControlImpl

    33         implements javax.microedition.amms.control.tuner.TunerControl

    34 {

    35     //preset name max length

    36     private static final int MAX_PRESET_NAME_LENGTH = 100;

    37     //max number of presets

    38     private static final int MAX_NUMBER_OF_PRESETS = 20;

    39     //all frequencys are in 100 Hertzs

    40     private static final int HERTZ_MULTIPLIER = 100;

    41 

    42     /**

    43      * Constructor

    44      */

    45     public TunerControlImpl()

    46     {

    47         //JDEBUG( "AMMS TunerControlImpl Constructor" );

    48     }

    49 

    50     /**

    51      * Gets the minimum frequency supported by this tuner

    52      * with the given modulation.

    53      *

    54      * @param modulation The modulation whose supported minimum frequency

    55      * is asked.

    56      * @return The minimum frequency in 100 Hertzs.

    57      * @throws IllegalArgumentException if the <code>modulation</code> is not supported or it is null.

    58      */

    59     public int getMinFreq(String aModulation)

    60     {

    61         if (aModulation != MODULATION_FM)

    62         {

    63             throw new IllegalArgumentException("Modulation is not valid.");

    64         }

    65 

    66         int minFreq = _getMinFreq(iEventSource,

    67                                   iControlHandle);

    68 

    69         NativeError.check(minFreq);

    70 

    71         return minFreq / HERTZ_MULTIPLIER;

    72     }

    73 

    74     /**

    75      * Gets the maximum frequency supported by this tuner

    76      * with the given modulation.

    77      *

    78      * @param modulation The modulation whose supported maximum frequency

    79      * is asked.

    80      * @return The maximum frequency in 100 Hertzs.

    81      * @throws IllegalArgumentException if the <code>modulation</code> is not supported or it is null.

    82      */

    83     public int getMaxFreq(String aModulation)

    84     {

    85         if (aModulation != MODULATION_FM)

    86         {

    87             throw new IllegalArgumentException("Modulation is not valid.");

    88         }

    89 

    90         int maxFreq = _getMaxFreq(iEventSource,

    91                                   iControlHandle);

    92 

    93         NativeError.check(maxFreq);

    94 

    95         return maxFreq / HERTZ_MULTIPLIER;

    96     }

    97 

    98     /**

    99      * Tunes to the given frequency or to the closest supported frequency.

   100      *

   101      * @param freq The frequency in 100 Hertzs that will be taken into use.

   102      * If that frequency is not supported, the closest supported

   103      * frequency will be taken into use.

   104      *

   105      * @param modulation The modulation to be used. <code>TunerControl</code> specifies

   106      * predefined constants <code>MODULATION_FM</code> and <code>MODULATION_AM</code>

   107      * but other modulations can be supported as well. Supported modulations can be queried

   108      * by <code>System</code> property <code>tuner.modulations</code>.

   109      *

   110      * @throws IllegalArgumentException if <code>freq</code> is not inside the frequency band supported

   111      * by the device or if the <code>modulation</code> is not supported or the <code>modulation</code> is null.

   112      *

   113      * @return the frequency in 100 Hertzs that was taken into use.

   114      */

   115     public int setFrequency(int aFreq, String aModulation)

   116     {

   117         if (aModulation != MODULATION_FM)

   118         {

   119             throw new IllegalArgumentException("Modulation is not valid.");

   120         }

   121 

   122         int freqInUse = _setFrequency(iEventSource,

   123                                       iControlHandle,

   124                                       aFreq * HERTZ_MULTIPLIER);

   125 

   126         NativeError.check(freqInUse);

   127 

   128         return freqInUse / HERTZ_MULTIPLIER;

   129     }

   130 

   131     /**

   132      * Gets the frequency which the tuner has been tuned to.

   133      *

   134      * @return The frequency to which the device has been tuned, in 100 Hertzs.

   135      */

   136     public int getFrequency()

   137     {

   138         int freq = _getFrequency(iEventSource, iControlHandle);

   139 

   140         NativeError.check(freq);

   141 

   142         return freq / HERTZ_MULTIPLIER;

   143     }

   144 

   145     /**

   146      * <p>Seeks for the next broadcast signal. If the end of the Player's

   147      * frequency band is reached before a signal was found, the scan

   148      * continues from the other end until a signal is found or the

   149      * starting frequency is reached.</p>

   150      *

   151      * <p>After seeking, the frequency of the Player is the one that

   152      * was returned or if nothing was found, the original frequency.</p>

   153      *

   154      * @param startFreq the frequency in 100 Hertzs wherefrom the scan starts (inclusive)

   155      *

   156      * @param modulation The modulation to be used. <code>TunerControl</code> specifies

   157      * predefined constants <code>MODULATION_FM</code> and <code>MODULATION_AM</code>

   158      * but other modulations can be supported as well. Supported modulations can be queried

   159      * by <code>System</code> property <code>tuner.modulations</code>.

   160      * @param upwards if <code>true</code>, the scan proceeds towards higher frequencies,

   161      * otherwise towards lower frequencies

   162      *

   163      * @return The found frequency in 100 Hertzs or, if no signal was found, 0.

   164      *

   165      * @throws IllegalArgumentException if <code>startFreq</code> is not between the supported minimum

   166      * and maximum frequencies or if the <code>modulation</code> is null.

   167      * @throws MediaException if the seek functionality is not available for the given modulation.

   168      */

   169     public int seek(int aStartFreq, String aModulation, boolean aUpwards)

   170     throws MediaException

   171     {

   172         if (aModulation != MODULATION_FM)

   173         {

   174             throw new IllegalArgumentException("Modulation is not valid.");

   175         }

   176 

   177         int foundFreq = _seek(iEventSource,

   178                               iControlHandle,

   179                               aStartFreq * HERTZ_MULTIPLIER,

   180                               aUpwards);

   181 

   182         NativeError.check(foundFreq);

   183 

   184         return foundFreq / HERTZ_MULTIPLIER;

   185     }

   186 

   187     /**

   188      * Gets the current squelching (muting in frequencies without broadcast)

   189      * setting.

   190      *

   191      * @return <code>true</code> if squelch is on or <code>false</code> if squelch is off.

   192      */

   193     public boolean getSquelch()

   194     {

   195         int retValue = _getSquelch(iEventSource, iControlHandle);

   196 

   197         NativeError.check(retValue);

   198 

   199         if (retValue == NativeError.KErrNone)

   200         {

   201             return true;

   202         }

   203 

   204         return false;

   205     }

   206 

   207     /**

   208      * Sets squelching on or off. Squelching means muting the frequencies

   209      * that do not contain radio broadcast.

   210      *

   211      * @param squelch <code>true</code> to turn the squelch on or <code>false</code> to turn the squelch off.

   212      * @throws MediaException if the given squelch setting is not supported.

   213      */

   214     public void setSquelch(boolean aSquelch) throws MediaException

   215     {

   216         int err = _setSquelch(iEventSource, iControlHandle, aSquelch);

   217 

   218         NativeError.check(err);

   219     }

   220 

   221     /**

   222      * Gets the modulation in use.

   223      *

   224      * @return The modulation currently in use.

   225      */

   226     public String getModulation()

   227     {

   228         //only FM modulation is supported

   229         return MODULATION_FM;

   230     }

   231 

   232     /**

   233      * Gets the strength of the recepted signal.

   234      *

   235      * @return A value between 0 and 100 where 0 means the faintest and 100 the strongest possible signal strength.

   236      * @throws MediaException if querying the signal strength is not supported.

   237      */

   238     public int getSignalStrength() throws MediaException

   239     {

   240         int signalStrength = _getSignalStrength(iEventSource,

   241                                                 iControlHandle);

   242 

   243         if (signalStrength != NativeError.KErrNone)

   244         {

   245             throw new MediaException("Signal strength is not supported.");

   246         }

   247 

   248         return signalStrength;

   249     }

   250 

   251     /**

   252      * Gets the stereo mode in use.

   253      *

   254      * @return The stereo mode in use. Stereo mode is one of <code>MONO</code>,

   255      * <code>STEREO</code> or <code>AUTO</code>.

   256      */

   257     public int getStereoMode()

   258     {

   259         int stereoMode = _getStereoMode(iEventSource, iControlHandle);

   260 

   261         NativeError.check(stereoMode);

   262 

   263         return stereoMode;

   264     }

   265 

   266     /**

   267      * Sets the stereo mode.

   268      *

   269      * @param mode The stereo mode to be used. Stereo mode is one of <code>MONO</code>,

   270      * <code>STEREO</code> or <code>AUTO</code>.

   271      * @throws IllegalArgumentException if the given mode is not supported.

   272      */

   273     public void setStereoMode(int aStereoMode)

   274     {

   275         if (aStereoMode != MONO && aStereoMode != STEREO && aStereoMode != AUTO)

   276         {

   277             throw new IllegalArgumentException();

   278         }

   279 

   280         int err = _setStereoMode(iEventSource, iControlHandle, aStereoMode);

   281 

   282         if (err != NativeError.KErrNone)

   283         {

   284             throw new IllegalArgumentException("Stereo mode is not supported.");

   285         }

   286     }

   287 

   288     /**

   289      * Gets the number of presets. The numbering of presets starts from one and the largest

   290      * preset number equals the value returned from this method.

   291      *

   292      * @return The number of presets, or zero if the presets are not supported.

   293      */

   294     public int getNumberOfPresets()

   295     {

   296 

   297         return 0;

   298     }

   299 

   300     /**

   301      * Tunes the tuner by using settings specified in the preset. Changes to

   302      * presets following a <code>usePreset</code> call do not tune the tuner automatically.

   303      *

   304      * @param preset the preset to be used.

   305      * @throws IllegalArgumentException if <code>preset</code> &lt 1 or <code>preset</code> &gt number of presets.

   306      */

   307     public void usePreset(int aPreset)

   308     {

   309         if (aPreset < 0 || aPreset > MAX_NUMBER_OF_PRESETS)

   310         {

   311             throw new IllegalArgumentException("Preset out of preset range.");

   312         }

   313         int err = _usePreset(iEventSource, iControlHandle, aPreset);

   314 

   315         NativeError.check(err);

   316     }

   317 

   318     /**

   319      * Configures the preset using current frequency and modulation

   320      * (and stereo mode if native presets support storing it).

   321      *

   322      * @param preset the preset to be set.

   323      * @throws IllegalArgumentException if <code>preset</code> &lt 1 or <code>preset</code> &gt number of preset range.

   324      * @throws SecurityException if setting presets has been prohibited.

   325      */

   326     public void setPreset(int aPreset)

   327     {

   328         if (aPreset < 0 || aPreset > MAX_NUMBER_OF_PRESETS)

   329         {

   330             throw new IllegalArgumentException("Preset out of preset range.");

   331         }

   332         int err = _setPreset(iEventSource, iControlHandle, aPreset);

   333 

   334         NativeError.check(err);

   335     }

   336 

   337     /**

   338      * Configures the preset using given settings.

   339      * The stereo mode might not be stored if it is not supported by the presets.

   340      * (In that case, <code>IllegalArgumentException</code> is not thrown.)

   341      *

   342      * @param preset the preset to be configured.

   343      * @param freq the frequency of the preset in 100 Hertzs.

   344      * @param mod the modulation of the preset.

   345      * @param stereoMode the stereo mode of the preset.

   346      * @throws IllegalArgumentException if <code>preset</code> &lt 1 or <code>preset</code> &gt number of presets or

   347      * <code>freq</code> or <code>modulation</code> are not available or if the <code>modulation</code> is null or if <code>stereoMode</code> is not a supported stereo mode.

   348      * @throws SecurityException if setting presets has been prohibited.

   349      */

   350     public void setPreset(int aPreset, int aFreq, String aModulation, int aStereoMode)

   351     {

   352         if (aPreset < 0 || aPreset > MAX_NUMBER_OF_PRESETS)

   353         {

   354             throw new IllegalArgumentException("Preset out of preset range.");

   355         }

   356         if (aModulation != MODULATION_FM)

   357         {

   358             throw new IllegalArgumentException("Modulation is not valid.");

   359         }

   360         if (aStereoMode != MONO && aStereoMode != STEREO && aStereoMode != AUTO)

   361         {

   362             throw new IllegalArgumentException("Stereo mode is not supported.");

   363         }

   364 

   365         int err = _setPreset(iEventSource, iControlHandle, aPreset, aFreq * HERTZ_MULTIPLIER, aStereoMode);

   366 

   367         NativeError.check(err);

   368     }

   369 

   370     /**

   371      * Gets the preset's frequency.

   372      *

   373      * @param preset the preset whose frequency is to be returned.

   374      * @return The frequency of the preset in 100 Hertzs.

   375      * @throws IllegalArgumentException if <code>preset</code> &lt 1 or <code>preset</code> &gt number of presets.

   376      */

   377     public int getPresetFrequency(int aPreset)

   378     {

   379         if (aPreset < 0 || aPreset > MAX_NUMBER_OF_PRESETS)

   380         {

   381             throw new IllegalArgumentException("Preset out of preset range.");

   382         }

   383 

   384         int presetFreq = _getPresetFrequency(iEventSource, iControlHandle, aPreset);

   385 

   386         NativeError.check(presetFreq);

   387 

   388         return presetFreq / HERTZ_MULTIPLIER;

   389     }

   390 

   391     /**

   392      * Gets the preset's modulation.

   393      *

   394      * @param preset the preset whose modulation is to be returned.

   395      * @return The modulation of the preset.

   396      * @throws IllegalArgumentException if <code>preset</code> &lt 1 or <code>preset</code> &gt number of presets.

   397      */

   398     public String getPresetModulation(int aPreset)

   399     {

   400         if (aPreset < 0 || aPreset > MAX_NUMBER_OF_PRESETS)

   401         {

   402             throw new IllegalArgumentException("Preset out of preset range.");

   403         }

   404         return MODULATION_FM;

   405     }

   406 

   407     /**

   408      * Gets the preset's stereo mode.

   409      *

   410      * @param preset the preset whose stereo mode is to be returned.

   411      * @return The stereo mode of the preset. Stereo mode is one of

   412      * <code>MONO</code>, <code>STEREO</code> or <code>AUTO</code>.

   413      * @throws IllegalArgumentException if <code>preset</code> &lt 1 or <code>preset</code> &gt number of presets.

   414      * @throws MediaException if the presets do not support storing of the stereo mode.

   415      */

   416     public int getPresetStereoMode(int aPreset) throws MediaException

   417     {

   418         if (aPreset < 0 || aPreset > MAX_NUMBER_OF_PRESETS)

   419         {

   420             throw new IllegalArgumentException("Preset out of preset range.");

   421         }

   422 

   423         int presetStereoMode = _getPresetStereoMode(iEventSource, iControlHandle, aPreset);

   424 

   425         NativeError.check(presetStereoMode);

   426 

   427         return presetStereoMode;

   428     }

   429 

   430     /**

   431      * Gets the preset name.

   432      *

   433      * @param preset the preset whose name is to be returned.

   434      * @return A <code>String</code> containing the preset name.

   435      * @throws IllegalArgumentException if <code>preset</code> &lt 1 or <code>preset</code> &gt number of presets.

   436      */

   437     public String getPresetName(int aPreset)

   438     {

   439         if (aPreset < 0 || aPreset > MAX_NUMBER_OF_PRESETS)

   440         {

   441             throw new IllegalArgumentException("Preset out of preset range.");

   442         }

   443 

   444         int[] error = new int[ 1 ];

   445 

   446         String presetName = _getPresetName(iEventSource, iControlHandle, aPreset, error);

   447 

   448         NativeError.check(error[ 0 ]);

   449 

   450         return presetName;

   451     }

   452 

   453     /**

   454      * Sets the preset name.

   455      *

   456      * @param preset the preset whose name is to be set.

   457      * @param name the name of the preset.

   458      * @throws IllegalArgumentException if <code>preset</code> &lt 1 or <code>preset</code> &gt number of presets or

   459      * if the <code>name</code> is null.

   460      * @throws SecurityException if setting presets has been prohibited.

   461      */

   462     public void setPresetName(int aPreset, String aName)

   463     {

   464         if (aPreset < 0 || aPreset > MAX_NUMBER_OF_PRESETS)

   465         {

   466             throw new IllegalArgumentException("Preset out of preset range.");

   467         }

   468         if (aName.length() > MAX_PRESET_NAME_LENGTH)

   469         {

   470             throw new IllegalArgumentException("Preset name too long");

   471         }

   472 

   473         int err = _setPresetName(iEventSource, iControlHandle, aPreset, aName);

   474 

   475         NativeError.check(err);

   476     }

   477 

   478 

   479     private native int _getMinFreq(int aEventSourceHandle,

   480                                    int aTunerControlHandle);

   481 

   482     private native int _getMaxFreq(int aEventSourceHandle,

   483                                    int aTunerControlHandle);

   484 

   485     private native int _setFrequency(int aEventSourceHandle,

   486                                      int aTunerControlHandle,

   487                                      int aFreq);

   488 

   489     private native int _getFrequency(int aEventSourceHandle,

   490                                      int aTunerControlHandle);

   491 

   492 

   493     private native int _seek(int aEventSourceHandle,

   494                              int aTunerControlHandle,

   495                              int aStartFreq,

   496                              boolean aUpwards);

   497 

   498     private native int _getSquelch(int aEventSourceHandle,

   499                                    int aTunerControlHandle);

   500 

   501     private native int _setSquelch(int aEventSourceHandle,

   502                                    int aTunerControlHandle,

   503                                    boolean aSquelch);

   504 

   505     private native int _getSignalStrength(int aEventSourceHandle,

   506                                           int aTunerControlHandle);

   507 

   508     private native int _getStereoMode(int aEventSourceHandle,

   509                                       int aTunerControlHandle);

   510 

   511     private native int _setStereoMode(int aEventSourceHandle,

   512                                       int aTunerControlHandle,

   513                                       int aStereoMode);

   514 

   515     private native int _usePreset(int aEventSourceHandle,

   516                                   int aTunerControlHandle,

   517                                   int aPreset);

   518 

   519     private native int _setPreset(int aEventSourceHandle,

   520                                   int aTunerControlHandle,

   521                                   int aPreset);

   522 

   523     private native int _setPreset(int aEventSourceHandle,

   524                                   int aTunerControlHandle,

   525                                   int aPreset,

   526                                   int aFreq,

   527                                   int aStereoMode);

   528 

   529     private native int _getPresetFrequency(int aEventSourceHandle,

   530                                            int aTunerControlHandle,

   531                                            int aPreset);

   532 

   533     private native int _getPresetStereoMode(int aEventSourceHandle,

   534                                             int aTunerControlHandle,

   535                                             int aPreset);

   536 

   537     private native int _setPresetName(int aEventSourceHandle,

   538                                       int aTunerControlHandle,

   539                                       int aPreset,

   540                                       String aName);

   541 

   542     private native String _getPresetName(int aEventSourceHandle,

   543                                          int aTunerControlHandle,

   544                                          int aPreset,

   545                                          int[] aError);

   546 

   547 

   548 }