1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/mm/mm_plat/fm_radio_adaptation_api/inc/FMRadioTunerControl.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,567 @@
1.4 +/*
1.5 +* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: This class is the main interface to FMRadioTunerControl Adaptation API.
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +
1.23 +#ifndef C_FMRADIOTUNERCONTROL_H
1.24 +#define C_FMRADIOTUNERCONTROL_H
1.25 +
1.26 +#include <e32base.h>
1.27 +
1.28 +class MRdsControl;
1.29 +class MRdsControlObserver;
1.30 +
1.31 +/**
1.32 + * FM tuner error definitions.
1.33 + * In addition to the standard system error code, the following error codes may
1.34 + * be returned.
1.35 + */
1.36 +typedef TInt TFMRadioTunerError;
1.37 +const TFMRadioTunerError KFMRadioErrHardwareFaulty = -12050;
1.38 +const TFMRadioTunerError KFMRadioErrTuning = -12051;
1.39 +const TFMRadioTunerError KFMRadioErrFrequencyOutOfBandRange = -12052;
1.40 +const TFMRadioTunerError KFMRadioErrFrequencyNotValid = -12053;
1.41 +const TFMRadioTunerError KFMRadioErrNotPermittedInCurrentState = -12054;
1.42 +const TFMRadioTunerError KFMRadioErrDuplicateRequest = -12055;
1.43 +const TFMRadioTunerError KFMRadioErrAntennaNotConnected = -12056;
1.44 +const TFMRadioTunerError KFMRadioErrFmTransmitterActive = -12057;
1.45 +
1.46 +
1.47 +/** FM radio frequency range */
1.48 +enum TFMRadioFrequencyRange
1.49 + {
1.50 + EFMRadioFrequencyEuroAmerica = 0x01, // European and American FM frequency range
1.51 + EFMRadioFrequencyJapan = 0x02, // Japanese FM frequency range
1.52 + EFMRadioFrequencyAmericaNarrow = 0x04 // North American band (87.9-108 Mhz)
1.53 + };
1.54 +
1.55 +
1.56 +/** FM radio seek direction */
1.57 +enum TFMRadioSeekDirection
1.58 + {
1.59 + EFMRadioSeekUp,
1.60 + EFMRadioSeekDown
1.61 + };
1.62 +
1.63 +
1.64 +/** FM radio audio mode */
1.65 +enum TFMRadioAudioMode
1.66 + {
1.67 + EFMRadioAudioMono = 0x01,
1.68 + EFMRadioAudioStereo = 0x02
1.69 + };
1.70 +
1.71 +/** FM radio sample rates */
1.72 +enum TFMRadioSampleRate
1.73 + {
1.74 + EFMRadioSampleRate8000Hz = 0x0001,
1.75 + EFMRadioSampleRate11025Hz = 0x0002,
1.76 + EFMRadioSampleRate12000Hz = 0x0004,
1.77 + EFMRadioSampleRate16000Hz = 0x0008,
1.78 + EFMRadioSampleRate22050Hz = 0x0010,
1.79 + EFMRadioSampleRate24000Hz = 0x0020,
1.80 + EFMRadioSampleRate32000Hz = 0x0040,
1.81 + EFMRadioSampleRate44100Hz = 0x0080,
1.82 + EFMRadioSampleRate48000Hz = 0x0100,
1.83 + EFMRadioSampleRate64000Hz = 0x0200,
1.84 + EFMRadioSampleRate88200Hz = 0x0400,
1.85 + EFMRadioSampleRate96000Hz = 0x0800
1.86 + };
1.87 +
1.88 +
1.89 +/**
1.90 + * The FM Tuner Capabilities class defines the capabilities of the FM tuner on the
1.91 + * device, as retrieved using the function GetCapabilities. Adaptation can utilize this
1.92 + * class to indicate the hardware limitations.
1.93 + *
1.94 + * @since S60 3.0
1.95 + */
1.96 +class TFMRadioCapabilities
1.97 + {
1.98 +
1.99 +#ifdef RD_FM_RADIO_ENHANCEMENTS
1.100 +
1.101 + // Tuner Features bit flags - may be extended in future
1.102 + enum TFMTunerFeatures
1.103 + {
1.104 + // This bit is set if the tuner can be used even when the device is in
1.105 + // offline mode. Some tuner may not allow this due to hw conflict.
1.106 + ETunerAvailableInOfflineMode = 0x01,
1.107 + // This bit is set if the tuner has RDS support.
1.108 + ETunerRdsSupport = 0x02,
1.109 + // This bit is set when the device supports dual tuner, which allows
1.110 + // more extensive RDS feature support.
1.111 + ETunerDualTunerSupport = 0x04
1.112 + };
1.113 +#endif
1.114 +
1.115 + public:
1.116 + // Bitmask using TFMRadioSampleRate
1.117 + TUint iSampleRate;
1.118 + // Bitmask using TFMRadioAudioMode
1.119 + TUint iChannels;
1.120 + // Encodings supported - FourCC
1.121 + TUint32 iEncoding ;
1.122 +
1.123 + // Bitmask using TFMRadioFrequencyRange; used to indicate supported ranges.
1.124 + TUint32 iTunerBands;
1.125 + // Bitmask using TFMTunerFeatures; used to indicate supported tuner features.
1.126 + TUint32 iTunerFunctions;
1.127 + // Reserved for future
1.128 + TUint32 iAdditionalFunctions1;
1.129 + // Reserved for future
1.130 + TUint32 iAdditionalFunctions2;
1.131 +
1.132 + };
1.133 +
1.134 +
1.135 +/**
1.136 + * This class provides the interface class to be implemented by object receiving request
1.137 + * complete notification from FM tuner control. These functions are called once the asynchronous
1.138 + * request completes successfully or with an error.
1.139 + *
1.140 + * In addition, this class provides the interface for receiving events from FM tuner control.
1.141 + *
1.142 + * @since S60 3.0
1.143 + */
1.144 +class MFMRadioTunerControlObserver
1.145 + {
1.146 +public:
1.147 +
1.148 + /**
1.149 + * Notification mechanism provided to inform client that TunerOn request has completed.
1.150 + *
1.151 + * @since S60 3.0
1.152 + * @param aError The result of the request indicating whether the operation was
1.153 + * successful or not.
1.154 + */
1.155 + virtual void TunerOnComplete( TFMRadioTunerError aError ) = 0;
1.156 +
1.157 + /**
1.158 + * Notification mechanism provided to inform client that TunerOff request has completed.
1.159 + *
1.160 + * @since S60 3.0
1.161 + * @param aError The result of the request indicating whether the operation was
1.162 + * successful or not.
1.163 + */
1.164 + virtual void TunerOffComplete( TFMRadioTunerError aError ) = 0;
1.165 +
1.166 + /**
1.167 + * Notification mechanism provided to inform client that SetFrequencyRange request has completed.
1.168 + *
1.169 + * @since S60 3.0
1.170 + * @param aError The result of the request indicating whether the operation was
1.171 + * successful or not.
1.172 + */
1.173 + virtual void SetFrequencyRangeComplete( TFMRadioTunerError aError ) = 0;
1.174 +
1.175 + /**
1.176 + * Notification mechanism provided to inform client that SetFrequency request has completed.
1.177 + *
1.178 + * @since S60 3.0
1.179 + * @param aError The result of the request indicating whether the operation was
1.180 + * successful or not.
1.181 + */
1.182 + virtual void SetFrequencyComplete( TFMRadioTunerError aError ) = 0;
1.183 +
1.184 + /**
1.185 + * Notification mechanism provided to inform client that StationSeek request has completed.
1.186 + *
1.187 + * @since S60 3.0
1.188 + * @param aError The result of the request indicating whether the operation was
1.189 + * successful or not.
1.190 + * @param aFrequency The frequency(Hz) of the radio station that was found.
1.191 + */
1.192 + virtual void StationSeekComplete( TFMRadioTunerError aError, TInt aFrequency ) = 0;
1.193 +
1.194 + /**
1.195 + * Notification mechanism provided to inform client that AudioMode request has completed.
1.196 + *
1.197 + * @since S60 3.0
1.198 + * @param aError The result of the request indicating whether the operation was
1.199 + * successful or not.
1.200 + * @param aMode The audio mode of the radio.
1.201 + */
1.202 + virtual void AudioModeComplete( TFMRadioTunerError aError, TFMRadioAudioMode aMode ) = 0;
1.203 +
1.204 + /**
1.205 + * Notification mechanism provided to inform client that SetAudioMode request has completed.
1.206 + *
1.207 + * @since S60 3.0
1.208 + * @param aError The result of the request indicating whether the operation was
1.209 + * successful or not.
1.210 + */
1.211 + virtual void SetAudioModeComplete( TFMRadioTunerError aError ) = 0;
1.212 +
1.213 + /**
1.214 + * Notification mechanism provided to inform client that MaxSignalStrength request has completed.
1.215 + *
1.216 + * @since S60 3.0
1.217 + * @param aError The result of the request indicating whether the operation was
1.218 + * successful or not.
1.219 + * @param aStrength The maximum possible signal strength of a tuned signal.
1.220 + */
1.221 + virtual void MaxSignalStrengthComplete( TFMRadioTunerError aError, TInt aStrength ) = 0;
1.222 +
1.223 + /**
1.224 + * Notification mechanism provided to inform client that SignalStrength request has completed.
1.225 + *
1.226 + * @since S60 3.0
1.227 + * @param aError The result of the request indicating whether the operation was
1.228 + * successful or not.
1.229 + * @param aStrength The signal strength of the currently tuned frequency.
1.230 + */
1.231 + virtual void SignalStrengthComplete( TFMRadioTunerError aError, TInt aStrength ) = 0;
1.232 +
1.233 + /**
1.234 + * Notification mechanism provided to inform client that Squelch request has completed.
1.235 + *
1.236 + * @since S60 3.0
1.237 + * @param aError The result of the request indicating whether the operation was
1.238 + * successful or not.
1.239 + * @param aEnabled ETrue if squelching is enabled, EFalse if disabled.
1.240 + */
1.241 + virtual void SquelchComplete( TFMRadioTunerError aError, TBool aEnabled ) = 0;
1.242 +
1.243 + /**
1.244 + * Notification mechanism provided to inform client that SetSquelch request has completed.
1.245 + *
1.246 + * @since S60 3.0
1.247 + * @param aError The result of the request indicating whether the operation was
1.248 + * successful or not.
1.249 + */
1.250 + virtual void SetSquelchComplete( TFMRadioTunerError aError ) = 0;
1.251 +
1.252 + /**
1.253 + * Notification mechanism provided to inform client that BufferToBeFilled request has completed.
1.254 + *
1.255 + * @since S60 3.0
1.256 + * @param aBuffer Buffer with data to be played.
1.257 + */
1.258 + virtual void BufferFilled( TDes8& aBuffer ) = 0;
1.259 +
1.260 + /**
1.261 + * Notification mechanism provided to inform that the antenna status has changed.
1.262 + *
1.263 + * @since S60 3.0
1.264 + * @param aAttached ETrue if antenna is attached.
1.265 + */
1.266 + virtual void RadioEventAntennaStatusChange( TBool aAttached ) = 0;
1.267 +
1.268 +#ifdef RD_FM_RADIO_ENHANCEMENTS
1.269 + /**
1.270 + * Notification mechanism indicating tuner control change. When tuner receiver is
1.271 + * forced to be turned off due to hardware conflict such as a FM transmitter, this
1.272 + * event is sent with an error code.
1.273 + * NOTE: Once the tuner control is restored, this event is sent again with KErrNone
1.274 + * and the client can re-issue TunerOn.
1.275 + *
1.276 + * @since S60 3.2
1.277 + * @param aError A standard system error code or FM tuner error (TFMRadioTunerError).
1.278 + */
1.279 + virtual void RadioEventTunerControlChange( TInt aError ) = 0;
1.280 +#endif
1.281 +
1.282 + };
1.283 +
1.284 +/**
1.285 + * This class provides an interface to allow clients to control the FM tuner hardware
1.286 + * present on a device.
1.287 + *
1.288 + * @lib FMRadioTunerControl.lib
1.289 + * @since S60 3.0
1.290 + */
1.291 +class CFMRadioTunerControl : public CBase
1.292 + {
1.293 +public: // Constructors
1.294 +
1.295 + /**
1.296 + * Factory function to create a new instance of the tuner control.
1.297 + *
1.298 + * @since S60 3.0
1.299 + * @param aObserver The observer object
1.300 + * @return A pointer to a new instance of this class
1.301 + */
1.302 + IMPORT_C static CFMRadioTunerControl* NewL( MFMRadioTunerControlObserver& aObserver );
1.303 +
1.304 +public: // New functions
1.305 +
1.306 + /**
1.307 + * Turns on the tuner. The method does not block, but returns immediately
1.308 + * and once the tuner is actually turned on the calling client will receive
1.309 + * a notification via the callback mechanism.
1.310 + *
1.311 + * @since S60 3.0
1.312 + * @param aRange The frequency range the tuner should be set to.
1.313 + * @param aFrequency The frequency (Hz) the tuner should be tuned to.
1.314 + */
1.315 + virtual void TunerOn( TFMRadioFrequencyRange aRange, TInt aFrequency ) = 0;
1.316 +
1.317 + /**
1.318 + * Cancels an outstanding TunerOn request. The method blocks while cancelling
1.319 + * the outstanding request. It is possible that the outstanding request may
1.320 + * complete normally before the cancel request can be processed.
1.321 + *
1.322 + * @since S60 3.0
1.323 + */
1.324 + virtual void CancelTunerOn() = 0;
1.325 +
1.326 + /**
1.327 + * Turns off the tuner. The method does not block, but returns immediately and
1.328 + * once the tuner is actually turned off the calling client will receive a
1.329 + * notification via the callback mechanism.
1.330 + * @since S60 3.0
1.331 + */
1.332 + virtual void TunerOff() = 0;
1.333 +
1.334 + /**
1.335 + * Cancels an outstanding TunerOff request. The method blocks while cancelling
1.336 + * the outstanding request. It is possible that the outstanding request may
1.337 + * complete normally before the cancel request can be processed.
1.338 + *
1.339 + * @since S60 3.0
1.340 + */
1.341 + virtual void CancelTunerOff() = 0;
1.342 +
1.343 + /**
1.344 + * Sets the tuner to the specified frequency range. The method does not block,
1.345 + * but returns immediately and once the frequency range has been set the calling
1.346 + * client will receive a notification via the callback mechanism.
1.347 + *
1.348 + * When not set, default to EFMRadioFrequencyEuroAmerica.
1.349 + *
1.350 + * This method can only be called when tuner is off. Otherwise, KErrInUse will be
1.351 + * returned in callback method.
1.352 + *
1.353 + * @since S60 3.0
1.354 + * @param aRange The frequency range the tuner should be set to.
1.355 + */
1.356 + virtual void SetFrequencyRange( TFMRadioFrequencyRange aRange ) = 0;
1.357 +
1.358 + /**
1.359 + * Cancels an outstanding SetFrequencyRange request. The method blocks while
1.360 + * cancelling the outstanding request. It is possible that the outstanding
1.361 + * request may complete normally before the cancel request can be processed.
1.362 + *
1.363 + * @since S60 3.0
1.364 + */
1.365 + virtual void CancelSetFrequencyRange() = 0;
1.366 +
1.367 + /**
1.368 + * Tunes the tuner to the specified frequency. The method does not block,
1.369 + * but returns immediately and once the tuner has been tuned the calling
1.370 + * client will receive a notification via the callback mechanism.
1.371 + *
1.372 + * @since S60 3.0
1.373 + * @param aFrequency The frequency (Hz) the tuner should be tuned to.
1.374 + */
1.375 + virtual void SetFrequency( TInt aFrequency ) = 0;
1.376 +
1.377 + /**
1.378 + * Cancels an outstanding SetFrequency request. The method blocks while
1.379 + * cancelling the outstanding request. It is possible that the outstanding
1.380 + * request may complete normally before the cancel request can be processed.
1.381 + *
1.382 + * @since S60 3.0
1.383 + */
1.384 + virtual void CancelSetFrequency() = 0;
1.385 +
1.386 + /**
1.387 + * Finds a station, starting at the currently tuned frequency and searches in
1.388 + * the direction specified (i.e. up or down). The method does not block, but
1.389 + * returns immediately and once a station is found the calling client will
1.390 + * receive a notification via the callback mechanism. The station found is
1.391 + * returned in the callback.
1.392 + *
1.393 + * @since S60 3.0
1.394 + * @param aDirection The direction to search in.
1.395 + */
1.396 + virtual void StationSeek( TFMRadioSeekDirection aDirection ) = 0;
1.397 +
1.398 + /**
1.399 + * Cancels an outstanding StationSeek request. The method blocks while
1.400 + * cancelling the outstanding request. It is possible that the outstanding
1.401 + * request may complete normally before the cancel request can be processed.
1.402 + *
1.403 + * @since S60 3.0
1.404 + */
1.405 + virtual void CancelStationSeek() = 0;
1.406 +
1.407 + /**
1.408 + * Retrieves the tuner’s current audio mode (i.e. stereo or mono). The
1.409 + * method does not block, but returns immediately and once the request
1.410 + * is completed the calling client will receive a notification via the
1.411 + * callback mechanism. Audio mode is returned in the callback.
1.412 + *
1.413 + * @since S60 3.0
1.414 + */
1.415 + virtual void AudioMode() = 0;
1.416 +
1.417 + /**
1.418 + * Cancels an outstanding AudioMode request. The method blocks while cancelling
1.419 + * the outstanding request. It is possible that the outstanding request may
1.420 + * complete normally before the cancel request can be processed.
1.421 + *
1.422 + * @since S60 3.0
1.423 + */
1.424 + virtual void CancelAudioMode() = 0;
1.425 +
1.426 + /**
1.427 + * Sets the tuner’s audio mode (i.e. stereo or mono). The method does not block,
1.428 + * but returns immediately and once the audio mode is actually set the calling
1.429 + * client will receive a notification via the callback mechanism.
1.430 + *
1.431 + * When not set, default to EFMRadioAudioStereo.
1.432 + *
1.433 + * @since S60 3.0
1.434 + * @param aMode The audio mode the tuner should be set to.
1.435 + */
1.436 + virtual void SetAudioMode( TFMRadioAudioMode aMode ) = 0;
1.437 +
1.438 + /**
1.439 + * Cancels an outstanding SetAudioMode request. The method blocks while cancelling
1.440 + * the outstanding request. It is possible that the outstanding request may
1.441 + * complete normally before the cancel request can be processed.
1.442 + *
1.443 + * @since S60 3.0
1.444 + */
1.445 + virtual void CancelSetAudioMode() = 0;
1.446 +
1.447 + /**
1.448 + * Retrieves the maximum possible signal strength (RSSI) of a tuned signal.
1.449 + * The method does not block, but returns immediately and once the request
1.450 + * is completed the calling client will receive a notification via the callback
1.451 + * mechanism. Maximun signal strength is returned in the callback.
1.452 + *
1.453 + * @since S60 3.0
1.454 + */
1.455 + virtual void MaxSignalStrength() = 0;
1.456 +
1.457 + /**
1.458 + * Cancels an outstanding MaxSignalStrength request. The method blocks while
1.459 + * cancelling the outstanding request. It is possible that the outstanding
1.460 + * request may complete normally before the cancel request can be processed.
1.461 + *
1.462 + * @since S60 3.0
1.463 + */
1.464 + virtual void CancelMaxSignalStrength() = 0;
1.465 +
1.466 + /**
1.467 + * Retrieves the signal strength (RSSI) of the currently tuned frequency.
1.468 + * The method does not block, but returns immediately and once the request
1.469 + * is completed the calling client will receive a notification via the callback
1.470 + * mechanism. Signal strength is returned in the callback.
1.471 + *
1.472 + * @since S60 3.0
1.473 + */
1.474 + virtual void SignalStrength() = 0;
1.475 +
1.476 + /**
1.477 + * Cancels an outstanding SignalStrength request. The method blocks while
1.478 + * cancelling the outstanding request. It is possible that the outstanding
1.479 + * request may complete normally before the cancel request can be processed.
1.480 + *
1.481 + * @since S60 3.0
1.482 + */
1.483 + virtual void CancelSignalStrength() = 0;
1.484 +
1.485 + /**
1.486 + * Retrieves the current squelching (muting in frequencies without reception)
1.487 + * setting. The method does not block, but returns immediately and once the
1.488 + * request is completed the calling client will receive a notification via
1.489 + * the callback mechanism. Squelch setting is returned in the callback.
1.490 + *
1.491 + * @since S60 3.0
1.492 + */
1.493 + virtual void Squelch() = 0;
1.494 +
1.495 + /**
1.496 + * Cancels an outstanding Squelch request. The method blocks while cancelling
1.497 + * the outstanding request. It is possible that the outstanding request may
1.498 + * complete normally before the cancel request can be processed.
1.499 + *
1.500 + * @since S60 3.0
1.501 + */
1.502 + virtual void CancelSquelch() = 0;
1.503 +
1.504 + /**
1.505 + * Sets the current squelching (muting in frequencies without reception) setting.
1.506 + * The method does not block, but returns immediately and once the squelch setting
1.507 + * is actually set the calling client will receive a notification via the callback
1.508 + * mechanism.
1.509 + *
1.510 + * When not set, default to enabled.
1.511 + *
1.512 + * @since S60 3.0
1.513 + * @param aEnabled ETrue to enable squelching, EFalse to disable it.
1.514 + */
1.515 + virtual void SetSquelch( TBool aEnabled ) = 0;
1.516 +
1.517 + /**
1.518 + * Cancels an outstanding SetSquelch request. The method blocks while cancelling
1.519 + * the outstanding request. It is possible that the outstanding request may
1.520 + * complete normally before the cancel request can be processed.
1.521 + *
1.522 + * @since S60 3.0
1.523 + */
1.524 + virtual void CancelSetSquelch() = 0;
1.525 +
1.526 + /**
1.527 + * This function is called when data is needed for playing. BufferFilled should
1.528 + * be called as quickly as possible after the data is read into buffer or an
1.529 + * underflow situation may occur.
1.530 + *
1.531 + * @since S60 3.0
1.532 + * @param aBuffer Buffer into which data should be read.
1.533 + */
1.534 + virtual void BufferToBeFilled( TDes8& aBuffer ) = 0;
1.535 +
1.536 + /**
1.537 + * Retrieves the audio capabilities supported by the device.
1.538 + *
1.539 + * @since S60 3.0
1.540 + * @return Supported audio capabilities
1.541 + */
1.542 + virtual TFMRadioCapabilities Capabilities() = 0;
1.543 +
1.544 +#ifdef RD_FM_RADIO_ENHANCEMENTS
1.545 + /**
1.546 + * Returns a pointer to RDS control.
1.547 + *
1.548 + * @since S60 3.2
1.549 + * @param aObserver RDS control observer
1.550 + */
1.551 + virtual MRdsControl* RdsControl( MRdsControlObserver& aObserver ) = 0;
1.552 +
1.553 + /**
1.554 + * Gets the current frequency range. It also returns the minimum and maximum frequencies (Hz)
1.555 + * for the returned range. Client should always use the minimum and maximum frequencies returned
1.556 + * by the tuner device, since it may vary slightly depending on the hardware.
1.557 + *
1.558 + * @since S60 3.2
1.559 + * @param aRange On return contains the current frequency range.
1.560 + * @param aMinFreq On return contains the minimum frequency for the current frequency range.
1.561 + * @param aMaxFreq On return contains the maximum frequency for the current frequency range.
1.562 + * @return A standard system error code or FM tuner error (TFMRadioTunerError).
1.563 + */
1.564 + virtual TInt GetFrequencyRange( TFMRadioFrequencyRange& aRange, TInt& aMinFreq, TInt& aMaxFreq ) const = 0;
1.565 +#endif
1.566 +
1.567 + };
1.568 +
1.569 +#endif // C_FMRADIOTUNERCONTROL_H
1.570 +