sl@0: /*
sl@0: * Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).
sl@0: * All rights reserved.
sl@0: * This component and the accompanying materials are made available
sl@0: * under the terms of "Eclipse Public License v1.0"
sl@0: * which accompanies this distribution, and is available
sl@0: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: *
sl@0: * Initial Contributors:
sl@0: * Nokia Corporation - initial contribution.
sl@0: *
sl@0: * Contributors:
sl@0: *
sl@0: * Description: This class is the main interface to FMRadioTunerControl Adaptation API.
sl@0: *
sl@0: */
sl@0:
sl@0:
sl@0:
sl@0: #ifndef C_FMRADIOTUNERCONTROL_H
sl@0: #define C_FMRADIOTUNERCONTROL_H
sl@0:
sl@0: #include <e32base.h>
sl@0:
sl@0: class MRdsControl;
sl@0: class MRdsControlObserver;
sl@0:
sl@0: /**
sl@0: * FM tuner error definitions.
sl@0: * In addition to the standard system error code, the following error codes may
sl@0: * be returned.
sl@0: */
sl@0: typedef TInt TFMRadioTunerError;
sl@0: const TFMRadioTunerError KFMRadioErrHardwareFaulty = -12050;
sl@0: const TFMRadioTunerError KFMRadioErrTuning = -12051;
sl@0: const TFMRadioTunerError KFMRadioErrFrequencyOutOfBandRange = -12052;
sl@0: const TFMRadioTunerError KFMRadioErrFrequencyNotValid = -12053;
sl@0: const TFMRadioTunerError KFMRadioErrNotPermittedInCurrentState = -12054;
sl@0: const TFMRadioTunerError KFMRadioErrDuplicateRequest = -12055;
sl@0: const TFMRadioTunerError KFMRadioErrAntennaNotConnected = -12056;
sl@0: const TFMRadioTunerError KFMRadioErrFmTransmitterActive = -12057;
sl@0:
sl@0:
sl@0: /** FM radio frequency range */
sl@0: enum TFMRadioFrequencyRange
sl@0: {
sl@0: EFMRadioFrequencyEuroAmerica = 0x01, // European and American FM frequency range
sl@0: EFMRadioFrequencyJapan = 0x02, // Japanese FM frequency range
sl@0: EFMRadioFrequencyAmericaNarrow = 0x04 // North American band (87.9-108 Mhz)
sl@0: };
sl@0:
sl@0:
sl@0: /** FM radio seek direction */
sl@0: enum TFMRadioSeekDirection
sl@0: {
sl@0: EFMRadioSeekUp,
sl@0: EFMRadioSeekDown
sl@0: };
sl@0:
sl@0:
sl@0: /** FM radio audio mode */
sl@0: enum TFMRadioAudioMode
sl@0: {
sl@0: EFMRadioAudioMono = 0x01,
sl@0: EFMRadioAudioStereo = 0x02
sl@0: };
sl@0:
sl@0: /** FM radio sample rates */
sl@0: enum TFMRadioSampleRate
sl@0: {
sl@0: EFMRadioSampleRate8000Hz = 0x0001,
sl@0: EFMRadioSampleRate11025Hz = 0x0002,
sl@0: EFMRadioSampleRate12000Hz = 0x0004,
sl@0: EFMRadioSampleRate16000Hz = 0x0008,
sl@0: EFMRadioSampleRate22050Hz = 0x0010,
sl@0: EFMRadioSampleRate24000Hz = 0x0020,
sl@0: EFMRadioSampleRate32000Hz = 0x0040,
sl@0: EFMRadioSampleRate44100Hz = 0x0080,
sl@0: EFMRadioSampleRate48000Hz = 0x0100,
sl@0: EFMRadioSampleRate64000Hz = 0x0200,
sl@0: EFMRadioSampleRate88200Hz = 0x0400,
sl@0: EFMRadioSampleRate96000Hz = 0x0800
sl@0: };
sl@0:
sl@0:
sl@0: /**
sl@0: * The FM Tuner Capabilities class defines the capabilities of the FM tuner on the
sl@0: * device, as retrieved using the function GetCapabilities. Adaptation can utilize this
sl@0: * class to indicate the hardware limitations.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: class TFMRadioCapabilities
sl@0: {
sl@0:
sl@0: #ifdef RD_FM_RADIO_ENHANCEMENTS
sl@0:
sl@0: // Tuner Features bit flags - may be extended in future
sl@0: enum TFMTunerFeatures
sl@0: {
sl@0: // This bit is set if the tuner can be used even when the device is in
sl@0: // offline mode. Some tuner may not allow this due to hw conflict.
sl@0: ETunerAvailableInOfflineMode = 0x01,
sl@0: // This bit is set if the tuner has RDS support.
sl@0: ETunerRdsSupport = 0x02,
sl@0: // This bit is set when the device supports dual tuner, which allows
sl@0: // more extensive RDS feature support.
sl@0: ETunerDualTunerSupport = 0x04
sl@0: };
sl@0: #endif
sl@0:
sl@0: public:
sl@0: // Bitmask using TFMRadioSampleRate
sl@0: TUint iSampleRate;
sl@0: // Bitmask using TFMRadioAudioMode
sl@0: TUint iChannels;
sl@0: // Encodings supported - FourCC
sl@0: TUint32 iEncoding ;
sl@0:
sl@0: // Bitmask using TFMRadioFrequencyRange; used to indicate supported ranges.
sl@0: TUint32 iTunerBands;
sl@0: // Bitmask using TFMTunerFeatures; used to indicate supported tuner features.
sl@0: TUint32 iTunerFunctions;
sl@0: // Reserved for future
sl@0: TUint32 iAdditionalFunctions1;
sl@0: // Reserved for future
sl@0: TUint32 iAdditionalFunctions2;
sl@0:
sl@0: };
sl@0:
sl@0:
sl@0: /**
sl@0: * This class provides the interface class to be implemented by object receiving request
sl@0: * complete notification from FM tuner control. These functions are called once the asynchronous
sl@0: * request completes successfully or with an error.
sl@0: *
sl@0: * In addition, this class provides the interface for receiving events from FM tuner control.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: class MFMRadioTunerControlObserver
sl@0: {
sl@0: public:
sl@0:
sl@0: /**
sl@0: * Notification mechanism provided to inform client that TunerOn request has completed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aError The result of the request indicating whether the operation was
sl@0: * successful or not.
sl@0: */
sl@0: virtual void TunerOnComplete( TFMRadioTunerError aError ) = 0;
sl@0:
sl@0: /**
sl@0: * Notification mechanism provided to inform client that TunerOff request has completed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aError The result of the request indicating whether the operation was
sl@0: * successful or not.
sl@0: */
sl@0: virtual void TunerOffComplete( TFMRadioTunerError aError ) = 0;
sl@0:
sl@0: /**
sl@0: * Notification mechanism provided to inform client that SetFrequencyRange request has completed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aError The result of the request indicating whether the operation was
sl@0: * successful or not.
sl@0: */
sl@0: virtual void SetFrequencyRangeComplete( TFMRadioTunerError aError ) = 0;
sl@0:
sl@0: /**
sl@0: * Notification mechanism provided to inform client that SetFrequency request has completed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aError The result of the request indicating whether the operation was
sl@0: * successful or not.
sl@0: */
sl@0: virtual void SetFrequencyComplete( TFMRadioTunerError aError ) = 0;
sl@0:
sl@0: /**
sl@0: * Notification mechanism provided to inform client that StationSeek request has completed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aError The result of the request indicating whether the operation was
sl@0: * successful or not.
sl@0: * @param aFrequency The frequency(Hz) of the radio station that was found.
sl@0: */
sl@0: virtual void StationSeekComplete( TFMRadioTunerError aError, TInt aFrequency ) = 0;
sl@0:
sl@0: /**
sl@0: * Notification mechanism provided to inform client that AudioMode request has completed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aError The result of the request indicating whether the operation was
sl@0: * successful or not.
sl@0: * @param aMode The audio mode of the radio.
sl@0: */
sl@0: virtual void AudioModeComplete( TFMRadioTunerError aError, TFMRadioAudioMode aMode ) = 0;
sl@0:
sl@0: /**
sl@0: * Notification mechanism provided to inform client that SetAudioMode request has completed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aError The result of the request indicating whether the operation was
sl@0: * successful or not.
sl@0: */
sl@0: virtual void SetAudioModeComplete( TFMRadioTunerError aError ) = 0;
sl@0:
sl@0: /**
sl@0: * Notification mechanism provided to inform client that MaxSignalStrength request has completed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aError The result of the request indicating whether the operation was
sl@0: * successful or not.
sl@0: * @param aStrength The maximum possible signal strength of a tuned signal.
sl@0: */
sl@0: virtual void MaxSignalStrengthComplete( TFMRadioTunerError aError, TInt aStrength ) = 0;
sl@0:
sl@0: /**
sl@0: * Notification mechanism provided to inform client that SignalStrength request has completed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aError The result of the request indicating whether the operation was
sl@0: * successful or not.
sl@0: * @param aStrength The signal strength of the currently tuned frequency.
sl@0: */
sl@0: virtual void SignalStrengthComplete( TFMRadioTunerError aError, TInt aStrength ) = 0;
sl@0:
sl@0: /**
sl@0: * Notification mechanism provided to inform client that Squelch request has completed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aError The result of the request indicating whether the operation was
sl@0: * successful or not.
sl@0: * @param aEnabled ETrue if squelching is enabled, EFalse if disabled.
sl@0: */
sl@0: virtual void SquelchComplete( TFMRadioTunerError aError, TBool aEnabled ) = 0;
sl@0:
sl@0: /**
sl@0: * Notification mechanism provided to inform client that SetSquelch request has completed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aError The result of the request indicating whether the operation was
sl@0: * successful or not.
sl@0: */
sl@0: virtual void SetSquelchComplete( TFMRadioTunerError aError ) = 0;
sl@0:
sl@0: /**
sl@0: * Notification mechanism provided to inform client that BufferToBeFilled request has completed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aBuffer Buffer with data to be played.
sl@0: */
sl@0: virtual void BufferFilled( TDes8& aBuffer ) = 0;
sl@0:
sl@0: /**
sl@0: * Notification mechanism provided to inform that the antenna status has changed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aAttached ETrue if antenna is attached.
sl@0: */
sl@0: virtual void RadioEventAntennaStatusChange( TBool aAttached ) = 0;
sl@0:
sl@0: #ifdef RD_FM_RADIO_ENHANCEMENTS
sl@0: /**
sl@0: * Notification mechanism indicating tuner control change. When tuner receiver is
sl@0: * forced to be turned off due to hardware conflict such as a FM transmitter, this
sl@0: * event is sent with an error code.
sl@0: * NOTE: Once the tuner control is restored, this event is sent again with KErrNone
sl@0: * and the client can re-issue TunerOn.
sl@0: *
sl@0: * @since S60 3.2
sl@0: * @param aError A standard system error code or FM tuner error (TFMRadioTunerError).
sl@0: */
sl@0: virtual void RadioEventTunerControlChange( TInt aError ) = 0;
sl@0: #endif
sl@0:
sl@0: };
sl@0:
sl@0: /**
sl@0: * This class provides an interface to allow clients to control the FM tuner hardware
sl@0: * present on a device.
sl@0: *
sl@0: * @lib FMRadioTunerControl.lib
sl@0: * @since S60 3.0
sl@0: */
sl@0: class CFMRadioTunerControl : public CBase
sl@0: {
sl@0: public: // Constructors
sl@0:
sl@0: /**
sl@0: * Factory function to create a new instance of the tuner control.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aObserver The observer object
sl@0: * @return A pointer to a new instance of this class
sl@0: */
sl@0: IMPORT_C static CFMRadioTunerControl* NewL( MFMRadioTunerControlObserver& aObserver );
sl@0:
sl@0: public: // New functions
sl@0:
sl@0: /**
sl@0: * Turns on the tuner. The method does not block, but returns immediately
sl@0: * and once the tuner is actually turned on the calling client will receive
sl@0: * a notification via the callback mechanism.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aRange The frequency range the tuner should be set to.
sl@0: * @param aFrequency The frequency (Hz) the tuner should be tuned to.
sl@0: */
sl@0: virtual void TunerOn( TFMRadioFrequencyRange aRange, TInt aFrequency ) = 0;
sl@0:
sl@0: /**
sl@0: * Cancels an outstanding TunerOn request. The method blocks while cancelling
sl@0: * the outstanding request. It is possible that the outstanding request may
sl@0: * complete normally before the cancel request can be processed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void CancelTunerOn() = 0;
sl@0:
sl@0: /**
sl@0: * Turns off the tuner. The method does not block, but returns immediately and
sl@0: * once the tuner is actually turned off the calling client will receive a
sl@0: * notification via the callback mechanism.
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void TunerOff() = 0;
sl@0:
sl@0: /**
sl@0: * Cancels an outstanding TunerOff request. The method blocks while cancelling
sl@0: * the outstanding request. It is possible that the outstanding request may
sl@0: * complete normally before the cancel request can be processed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void CancelTunerOff() = 0;
sl@0:
sl@0: /**
sl@0: * Sets the tuner to the specified frequency range. The method does not block,
sl@0: * but returns immediately and once the frequency range has been set the calling
sl@0: * client will receive a notification via the callback mechanism.
sl@0: *
sl@0: * When not set, default to EFMRadioFrequencyEuroAmerica.
sl@0: *
sl@0: * This method can only be called when tuner is off. Otherwise, KErrInUse will be
sl@0: * returned in callback method.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aRange The frequency range the tuner should be set to.
sl@0: */
sl@0: virtual void SetFrequencyRange( TFMRadioFrequencyRange aRange ) = 0;
sl@0:
sl@0: /**
sl@0: * Cancels an outstanding SetFrequencyRange request. The method blocks while
sl@0: * cancelling the outstanding request. It is possible that the outstanding
sl@0: * request may complete normally before the cancel request can be processed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void CancelSetFrequencyRange() = 0;
sl@0:
sl@0: /**
sl@0: * Tunes the tuner to the specified frequency. The method does not block,
sl@0: * but returns immediately and once the tuner has been tuned the calling
sl@0: * client will receive a notification via the callback mechanism.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aFrequency The frequency (Hz) the tuner should be tuned to.
sl@0: */
sl@0: virtual void SetFrequency( TInt aFrequency ) = 0;
sl@0:
sl@0: /**
sl@0: * Cancels an outstanding SetFrequency request. The method blocks while
sl@0: * cancelling the outstanding request. It is possible that the outstanding
sl@0: * request may complete normally before the cancel request can be processed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void CancelSetFrequency() = 0;
sl@0:
sl@0: /**
sl@0: * Finds a station, starting at the currently tuned frequency and searches in
sl@0: * the direction specified (i.e. up or down). The method does not block, but
sl@0: * returns immediately and once a station is found the calling client will
sl@0: * receive a notification via the callback mechanism. The station found is
sl@0: * returned in the callback.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aDirection The direction to search in.
sl@0: */
sl@0: virtual void StationSeek( TFMRadioSeekDirection aDirection ) = 0;
sl@0:
sl@0: /**
sl@0: * Cancels an outstanding StationSeek request. The method blocks while
sl@0: * cancelling the outstanding request. It is possible that the outstanding
sl@0: * request may complete normally before the cancel request can be processed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void CancelStationSeek() = 0;
sl@0:
sl@0: /**
sl@0: * Retrieves the tuner’s current audio mode (i.e. stereo or mono). The
sl@0: * method does not block, but returns immediately and once the request
sl@0: * is completed the calling client will receive a notification via the
sl@0: * callback mechanism. Audio mode is returned in the callback.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void AudioMode() = 0;
sl@0:
sl@0: /**
sl@0: * Cancels an outstanding AudioMode request. The method blocks while cancelling
sl@0: * the outstanding request. It is possible that the outstanding request may
sl@0: * complete normally before the cancel request can be processed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void CancelAudioMode() = 0;
sl@0:
sl@0: /**
sl@0: * Sets the tuner’s audio mode (i.e. stereo or mono). The method does not block,
sl@0: * but returns immediately and once the audio mode is actually set the calling
sl@0: * client will receive a notification via the callback mechanism.
sl@0: *
sl@0: * When not set, default to EFMRadioAudioStereo.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aMode The audio mode the tuner should be set to.
sl@0: */
sl@0: virtual void SetAudioMode( TFMRadioAudioMode aMode ) = 0;
sl@0:
sl@0: /**
sl@0: * Cancels an outstanding SetAudioMode request. The method blocks while cancelling
sl@0: * the outstanding request. It is possible that the outstanding request may
sl@0: * complete normally before the cancel request can be processed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void CancelSetAudioMode() = 0;
sl@0:
sl@0: /**
sl@0: * Retrieves the maximum possible signal strength (RSSI) of a tuned signal.
sl@0: * The method does not block, but returns immediately and once the request
sl@0: * is completed the calling client will receive a notification via the callback
sl@0: * mechanism. Maximun signal strength is returned in the callback.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void MaxSignalStrength() = 0;
sl@0:
sl@0: /**
sl@0: * Cancels an outstanding MaxSignalStrength request. The method blocks while
sl@0: * cancelling the outstanding request. It is possible that the outstanding
sl@0: * request may complete normally before the cancel request can be processed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void CancelMaxSignalStrength() = 0;
sl@0:
sl@0: /**
sl@0: * Retrieves the signal strength (RSSI) of the currently tuned frequency.
sl@0: * The method does not block, but returns immediately and once the request
sl@0: * is completed the calling client will receive a notification via the callback
sl@0: * mechanism. Signal strength is returned in the callback.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void SignalStrength() = 0;
sl@0:
sl@0: /**
sl@0: * Cancels an outstanding SignalStrength request. The method blocks while
sl@0: * cancelling the outstanding request. It is possible that the outstanding
sl@0: * request may complete normally before the cancel request can be processed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void CancelSignalStrength() = 0;
sl@0:
sl@0: /**
sl@0: * Retrieves the current squelching (muting in frequencies without reception)
sl@0: * setting. The method does not block, but returns immediately and once the
sl@0: * request is completed the calling client will receive a notification via
sl@0: * the callback mechanism. Squelch setting is returned in the callback.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void Squelch() = 0;
sl@0:
sl@0: /**
sl@0: * Cancels an outstanding Squelch request. The method blocks while cancelling
sl@0: * the outstanding request. It is possible that the outstanding request may
sl@0: * complete normally before the cancel request can be processed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void CancelSquelch() = 0;
sl@0:
sl@0: /**
sl@0: * Sets the current squelching (muting in frequencies without reception) setting.
sl@0: * The method does not block, but returns immediately and once the squelch setting
sl@0: * is actually set the calling client will receive a notification via the callback
sl@0: * mechanism.
sl@0: *
sl@0: * When not set, default to enabled.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aEnabled ETrue to enable squelching, EFalse to disable it.
sl@0: */
sl@0: virtual void SetSquelch( TBool aEnabled ) = 0;
sl@0:
sl@0: /**
sl@0: * Cancels an outstanding SetSquelch request. The method blocks while cancelling
sl@0: * the outstanding request. It is possible that the outstanding request may
sl@0: * complete normally before the cancel request can be processed.
sl@0: *
sl@0: * @since S60 3.0
sl@0: */
sl@0: virtual void CancelSetSquelch() = 0;
sl@0:
sl@0: /**
sl@0: * This function is called when data is needed for playing. BufferFilled should
sl@0: * be called as quickly as possible after the data is read into buffer or an
sl@0: * underflow situation may occur.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @param aBuffer Buffer into which data should be read.
sl@0: */
sl@0: virtual void BufferToBeFilled( TDes8& aBuffer ) = 0;
sl@0:
sl@0: /**
sl@0: * Retrieves the audio capabilities supported by the device.
sl@0: *
sl@0: * @since S60 3.0
sl@0: * @return Supported audio capabilities
sl@0: */
sl@0: virtual TFMRadioCapabilities Capabilities() = 0;
sl@0:
sl@0: #ifdef RD_FM_RADIO_ENHANCEMENTS
sl@0: /**
sl@0: * Returns a pointer to RDS control.
sl@0: *
sl@0: * @since S60 3.2
sl@0: * @param aObserver RDS control observer
sl@0: */
sl@0: virtual MRdsControl* RdsControl( MRdsControlObserver& aObserver ) = 0;
sl@0:
sl@0: /**
sl@0: * Gets the current frequency range. It also returns the minimum and maximum frequencies (Hz)
sl@0: * for the returned range. Client should always use the minimum and maximum frequencies returned
sl@0: * by the tuner device, since it may vary slightly depending on the hardware.
sl@0: *
sl@0: * @since S60 3.2
sl@0: * @param aRange On return contains the current frequency range.
sl@0: * @param aMinFreq On return contains the minimum frequency for the current frequency range.
sl@0: * @param aMaxFreq On return contains the maximum frequency for the current frequency range.
sl@0: * @return A standard system error code or FM tuner error (TFMRadioTunerError).
sl@0: */
sl@0: virtual TInt GetFrequencyRange( TFMRadioFrequencyRange& aRange, TInt& aMinFreq, TInt& aMaxFreq ) const = 0;
sl@0: #endif
sl@0:
sl@0: };
sl@0:
sl@0: #endif // C_FMRADIOTUNERCONTROL_H
sl@0: