--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mmmw_plat/radio_utilities_api/inc/RadioFmTunerUtility.h Tue Feb 02 01:08:46 2010 +0200
@@ -0,0 +1,454 @@
+/*
+* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: This class provides an interface for controlling the FM tuner
+* controls such as tuning or seeking frequencies. In addition an
+* observer class is provided for receiving completion notification
+* for asynchronous requests made to FM tuner control and for receiving
+* events notifying changes in the tuner such as frequency change
+* (caused by other clients or RDS, if supported), loss of tuner
+* control,etc.
+*
+*
+*/
+
+
+
+#ifndef C_RADIOFMTUNERUTILITY_H
+#define C_RADIOFMTUNERUTILITY_H
+
+#include <RadioUtility.h>
+
+class RRadioSession;
+
+/**
+ * FM tuner error definitions.
+ * In addition to the standard system error code, the following error codes may
+ * be returned.
+ */
+typedef TInt TFmRadioTunerError;
+const TFmRadioTunerError KFmRadioErrHardwareFaulty = -12050;
+const TFmRadioTunerError KFmRadioErrTuning = -12051;
+const TFmRadioTunerError KFmRadioErrFrequencyOutOfBandRange = -12052;
+const TFmRadioTunerError KFmRadioErrFrequencyNotValid = -12053;
+const TFmRadioTunerError KFmRadioErrNotPermittedInCurrentState = -12054;
+const TFmRadioTunerError KFmRadioErrDuplicateRequest = -12055;
+const TFmRadioTunerError KFmRadioErrAntennaNotConnected = -12056;
+const TFmRadioTunerError KFmRadioErrFmTransmitterActive = -12057;
+const TFmRadioTunerError KFmRadioErrOfflineMode = -12058;
+
+
+/** FM radio frequency range */
+enum TFmRadioFrequencyRange
+ {
+ EFmRangeEuroAmerica = 0x01, // European and American FM frequency range
+ EFmRangeJapan = 0x02 // Japanese FM frequency range
+ };
+
+
+/**
+ * The FM Tuner Capabilities class defines the capabilities of the FM tuner on the
+ * device, as retrieved using the function GetCapabilities.
+ *
+ * @since S60 3.2
+ */
+class TFmTunerCapabilities
+ {
+public:
+ // Tuner Features bit flags - may be extended in future
+ enum TFmTunerFeatures
+ {
+ // This bit is set if the tuner can be used even when the device is in
+ // offline mode. Some tuner may not allow this due to hw conflict.
+ ETunerAvailableInOfflineMode = 0x01,
+ // This bit is set if the tuner has RDS support.
+ ETunerRdsSupport = 0x02,
+ // This bit is set when the device supports dual tuner, which allows
+ // more extensive RDS feature support.
+ ETunerDualTunerSupport = 0x04
+ };
+
+public:
+ // Bitfield (as defined by TFmRadioFrequencyRange) with the bits of the supported frequency range
+ TUint32 iTunerBands;
+ // Bitfield (as defined by TFmTunerFunctions) with the bits of the supported functions set
+ TUint32 iTunerFunctions;
+ // Reserved for future
+ TUint32 iAdditionalFunctions1;
+ // Reserved for future
+ TUint32 iAdditionalFunctions2;
+ };
+
+
+/**
+ * This class provides the interface class to be implemented by object receiving request
+ * complete notification from FM tuner control. These functions are called once the asynchronous
+ * request completes successfully or with an error.
+ *
+ * In addition, this class provides the interface for receiving events from FM tuner control.
+ *
+ * @since S60 3.2
+ */
+class MRadioFmTunerObserver
+ {
+public:
+
+ /**
+ * Request for tuner control complete event. This event is asynchronous and is received after
+ * a call to CRadioFmTunerUtility::RequestTunerControl.
+ *
+ * If this function returns KErrNone, control of the tuner has been granted.
+ *
+ * If this function returns KFMRadioErrAntennaNotConnected, KFMRadioErrFmTransmitterActive,
+ * or KFMRadioErrOfflineMode, client will receive the following events respectively:
+ * MrfteoAntennaStatusChanged, MrfteoFmTransmitterStatusChanged, MrfteoOfflineModeStatusChanged.
+ * At this time, client must re-issue RequestTunerControl. Note that functions that require
+ * control of the tuner (such as Tune) will return one of the above error codes.
+ *
+ * In case of multiple clients accessing the tuner, or when RequestTunerControl is re-issued,
+ * this function returns KErrAlreadyExists.
+ *
+ * @since S60 3.2
+ * @param aError A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ virtual void MrftoRequestTunerControlComplete( TInt aError ) = 0;
+
+ /**
+ * Set frequency range complete event. This event is asynchronous and is received after
+ * a call to CRadioFmTunerUtility::SetFrequencyRange.
+ *
+ * @since S60 3.2
+ * @param aError A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ virtual void MrftoSetFrequencyRangeComplete( TInt aError ) = 0;
+
+ /**
+ * Set frequency complete event. This event is asynchronous and is received after a call to
+ * CRadioFmTunerUtility::SetFrequency.
+ *
+ * @since S60 3.2
+ * @param aError A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ virtual void MrftoSetFrequencyComplete( TInt aError ) = 0;
+
+ /**
+ * Station seek complete event. This event is asynchronous and is received after a call to
+ * CRadioFmTunerUtility::StationSeek.
+ *
+ * @since S60 3.2
+ * @param aError A standard system error code or FM tuner error (TFmRadioTunerError).
+ * @param aFrequency The frequency(Hz) of the radio station that was found.
+ */
+ virtual void MrftoStationSeekComplete( TInt aError, TInt aFrequency ) = 0;
+
+ /**
+ * Called when FM Transmitter status changes (if one is present in the device). Tuner receiver
+ * is forced to be turned off due to hardware conflicts when FM transmitter is activated.
+ *
+ * @since S60 3.2
+ * @param aActive ETrue if FM transmitter is active; EFalse otherwise.
+ */
+ virtual void MrftoFmTransmitterStatusChange( TBool aActive ) = 0;
+
+ /**
+ * Called when antenna status changes.
+ *
+ * @since S60 3.2
+ * @param aAttached ETrue if antenna is attached; EFalse otherwise.
+ */
+ virtual void MrftoAntennaStatusChange( TBool aAttached ) = 0;
+
+ /**
+ * Called when offline mode status changes.
+ * @since S60 3.2
+ *
+ ** @param aAttached ETrue if offline mode is enabled; EFalse otherwise.
+ */
+ virtual void MrftoOfflineModeStatusChange( TBool aOfflineMode ) = 0;
+
+ /**
+ * Called when the frequency range changes. This may be caused by other applications.
+ *
+ * @since S60 3.2
+ * @param aNewRange New frequency range.
+ */
+ virtual void MrftoFrequencyRangeChange( TFmRadioFrequencyRange aNewRange ) = 0;
+
+ /**
+ * Called when the tuned frequency changes. This may be caused by other
+ * applications or RDS if AF/TA is enabled.
+ *
+ * @since S60 3.2
+ * @param aNewFrequency The new tuned frequency(Hz).
+ */
+ virtual void MrftoFrequencyChange( TInt aNewFrequency ) = 0;
+
+ /**
+ * Called when the forced mono status change. This may be caused by other applications.
+ *
+ * @since S60 3.2
+ * @param aForcedMono ETrue if forced mono mode is enabled; EFalse otherwise.
+ */
+ virtual void MrftoForcedMonoChange( TBool aForcedMono ) = 0;
+
+ /**
+ * Called when the squelch (muting the frequencies without broadcast) status change.
+ * This may be caused by other applications.
+ *
+ * @since S60 3.2
+ * @param aSquelch ETrue if squelch is enabled; EFalse otherwise.
+ */
+ virtual void MrftoSquelchChange( TBool aSquelch ) = 0;
+ };
+
+/**
+ * This class provides an interface to allow clients to control the FM tuner hardware
+ * present on a device.
+ *
+ * @lib RadioUtility.lib
+ * @since S60 3.2
+ */
+class CRadioFmTunerUtility : public CBase
+ {
+ friend class CRadioUtility::CBody;
+
+public:
+
+ /**
+ * Asynchronous request to get control of the FM tuner. This method call must be made before
+ * any other method calls in this API.
+ * User must be ready to receive callback method MrftoRequestTunerControlComplete. Control
+ * to the tuner must be granted before any functions that require control of the tuner
+ * (such as SetFrequency) can be made.
+ * The only API call that doesn't require tuner control to be granted is EnableTunerInOfflineMode().
+ *
+ * @since S60 3.2
+ * @see MRadioFmTunerObserver::MrftoRequestTunerControlComplete
+ */
+ IMPORT_C void RequestTunerControl();
+
+ /**
+ * Close the tuner and free all memory allocated. Any ongoing playing activity will be stopped,
+ * control of the tuner will be released, and the hardware will be powered down if no other
+ * clients need it.
+ *
+ * @since S60 3.2
+ */
+ IMPORT_C void Close();
+
+ /**
+ * Get the capabilities of the FM tuner on the device.
+ *
+ * @since S60 3.2
+ * @param aCaps The capabilities object to fill
+ * @return A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ IMPORT_C TInt GetCapabilities( TFmTunerCapabilities& aCaps );
+
+ /**
+ * Enable tuner functions when the device is in offline mode. Client
+ * should first check the capabilities to see if this feature is supported.
+ *
+ * When requested prior to requesting tuner control, this function will succeed with
+ * KErrNone, however, tuner will only be enabled in offline mode if supported by the
+ * tuner device.
+ *
+ * Tuner functions are disabled in offline mode by default.
+ *
+ * @since S60 3.2
+ * @param aEnable ETrue to enable tuner functions in offline mode, EFalse to disable.
+ * @return A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ IMPORT_C TInt EnableTunerInOfflineMode( TBool aEnable );
+
+ /**
+ * Asynchronous request to set the frequency range. User must be ready to receive
+ * callback method MrftoSetFrequencyRangeComplete. If not set, it will be defaulted
+ * to EFmRangeEuroAmerica.
+ *
+ * @since S60 3.2
+ * @param aRange Frequency range
+ */
+ IMPORT_C void SetFrequencyRange( TFmRadioFrequencyRange aRange );
+
+ /**
+ * Cancels an ongoing set frequency range operation, as initiated by a call to
+ * SetFrequencyRange. The usual callback will not occur if this has been called.
+ *
+ * Has not effect if no set frequency range operation is ongoing.
+ *
+ * @since S60 3.2
+ */
+ IMPORT_C void CancelSetFrequencyRange();
+
+ /**
+ * Get the current frequency range. It also returns the minimum and maximum frequencies (Hz)
+ * for the returned range. Client should always use the minimum and maximum frequencies returned
+ * by the tuner device, since it may vary slightly depending on the hardware.
+ *
+ * @since S60 3.2
+ * @param aRange On return contains the current frequency range.
+ * @param aMinFreq On return contains the minimum frequency for the current frequency range.
+ * @param aMaxFreq On return contains the maximum frequency for the current frequency range.
+ * @return A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ IMPORT_C TInt GetFrequencyRange( TFmRadioFrequencyRange& aRange, TInt& aMinFreq, TInt& aMaxFreq ) const;
+
+ /**
+ * Asynchronous request to tune the tuner to the speficied frequency (Hz). User must be
+ * ready to receive callback method MrftoTuneComplete.
+ *
+ * @since S60 3.2
+ * @param aFrequency The frequency to tune to
+ * @see MRadioFmTunerObserver::MrftoTuneComplete
+ */
+ IMPORT_C void SetFrequency( TInt aFrequency );
+
+ /**
+ * Cancels an ongoing tune operation, as initiated by a call to Tune.
+ * The usual callback will not occur if this has been called.
+ *
+ * Has not effect if no tune operation is ongoing.
+ *
+ * @since S60 3.2
+ */
+ IMPORT_C void CancelSetFrequency();
+
+ /**
+ * Get the currently tuned frequency.
+ *
+ * @since S60 3.2
+ * @param aFrequency On return contains the current frequency (Hz).
+ * @return A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ IMPORT_C TInt GetFrequency( TInt& aFrequency ) const;
+
+ /**
+ * Asynchronous request to find a radio station, starting from the currently tuned frequency and
+ * searching in the direction specified (i.e. up or down). User must be ready to receive callback
+ * method MrftoSeekComplete. The station found is returned in the callback.
+ *
+ * If no station is found after a complete loop, seek will stop and return KErrNotfound
+ * in the callback method and frequency will not change.
+ *
+ * @since S60 3.2
+ * @param aUpwards The direction to search in. Searches upwards if set to ETrue.
+ * @see MRadioFmTunerObserver::MrftoStationSeekComplete
+ */
+ IMPORT_C void StationSeek( TBool aUpwards );
+
+ /**
+ * Cancels an ongoing station seek operation, as initiated by a call to StationSeek.
+ * The usual callback will not occur if this has been called.
+ *
+ * Has not effect if no station seek operation is ongoing.
+ *
+ * @since S60 3.2
+ */
+ IMPORT_C void CancelStationSeek();
+
+ /**
+ * Get the signal strenth of the currently tuned frequency.
+ *
+ * @since S60 3.2
+ * @param aSignalStrength On return contains the signal strength.
+ * @return A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ IMPORT_C TInt GetSignalStrength( TInt& aSignalStrength ) const;
+
+ /**
+ * Get the maximum possible signal strength of a tuned frequency.
+ *
+ * @since S60 3.2
+ * @param aMaxSignalStrength On return contains the maximum signal strength.
+ * @return A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ IMPORT_C TInt GetMaxSignalStrength( TInt& aMaxSignalStrength ) const;
+
+ /**
+ * Get the current frequency's stereo mode (stereo or mono).
+ *
+ * @since S60 3.2
+ * @param aStereo On return, will be ETrue if a stereo signal is currently being received.
+ * @return A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ IMPORT_C TInt GetStereoMode( TBool& aStereo ) const;
+
+ /**
+ * Indicates whether the reception should be forced into monophonic mode.
+ *
+ * @since S60 3.2
+ * @param aMono If ETrue, all reception will be in mono mode even if a stereo signal
+ * is available. If EFalse, a stereo signal will be received when possible.
+ * @return A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ IMPORT_C TInt ForceMonoReception( TBool aForcedMono );
+
+ /**
+ * Find out whether reception is forced into monophonic mode or not.
+ *
+ * @since S60 3.2
+ * @param aForcedMono On return, will be ETrue if a forced mono is currently enabled.
+ * @return A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ IMPORT_C TInt GetForcedMonoReception( TBool& aForcedMono ) const;
+
+ /**
+ * Set the current squleching (muting in frequencies without reception) setting.
+ * Squelching is enabled by default.
+ *
+ * @since S60 3.2
+ * @param aEnabled ETrue to enable squelching, EFalse to disable it.
+ * @return A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ IMPORT_C TInt SetSquelch( TBool aSquelch );
+
+ /**
+ * Get the current squelching (muting in frequencies without reception) setting.
+ *
+ * @since S60 3.2
+ * @param aSquelch On return, will be ETrue if a squelching is currently enabled.
+ * @return A standard system error code or FM tuner error (TFmRadioTunerError).
+ */
+ IMPORT_C TInt GetSquelch( TBool& aSquelch ) const;
+
+private:
+
+ /**
+ * Factory function to create a new instance of the FM tuner.
+ *
+ * @since S60 3.2
+ * @param aRadioSession Reference to radio session
+ * @param aObserver The observer object for receiving async completion callbacks
+ * @return A new FM tuner utility object.
+ */
+ static CRadioFmTunerUtility* NewL( RRadioSession& aRadioSession, MRadioFmTunerObserver& aObserver );
+
+ virtual ~CRadioFmTunerUtility();
+
+ CRadioFmTunerUtility();
+
+ void ConstructL();
+
+private: // data
+
+ class CBody;
+
+ /**
+ * FM tuner utility implementation body
+ * Own.
+ */
+ CBody* iBody;
+ };
+
+#endif // C_RADIOFMTUNERUTILITY_H