2 * Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: This class is the main interface to FMRadioTunerControl Adaptation API.
20 #ifndef C_FMRADIOTUNERCONTROL_H
21 #define C_FMRADIOTUNERCONTROL_H
26 class MRdsControlObserver;
29 * FM tuner error definitions.
30 * In addition to the standard system error code, the following error codes may
33 typedef TInt TFMRadioTunerError;
34 const TFMRadioTunerError KFMRadioErrHardwareFaulty = -12050;
35 const TFMRadioTunerError KFMRadioErrTuning = -12051;
36 const TFMRadioTunerError KFMRadioErrFrequencyOutOfBandRange = -12052;
37 const TFMRadioTunerError KFMRadioErrFrequencyNotValid = -12053;
38 const TFMRadioTunerError KFMRadioErrNotPermittedInCurrentState = -12054;
39 const TFMRadioTunerError KFMRadioErrDuplicateRequest = -12055;
40 const TFMRadioTunerError KFMRadioErrAntennaNotConnected = -12056;
41 const TFMRadioTunerError KFMRadioErrFmTransmitterActive = -12057;
44 /** FM radio frequency range */
45 enum TFMRadioFrequencyRange
47 EFMRadioFrequencyEuroAmerica = 0x01, // European and American FM frequency range
48 EFMRadioFrequencyJapan = 0x02, // Japanese FM frequency range
49 EFMRadioFrequencyAmericaNarrow = 0x04 // North American band (87.9-108 Mhz)
53 /** FM radio seek direction */
54 enum TFMRadioSeekDirection
61 /** FM radio audio mode */
62 enum TFMRadioAudioMode
64 EFMRadioAudioMono = 0x01,
65 EFMRadioAudioStereo = 0x02
68 /** FM radio sample rates */
69 enum TFMRadioSampleRate
71 EFMRadioSampleRate8000Hz = 0x0001,
72 EFMRadioSampleRate11025Hz = 0x0002,
73 EFMRadioSampleRate12000Hz = 0x0004,
74 EFMRadioSampleRate16000Hz = 0x0008,
75 EFMRadioSampleRate22050Hz = 0x0010,
76 EFMRadioSampleRate24000Hz = 0x0020,
77 EFMRadioSampleRate32000Hz = 0x0040,
78 EFMRadioSampleRate44100Hz = 0x0080,
79 EFMRadioSampleRate48000Hz = 0x0100,
80 EFMRadioSampleRate64000Hz = 0x0200,
81 EFMRadioSampleRate88200Hz = 0x0400,
82 EFMRadioSampleRate96000Hz = 0x0800
87 * The FM Tuner Capabilities class defines the capabilities of the FM tuner on the
88 * device, as retrieved using the function GetCapabilities. Adaptation can utilize this
89 * class to indicate the hardware limitations.
93 class TFMRadioCapabilities
96 #ifdef RD_FM_RADIO_ENHANCEMENTS
98 // Tuner Features bit flags - may be extended in future
101 // This bit is set if the tuner can be used even when the device is in
102 // offline mode. Some tuner may not allow this due to hw conflict.
103 ETunerAvailableInOfflineMode = 0x01,
104 // This bit is set if the tuner has RDS support.
105 ETunerRdsSupport = 0x02,
106 // This bit is set when the device supports dual tuner, which allows
107 // more extensive RDS feature support.
108 ETunerDualTunerSupport = 0x04
113 // Bitmask using TFMRadioSampleRate
115 // Bitmask using TFMRadioAudioMode
117 // Encodings supported - FourCC
120 // Bitmask using TFMRadioFrequencyRange; used to indicate supported ranges.
122 // Bitmask using TFMTunerFeatures; used to indicate supported tuner features.
123 TUint32 iTunerFunctions;
124 // Reserved for future
125 TUint32 iAdditionalFunctions1;
126 // Reserved for future
127 TUint32 iAdditionalFunctions2;
133 * This class provides the interface class to be implemented by object receiving request
134 * complete notification from FM tuner control. These functions are called once the asynchronous
135 * request completes successfully or with an error.
137 * In addition, this class provides the interface for receiving events from FM tuner control.
141 class MFMRadioTunerControlObserver
146 * Notification mechanism provided to inform client that TunerOn request has completed.
149 * @param aError The result of the request indicating whether the operation was
152 virtual void TunerOnComplete( TFMRadioTunerError aError ) = 0;
155 * Notification mechanism provided to inform client that TunerOff request has completed.
158 * @param aError The result of the request indicating whether the operation was
161 virtual void TunerOffComplete( TFMRadioTunerError aError ) = 0;
164 * Notification mechanism provided to inform client that SetFrequencyRange request has completed.
167 * @param aError The result of the request indicating whether the operation was
170 virtual void SetFrequencyRangeComplete( TFMRadioTunerError aError ) = 0;
173 * Notification mechanism provided to inform client that SetFrequency request has completed.
176 * @param aError The result of the request indicating whether the operation was
179 virtual void SetFrequencyComplete( TFMRadioTunerError aError ) = 0;
182 * Notification mechanism provided to inform client that StationSeek request has completed.
185 * @param aError The result of the request indicating whether the operation was
187 * @param aFrequency The frequency(Hz) of the radio station that was found.
189 virtual void StationSeekComplete( TFMRadioTunerError aError, TInt aFrequency ) = 0;
192 * Notification mechanism provided to inform client that AudioMode request has completed.
195 * @param aError The result of the request indicating whether the operation was
197 * @param aMode The audio mode of the radio.
199 virtual void AudioModeComplete( TFMRadioTunerError aError, TFMRadioAudioMode aMode ) = 0;
202 * Notification mechanism provided to inform client that SetAudioMode request has completed.
205 * @param aError The result of the request indicating whether the operation was
208 virtual void SetAudioModeComplete( TFMRadioTunerError aError ) = 0;
211 * Notification mechanism provided to inform client that MaxSignalStrength request has completed.
214 * @param aError The result of the request indicating whether the operation was
216 * @param aStrength The maximum possible signal strength of a tuned signal.
218 virtual void MaxSignalStrengthComplete( TFMRadioTunerError aError, TInt aStrength ) = 0;
221 * Notification mechanism provided to inform client that SignalStrength request has completed.
224 * @param aError The result of the request indicating whether the operation was
226 * @param aStrength The signal strength of the currently tuned frequency.
228 virtual void SignalStrengthComplete( TFMRadioTunerError aError, TInt aStrength ) = 0;
231 * Notification mechanism provided to inform client that Squelch request has completed.
234 * @param aError The result of the request indicating whether the operation was
236 * @param aEnabled ETrue if squelching is enabled, EFalse if disabled.
238 virtual void SquelchComplete( TFMRadioTunerError aError, TBool aEnabled ) = 0;
241 * Notification mechanism provided to inform client that SetSquelch request has completed.
244 * @param aError The result of the request indicating whether the operation was
247 virtual void SetSquelchComplete( TFMRadioTunerError aError ) = 0;
250 * Notification mechanism provided to inform client that BufferToBeFilled request has completed.
253 * @param aBuffer Buffer with data to be played.
255 virtual void BufferFilled( TDes8& aBuffer ) = 0;
258 * Notification mechanism provided to inform that the antenna status has changed.
261 * @param aAttached ETrue if antenna is attached.
263 virtual void RadioEventAntennaStatusChange( TBool aAttached ) = 0;
265 #ifdef RD_FM_RADIO_ENHANCEMENTS
267 * Notification mechanism indicating tuner control change. When tuner receiver is
268 * forced to be turned off due to hardware conflict such as a FM transmitter, this
269 * event is sent with an error code.
270 * NOTE: Once the tuner control is restored, this event is sent again with KErrNone
271 * and the client can re-issue TunerOn.
274 * @param aError A standard system error code or FM tuner error (TFMRadioTunerError).
276 virtual void RadioEventTunerControlChange( TInt aError ) = 0;
282 * This class provides an interface to allow clients to control the FM tuner hardware
283 * present on a device.
285 * @lib FMRadioTunerControl.lib
288 class CFMRadioTunerControl : public CBase
290 public: // Constructors
293 * Factory function to create a new instance of the tuner control.
296 * @param aObserver The observer object
297 * @return A pointer to a new instance of this class
299 IMPORT_C static CFMRadioTunerControl* NewL( MFMRadioTunerControlObserver& aObserver );
301 public: // New functions
304 * Turns on the tuner. The method does not block, but returns immediately
305 * and once the tuner is actually turned on the calling client will receive
306 * a notification via the callback mechanism.
309 * @param aRange The frequency range the tuner should be set to.
310 * @param aFrequency The frequency (Hz) the tuner should be tuned to.
312 virtual void TunerOn( TFMRadioFrequencyRange aRange, TInt aFrequency ) = 0;
315 * Cancels an outstanding TunerOn request. The method blocks while cancelling
316 * the outstanding request. It is possible that the outstanding request may
317 * complete normally before the cancel request can be processed.
321 virtual void CancelTunerOn() = 0;
324 * Turns off the tuner. The method does not block, but returns immediately and
325 * once the tuner is actually turned off the calling client will receive a
326 * notification via the callback mechanism.
329 virtual void TunerOff() = 0;
332 * Cancels an outstanding TunerOff request. The method blocks while cancelling
333 * the outstanding request. It is possible that the outstanding request may
334 * complete normally before the cancel request can be processed.
338 virtual void CancelTunerOff() = 0;
341 * Sets the tuner to the specified frequency range. The method does not block,
342 * but returns immediately and once the frequency range has been set the calling
343 * client will receive a notification via the callback mechanism.
345 * When not set, default to EFMRadioFrequencyEuroAmerica.
347 * This method can only be called when tuner is off. Otherwise, KErrInUse will be
348 * returned in callback method.
351 * @param aRange The frequency range the tuner should be set to.
353 virtual void SetFrequencyRange( TFMRadioFrequencyRange aRange ) = 0;
356 * Cancels an outstanding SetFrequencyRange request. The method blocks while
357 * cancelling the outstanding request. It is possible that the outstanding
358 * request may complete normally before the cancel request can be processed.
362 virtual void CancelSetFrequencyRange() = 0;
365 * Tunes the tuner to the specified frequency. The method does not block,
366 * but returns immediately and once the tuner has been tuned the calling
367 * client will receive a notification via the callback mechanism.
370 * @param aFrequency The frequency (Hz) the tuner should be tuned to.
372 virtual void SetFrequency( TInt aFrequency ) = 0;
375 * Cancels an outstanding SetFrequency request. The method blocks while
376 * cancelling the outstanding request. It is possible that the outstanding
377 * request may complete normally before the cancel request can be processed.
381 virtual void CancelSetFrequency() = 0;
384 * Finds a station, starting at the currently tuned frequency and searches in
385 * the direction specified (i.e. up or down). The method does not block, but
386 * returns immediately and once a station is found the calling client will
387 * receive a notification via the callback mechanism. The station found is
388 * returned in the callback.
391 * @param aDirection The direction to search in.
393 virtual void StationSeek( TFMRadioSeekDirection aDirection ) = 0;
396 * Cancels an outstanding StationSeek request. The method blocks while
397 * cancelling the outstanding request. It is possible that the outstanding
398 * request may complete normally before the cancel request can be processed.
402 virtual void CancelStationSeek() = 0;
405 * Retrieves the tuner’s current audio mode (i.e. stereo or mono). The
406 * method does not block, but returns immediately and once the request
407 * is completed the calling client will receive a notification via the
408 * callback mechanism. Audio mode is returned in the callback.
412 virtual void AudioMode() = 0;
415 * Cancels an outstanding AudioMode request. The method blocks while cancelling
416 * the outstanding request. It is possible that the outstanding request may
417 * complete normally before the cancel request can be processed.
421 virtual void CancelAudioMode() = 0;
424 * Sets the tuner’s audio mode (i.e. stereo or mono). The method does not block,
425 * but returns immediately and once the audio mode is actually set the calling
426 * client will receive a notification via the callback mechanism.
428 * When not set, default to EFMRadioAudioStereo.
431 * @param aMode The audio mode the tuner should be set to.
433 virtual void SetAudioMode( TFMRadioAudioMode aMode ) = 0;
436 * Cancels an outstanding SetAudioMode request. The method blocks while cancelling
437 * the outstanding request. It is possible that the outstanding request may
438 * complete normally before the cancel request can be processed.
442 virtual void CancelSetAudioMode() = 0;
445 * Retrieves the maximum possible signal strength (RSSI) of a tuned signal.
446 * The method does not block, but returns immediately and once the request
447 * is completed the calling client will receive a notification via the callback
448 * mechanism. Maximun signal strength is returned in the callback.
452 virtual void MaxSignalStrength() = 0;
455 * Cancels an outstanding MaxSignalStrength request. The method blocks while
456 * cancelling the outstanding request. It is possible that the outstanding
457 * request may complete normally before the cancel request can be processed.
461 virtual void CancelMaxSignalStrength() = 0;
464 * Retrieves the signal strength (RSSI) of the currently tuned frequency.
465 * The method does not block, but returns immediately and once the request
466 * is completed the calling client will receive a notification via the callback
467 * mechanism. Signal strength is returned in the callback.
471 virtual void SignalStrength() = 0;
474 * Cancels an outstanding SignalStrength request. The method blocks while
475 * cancelling the outstanding request. It is possible that the outstanding
476 * request may complete normally before the cancel request can be processed.
480 virtual void CancelSignalStrength() = 0;
483 * Retrieves the current squelching (muting in frequencies without reception)
484 * setting. The method does not block, but returns immediately and once the
485 * request is completed the calling client will receive a notification via
486 * the callback mechanism. Squelch setting is returned in the callback.
490 virtual void Squelch() = 0;
493 * Cancels an outstanding Squelch request. The method blocks while cancelling
494 * the outstanding request. It is possible that the outstanding request may
495 * complete normally before the cancel request can be processed.
499 virtual void CancelSquelch() = 0;
502 * Sets the current squelching (muting in frequencies without reception) setting.
503 * The method does not block, but returns immediately and once the squelch setting
504 * is actually set the calling client will receive a notification via the callback
507 * When not set, default to enabled.
510 * @param aEnabled ETrue to enable squelching, EFalse to disable it.
512 virtual void SetSquelch( TBool aEnabled ) = 0;
515 * Cancels an outstanding SetSquelch request. The method blocks while cancelling
516 * the outstanding request. It is possible that the outstanding request may
517 * complete normally before the cancel request can be processed.
521 virtual void CancelSetSquelch() = 0;
524 * This function is called when data is needed for playing. BufferFilled should
525 * be called as quickly as possible after the data is read into buffer or an
526 * underflow situation may occur.
529 * @param aBuffer Buffer into which data should be read.
531 virtual void BufferToBeFilled( TDes8& aBuffer ) = 0;
534 * Retrieves the audio capabilities supported by the device.
537 * @return Supported audio capabilities
539 virtual TFMRadioCapabilities Capabilities() = 0;
541 #ifdef RD_FM_RADIO_ENHANCEMENTS
543 * Returns a pointer to RDS control.
546 * @param aObserver RDS control observer
548 virtual MRdsControl* RdsControl( MRdsControlObserver& aObserver ) = 0;
551 * Gets the current frequency range. It also returns the minimum and maximum frequencies (Hz)
552 * for the returned range. Client should always use the minimum and maximum frequencies returned
553 * by the tuner device, since it may vary slightly depending on the hardware.
556 * @param aRange On return contains the current frequency range.
557 * @param aMinFreq On return contains the minimum frequency for the current frequency range.
558 * @param aMaxFreq On return contains the maximum frequency for the current frequency range.
559 * @return A standard system error code or FM tuner error (TFMRadioTunerError).
561 virtual TInt GetFrequencyRange( TFMRadioFrequencyRange& aRange, TInt& aMinFreq, TInt& aMaxFreq ) const = 0;
566 #endif // C_FMRADIOTUNERCONTROL_H