/*
* 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 <e32base.h>
#include <hwrm/hwrmfmtxdata.h>
// 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 there is a wired accessory conflict. Some
* accessories are mutually exclusive with FM Tx.
*/
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 there is a wired accessory conflict. Some
* accessories are mutually exclusive with FM Tx.
*/
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 there is a wired accessory conflict. Some
* accessories are mutually exclusive with FM Tx.
*/
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