diff -r 000000000000 -r 4e1aa6a622a0 resourceinterfaces/fmtransmittercontrol/inc/HWRMFmTx.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/resourceinterfaces/fmtransmittercontrol/inc/HWRMFmTx.h Tue Feb 02 00:53:00 2010 +0200 @@ -0,0 +1,469 @@ +/* +* Copyright (c) 2006-2009 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: +* +*/ + + + +#ifndef HWRMFMTX_H +#define HWRMFMTX_H + +// INCLUDES + +#include +#include + +// FUNCTION PROTOTYPES + +// FORWARD DECLARATIONS +class MHWRMFmTxObserver; + +// CLASS DECLARATIONS + +/** +* Base class of FM Tx Client API of HWRM +* +* The HWRM FM Tx API provides the ability to control the device's FM radio transmitter +* +* @publishedPartner +* @deprecated +*/ +class CHWRMFmTx : public CBase + { + public: // Constructors + + /** + * Two-phased constructor for implementation class. + * Use this method for creating a FM Tx client with callbacks. + * + * @param aCallback Pointer to callback instance (NULL if callbacks are + * not required). + * @return New CHWRMFmTx implementing instance. + * @exception KErrNotSupported Device doesn't support FM Tx feature. + * KErrNoMemory if there is a memory allocation failure. + */ + IMPORT_C static CHWRMFmTx* NewL(MHWRMFmTxObserver* aCallback = NULL); + + /** + * Two-phased constructor for implementation class. + * Use this method for creating a FM Tx client with callbacks. + * Leaves instance on cleanup stack. + * + * @param aCallback Pointer to callback instance (NULL if callbacks are + * not required). + * @return New CHWRMFmTx implementing instance. + * @exception KErrNotSupported Device doesn't support FM Tx feature. + * KErrNoMemory if there is a memory allocation failure. + */ + IMPORT_C static CHWRMFmTx* NewLC(MHWRMFmTxObserver* aCallback = NULL); + + public: // New functions + + /** + * Reserves FM Tx resource exclusively for this client. + * A higher priority client may cause lower priority client reservation to be + * temporarily suspended. If FM Tx is already reserved by a higher or equal + * priority application, reserving will still succeed, but reservation is + * immediately suspended. + * The suspended client will not get any notification about suspension. Any + * ongoing commands will be cancelled, when a client’s reservation is suspended. + * Only reservation and status query commands may be issued, in the suspended + * state. + * + * @param aForceNoCCoeEnv If EFalse, then reservation requires that this + * client is on the foreground at the time of reservation and FM Tx + * will be automatically released and re-reserved based on + * background/foreground status of the this client. This also implies + * that CCoeEnv::Static() != NULL is required. + * If ETrue, the client will not require CCoeEnv to be present nor + * does it automatically reserve/release FM Tx. + * Only trusted clients are allowed to set this flag to ETrue. + * + * @exception KErrAccessDenied if aForceNoCCoeEnv is ETrue and client is not + * trusted. + * KErrBadHandle if aForceNoCCoeEnv is EFalse and no CCoeEnv present. + * KErrNotReady if trying to reserve while on background and + * aForceNoCCoeEnv is EFalse. + * KErrNoMemory if there is a memory allocation failure. + */ + virtual void ReserveL(TBool aForceNoCCoeEnv)=0; + + /** + * Releases FM Tx resource, if it was previously reserved for this client. + * If this client has not reserved FM Tx, then this method does nothing. + */ + virtual void Release() = 0; + + /** + * This method retrieves the current FM Tx state. + * + * @return TFmTxState The current FM Tx state. + * @see MHWRMFmTxObserver + */ + virtual TFmTxState Status() const = 0; + + /** + * The EnableL method switches the FM transmitter on. This is a synchronous + * method that will block the client application. + * + * @param aFrequency The initial transmitter frequency. Defaults to the previous + * frequency setting in Central Repository. + * @exception KErrInUse if reserved by another client. + * KErrArgument if frequency is out of range + * KErrNotReady if there is a wired accessory conflict. Some + * accessories are mutually exclusive with FM Tx. + * KErrNoMemory if there is a memory allocation failure. + * KErrGeneral if there is a hardware error. + */ + virtual void EnableL(TInt aFrequency=0) = 0; + + /** + * The DisableL method switches the FM transmitter off. This is a synchronous + * method that will block the client application. + * + * @exception KErrInUse if reserved by another client. + * KErrGeneral if there is a hardware error. + */ + virtual void DisableL() = 0; + + /** + * The Frequency method queries the current FM Tx frequency + * + * @return TInt The current FM Tx frequency (kHz). + */ + virtual TInt Frequency() const = 0; + + /** + * The GetFrequencyRangeL method queries the valid FM frequency range + * + * @param aFrequencyRange On return, min. and max. frequencies and step size + * of the FM range (kHz) + * @exception KErrInUse if reserved by another client + * KErrGeneral if there is a hardware error + */ + virtual void GetFrequencyRangeL(TFmTxFrequencyRange& aFrequencyRange) const = 0; + + /** + * The SetFrequencyL method sets the FM transmission frequency. FM Tx + * does not need to be enabled. This is a synchronous method + * that will block the client application. + * + * @param TInt aFrequency The new Tx frequency (Hz) + * @exception KErrInUse if reserved by another client + * KErrArgument if frequency parameter is out of range + * KErrGeneral if there is a hardware error + */ + virtual void SetFrequencyL(TInt aFrequency) = 0; + + /** + * The GetNextClearFrequency method requests a new clear frequency + * suggestion. This results in a RSSI scan at the hardware level, + * starting from the frequency increment after the previous suggested + * clear frequency. This is a synchronous method that will block + * the client application. + * + * @param aClearFrequency On return, this is set to a new (suggested) + * clear frequency. + * @exception KErrInUse if reserved by another client + * KErrNotSupported if RSSI scanning is unsupported + * KErrGeneral if there is a hardware error + * KErrNotReady if FM Tx is not enabled + */ + virtual void GetNextClearFrequencyL(TInt& aClearFrequency) = 0; + + /** + * The GetNextClearFrequency method requests a new clear frequency + * suggestion. This results in a RSSI scan at the hardware level, + * starting from the frequency increment after the previous suggested + * clear frequency. This is a synchronous method that will block + * the client application. + * + * @param aClearFrequencyArray On return, this contains 0-KClearFrequencyArrayMax + * clear frequencies. + * @param aCount The number of clear frequencies requested (1-KClearFrequencyArrayMax) + * On return, this is set to the actual number of clear frequencies found. + * @exception KErrInUse if reserved by another client + * KErrArgument If aCount is out of range + * KErrNotSupported if RSSI scanning is unsupported + * KErrGeneral if there is a hardware error + * KErrNotReady if FM Tx is not enabled + */ + virtual void GetNextClearFrequencyL(TClearFrequencyArray& aClearFrequencyArray, TUint& aCount) = 0; + + /** + * The GetNextClearFrequency method requests a new clear frequency + * suggestion. This results in a RSSI scan at the hardware level, + * starting from the frequency increment after the previous suggested + * clear frequency. This is an asynchronous method. + * + * @param aStatus This will be completed when a clear frequency is found + * @param aClearFrequency The clear frequency is returned in this parameter, + * which is only valid when aStatus == KErrNone. + */ + virtual void GetNextClearFrequency(TRequestStatus& aStatus, TInt& aClearFrequency) = 0; + + /** + * The GetNextClearFrequency method requests a new clear frequency + * suggestion. This results in a RSSI scan at the hardware level, + * starting from the frequency increment after the previous suggested + * clear frequency. This is an asynchronous method. + * + * @param aStatus This will be completed when a clear frequency is found + * @param aClearFrequencyArray On return, this contains 0-KClearFrequencyArrayMax + * clear frequencies. + * @param aCount The number of clear frequencies requested (1-KClearFrequencyArrayMax). + * On completion, this is set to the actual number of clear frequencies found. + * @exception KErrArgument if aCount is out of range + */ + virtual void GetNextClearFrequencyL(TRequestStatus& aStatus, TClearFrequencyArray& aClearFrequencyArray, TUint& aCount) = 0; + + /** + * The CancelGetNextClearFrequency method cancels any outstanding + * GetNextClearFrequency requests. If no requests have been made, + * then this has no effect. Note that the request may complete, + * before it can be cancelled. + */ + virtual void CancelGetNextClearFrequency() = 0; + + /** + * The SetNextClearFrequency method sets the FM Tx frequency to a + * new clear frequency suggested. This is equivalent to calling + * SetFrequencyL, with a result returned from GetNextClearFrequency. + * This is a synchronous method that will block the client application. + * + * @param aClearFrequency On return, this is set to the new Tx frequency. + * @exception KErrInUse if reserved by another client. + * KErrNotSupported if RSSI scanning is unsupported + * KErrGeneral if there is a hardware error. + * KErrNotReady if FM Tx is not enabled + */ + virtual void SetNextClearFrequencyL(TInt& aClearFrequency) = 0; + + /** + * The SetNextClearFrequency method sets the FM Tx frequency to a + * new clear frequency suggested. This is equivalent to calling + * SetFrequencyL, with a result returned from GetNextClearFrequency. + * This is an asynchronous method. + * + * @param aStatus This will be completed when a clear frequency is found + * @param aClearFrequency The clear frequency is returned in this parameter, + * which is only valid when aStatus == KErrNone. + */ + virtual void SetNextClearFrequency(TRequestStatus& aStatus, TInt& aClearFrequency) = 0; + + /** + * The CancelSetNextClearFrequency method cancels any outstanding + * SetNextClearFrequency requests. If no requests have been made, + * then this has no effect. Note that the request may complete, + * before it can be cancelled. + */ + virtual void CancelSetNextClearFrequency() = 0; + + /** + * The IsAutoFrequencyEnabled method queries whether auto frequency + * mode is enabled. + * + * @return TBool ETrue if auto frequency is enabled. + */ + virtual TBool IsAutoFrequencyEnabled() = 0; + + /** + * The EnableAutoFrequency method enables the FM Tx automatic frequency + * tuning mode. In this mode, the transmitter will continuously scan + * for interference from other transmitters. When interference is detected, + * the FM Tx frequency will change automatically, resulting in a + * MHWRMFmTxObserver::FmTxFrequencyChanged indication. + * + * @exception KErrInUse if reserved by another client. + * KErrNotSupported if auto frequency is unsupported + * KErrGeneral if there is a hardware error. + * KErrNotReady if FM Tx is not enabled + */ + virtual void EnableAutoFrequencyL() = 0; + + /** + * The DisableAutoFrequency method disables the FM Tx automatic frequency + * tuning mode. + * + * @exception KErrInUse if reserved by another client. + * KErrGeneral if there is a hardware error. + */ + virtual void DisableAutoFrequencyL() = 0; + + /** + * The GetRdsData method Queries the current FM Tx RDS data. + * If FM Tx is enabled, then this data is being transmitted. + * + * @param aData The current FM Tx RDS data. + */ + virtual void GetRdsData(TFmTxRdsData& aData) = 0; + + /** + * The SetRdsPTY method sets the RDS Programme Type to be transmitted. + * + * @param aPty The new Programme Type + * + * @exception KErrInUse if reserved by another client. + * KErrNotSupported if RDS is unsupported + * KErrArgument if aPty out of range + * KErrGeneral if there is a hardware error. + * KErrNotReady if FM Tx is not enabled + */ + virtual void SetRdsPtyL(TRdsProgrammeType aPty) = 0; + + /** + * The SetRdsPTYN method sets the RDS Programme Type Name to be transmitted. + * + * @param aPtyn The new Programme Type Name + * + * @exception KErrInUse if reserved by another client. + * KErrNotSupported if RDS is unsupported + * KErrArgument if non-latin characters are supplied or + * programme type name too long + * KErrGeneral if there is a hardware error. + * KErrNotReady if FM Tx is not enabled + */ + virtual void SetRdsPtynL(TRdsProgrammeTypeName& aPtyn) = 0; + + /** + * The SetRdsMS method sets the RDS Music/Speech flag + * + * @param aMusic ETrue if transmitting music. EFalse if transmitting speech. + * + * @exception KErrInUse if reserved by another client. + * KErrNotSupported if RDS is unsupported + * KErrGeneral if there is a hardware error. + * KErrNotReady if FM Tx is not enabled + */ + virtual void SetRdsMsL(TBool aMusic) = 0; + + /** + * The SetRdsLanguageId method sets the RDS language ID. Only relevant if MS flag + * is set to Speech. + * + * @param aLanguageId The new language ID. + * + * @exception KErrInUse if reserved by another client. + * KErrNotSupported if RDS is unsupported + * KErrArgument if aLanguageId out of range + * KErrGeneral if there is a hardware error. + * KErrNotReady if FM Tx is not enabled + */ + virtual void SetRdsLanguageIdL(TRdsLanguageIdType aLanguageId) = 0; + + /** + * The ClearRdsData method clears any RDS data previously set by clients. + * This does not include Radiotext or Radiotext+ data. + */ + virtual void ClearRdsData() = 0; + + /** + * The SetRadiotext method sets the Radiotext to be transmitted. + * + * @param aText The new Radiotext data. + * + * @exception KErrInUse if reserved by another client. + * KErrNotSupported if Radiotext is unsupported + * KErrArgument if non-latin characters are supplied + * KErrGeneral if there is a hardware error. + * KErrNotReady if FM Tx is not enabled + */ + virtual void SetRadiotextL(TDes& aText) = 0; + + /** + * The SetRadiotextPlus method sets the Radiotext+ to be transmitted. + * + * @param aText The new Radiotext+ data. + * @param aTag The Radiotext+ content type. + * + * @exception KErrInUse if reserved by another client. + * KErrNotSupported if Radiotext+ is unsupported + * KErrArgument if non-latin characters are supplied or + * if content type not valid. + * KErrGeneral if there is a hardware error. + * KErrNotReady if FM Tx is not enabled + */ + virtual void SetRadiotextPlusL(TDes& aText, TRtPlusContentType aContentType) = 0; + + /** + * The SetRadiotextPlus method sets the Radiotext+ to be transmitted. + * + * @param aText The new Radiotext+ data. + * @param aTag A Radiotext+ tag. + * + * @exception KErrInUse if reserved by another client. + * KErrNotSupported if Radiotext+ is unsupported + * KErrArgument if non-latin characters are supplied or + * if RT-plus tag content not valid. + * KErrGeneral if there is a hardware error. + * KErrNotReady if FM Tx is not enabled + */ + virtual void SetRadiotextPlusL(TDes& aText, TRtPlusTag aTag) = 0; + + /** + * The SetRadiotextPlus method sets the Radiotext+ to be transmitted. + * + * @param aText The new Radiotext+ data. + * @param aTag A Radiotext+ tag. + * @param aTag A second Radiotext+ tag. + * + * @exception KErrInUse if reserved by another client. + * KErrNotSupported if Radiotext+ is unsupported + * KErrArgument if non-latin characters are supplied or + * if RT-plus tag content not valid. + * KErrGeneral if there is a hardware error. + * KErrNotReady if FM Tx is not enabled + */ + virtual void SetRadiotextPlusL(TDes& aText, TRtPlusTag aTag1, TRtPlusTag aTag2) = 0; + + /** + * The ClearRdsData method clears any Radiotext or Radiotext+ data previously + * set by clients. + */ + virtual void ClearRadiotextData() = 0; + }; + +/** +* MHWRMFmTxObserver +* A client should derive from this abstract class, to receive FM Tx status notifications. +* +* @publishedPartner +* @released +*/ +class MHWRMFmTxObserver + { + public: + + /** + * Called when the device FM Tx status changes. + * + * @param aState Indicates current FM Tx state. + * + * @see TFmTxState + */ + virtual void FmTxStatusChanged(TFmTxState aState) = 0; + + /** + * Called when the device FM Tx frequency changes. + * + * @param aFrequency Indicates current FM Tx frequency (Hz). + */ + virtual void FmTxFrequencyChanged(TInt aFrequency) = 0; + }; + + +#endif // HWRMFMTX_H + +// End of File