diff -r 000000000000 -r 40261b775718 mmhais/dvbhreceiverhai/inc/mobiletv/hai/dvbh/dvbhreceiverinfo.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmhais/dvbhreceiverhai/inc/mobiletv/hai/dvbh/dvbhreceiverinfo.h Tue Feb 02 01:56:55 2010 +0200 @@ -0,0 +1,569 @@ +// Copyright (c) 2007-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: +// Declares the DVB-H tuner hardware adaptation information classes. +// +// + +/** + @file + @publishedPartner + @prototype +*/ + +#ifndef DVBHRECEIVERINFO_H +#define DVBHRECEIVERINFO_H + +#include +#include + +class TIp6Addr; + +/** +* @publishedPartner +* @prototype +* @see CDvbhReceiverInfo::SetStateObserver() +* +* Defines an interface for receiving notifications of RDvbhReceiver state changes. +* Clients wishing to monitor state changes should provide a CDvbhReceiverInfo +* instance with an implementation of this interface via CDvbhReceiverInfo::SetStateObserver(). +*/ +class MDvbhStateObserver + { +public: + /** + * @param aNewState Identifies the state to which the RDvbhReceiver has just transitioned. + * + * When a client has registered an implementation with a CDvbhReceiverInfo instance, + * this method will be called whenever RDvbhReceiver changes state, in order to + * inform the client of the new state. + */ + virtual void DvbhStateChange( TDvbhState aNewState ) = 0; + }; + +/** +* @publishedPartner +* @prototype +* @see CDvbhReceiverInfo::SetSignalQualityObserver() +* +* Defines an interface for receiving notifications of changes to signal quality. +* Clients wishing to monitor signal quality should provide a CDvbhReceiverInfo +* instance with an implementation of this interface via CDvbhReceiverInfo::SetSignalQualityObserver(). +*/ +class MDvbhSignalQualityObserver + { +public: + /** + * @param aNewSignalQuality Identifies the new signal quality value. + * + * When a client has registered an implementation with a CDvbhReceiverInfo instance, + * this method will be called whenever the signal quality changes, in order to + * inform the client of the new signal quality. + */ + virtual void DvbhSignalQualityChange( const TDvbhSignalQuality& aNewSignalQuality ) = 0; + }; + +/** +* @publishedPartner +* @prototype +* @see CDvbhReceiverInfo::SetPlatformObserver() +* +* Defines an interface for receiving notifications of changes of the current IP platform. +* Clients wishing to monitor IP platform changes should provide a CDvbhReceiverInfo +* instance with an implementation of this interface via CDvbhReceiverInfo::SetPlatformObserver(). +*/ +class MDvbhPlatformObserver + { +public: + /** + * @param aNewPlatform Identifies the IP platform to which the receiver has just switched. + * @param aESGRoot The IP address of the bootstrap ESG sevice on the new platform. + * + * When a client has registered an implementation with a CDvbhReceiverInfo instance, + * this method will be called whenever the current IP platform changes, in order to + * inform the client of the new IP platform and bootstrap ESG IP address. + */ + virtual void DvbhPlatformChange( const TDvbhPlatform& aNewPlatform, const TIp6Addr& aESGRoot ) = 0; + }; + +/** +* @publishedPartner +* @prototype +* @see CDvbhReceiverInfo::SetNetworkTimeObserver() +* +* Defines an interface for notifying of updates to the network time. +* Clients wishing to monitor network time changes should provide a CDvbhReceiverInfo +* instance with an implementation of this interface via CDvbhReceiverInfo::SetNetworkTimeObserver(). +* Network time update is triggered via call to RDvbhReceiver::UpdateNetworkTime() +*/ +class MDvbhNetworkTimeObserver + { +public: + /** + * When a client has registered an implementation with a CDvbhReceiverInfo instance, + * this method will be called whenever the current network time has been updated. + */ + virtual void DvbhNetworkTimeUpdate() = 0; + }; + +/** +* @publishedPartner +* @prototype +* @see CDvbhReceiverInfo::SetFrequencyObserver() +* +* Defines an interface for receiving notifications of changes to the frequency to which the receiver is tuned. +* Clients wishing to monitor frequency changes should provide a CDvbhReceiverInfo +* instance with an implementation of this interface via CDvbhReceiverInfo::SetFrequencyObserver(). +*/ +class MDvbhFrequencyObserver + { +public: + /** + * @param aNewFrequency Identifies the frequency to which the tuner has just tuned. + * + * When a client has registered an implementation with a CDvbhReceiverInfo instance, + * this method will be called whenever the tuned frequency changes, in order to + * inform the client of the new frequency. + */ + virtual void DvbhFrequencyChange( const TDvbhFrequency& aNewFrequency ) = 0; + }; + +/** +* @publishedPartner +* @prototype +* @see CDvbhReceiverInfo::SetCellIdObserver() +* +* Defines an interface for receiving notifications of changes to current cellId. +* Clients wishing to monitor cellId changes should provide a CDvbhReceiverInfo +* instance with an implementation of this interface via CDvbhReceiverInfo::SetCellIdObserver(). +*/ +class MDvbhCellIdObserver + { +public: + /** + * @param aNewCellId The new cellId. + * + * When a client has registered an implementation with a CDvbhReceiverInfo instance, + * this method will be called whenever the current cellId changes, in order to + * inform the client of the new cellId. + */ + virtual void DvbhCellIdChange( const TDvbhCellId& aNewCellId ) = 0; + }; + +/** +* @publishedPartner +* @prototype +* @see CDvbhReceiverInfo::SetNetworkIdObserver() +* +* Defines an interface for receiving notifications of changes to current networkId. +* Clients wishing to monitor networkId changes should provide a CDvbhReceiverInfo +* instance with an implementation of this interface via CDvbhReceiverInfo::SetNetworkIdObserver(). +*/ +class MDvbhNetworkIdObserver + { +public: + /** + * @param aNewNetworkId The ID of the network to which the receiver is now tuned. + * + * When a client has registered an implementation with a CDvbhReceiverInfo instance, + * this method will be called whenever the ID of the network to which it is tuned changes, + * in order to inform the client of the new networkId. + */ + virtual void DvbhNetworkIdChange( const TDvbhNetworkId& aNewNetworkId ) = 0; + }; + + +/** +* @publishedPartner +* @prototype +* @see CDvbhReceiverInfo::SetBatteryStateObserver() +* +* Defines an interface for receiving notifications of changes in external DVB-H receiver battery state. +* Clients wishing to monitor battery changes should provide a CDvbhReceiverInfo +* instance with an implementation of this interface via CDvbhReceiverInfo::SetBatteryStateObserver(). +*/ +class MDvbhExtBatteryStateObserver + { + public: + /** + * @param aNewState The new battery state of external receiver. + * + * When a client has registered an implementation with a CDvbhReceiverInfo instance, + * this method will be called whenever the battery state of external receiver is changed, + * in order to inform the client of the new aNewState. + */ + virtual void DvbhExtBatteryStateChange( TDvbhExtBatteryState aNewState ) = 0; + }; + +/** +* @publishedPartner +* @prototype +* @see CDvbhReceiverInfo::SetExtConnectionStateObserver() +* +* Defines an interface for receiving notifications of changes in external DVB-H receiver connection +* Clients wishing to monitor connection changes should provide a CDvbhReceiverInfo +* instance with an implementation of this interface via CDvbhReceiverInfo::SetExtConnectionStateObserver(). +*/ +class MDvbhExtConnectionObserver + { + public: + + /** + * @param aNewState The new external receiver connection state. + * @param aReceiverType Type of the receiver + * + * When a client has registered an implementation with a CDvbhReceiverInfo instance, + * this method will be called whenever the connection state of external receiver is changed, + * in order to inform the client of the new aNewState. + */ + virtual void DvbhExtConnectionStateChange( + const TDvbhExtConnectionState& aNewState, const TDvbhReceiverType& aReceiverType ) = 0; + }; + + +/** +* @publishedPartner +* @prototype +* @see CDvbhReceiverInfo::SetExtAntennaConnectionStateObserver() +* +* Defines an interface for receiving notifications of changes in external DVB-H receiver antenna connection. +* Clients wishing to monitor connection changes should provide a CDvbhReceiverInfo +* instance with an implementation of this interface via CDvbhReceiverInfo::SetExtAntennaConnectionStateObserver(). +*/ +class MDvbhExtAntennaConnectionObserver + { + public: + + /** + * @param aNewState The new external antenna connection state. + * @param aReceiverType Type of the receiver + * + * When a client has registered an implementation with a CDvbhReceiverInfo instance, + * this method will be called whenever the connection state of external receiver antenna is changed, + * in order to inform the client of the new aNewState. + */ + virtual void DvbhExtAntennaConnectionStateChange( + const TDvbhExtAntennaConnectionState& aNewState, const TDvbhReceiverType& aReceiverType ) = 0; + }; + + +/** +* @publishedPartner +* @prototype +* +* Provides operations for reading and tracking information about the receiver, such +* as state, signal quality, frequency, etc. Refer to the individual class methods +* for the full list. +* +* Use of this class is safe in the sense that it will not interfere with the +* receiver operation in any way. There can be multiple simultaneous instances +* of CDvbhReceiverInfo at one time. +*/ +class CDvbhReceiverInfo : public CBase + { +public: + /** + * @return A new instance of CDvbhReceiverInfo. + * + * Factory function for creating a CDvbhReceiverInfo object. + */ + IMPORT_C static CDvbhReceiverInfo* NewL(); + + /** + * @return A new instance of CDvbhReceiverInfo. + * + * Factory function for creating a CDvbhReceiverInfo object, with + * the new object left on the CleanupStack. + */ + IMPORT_C static CDvbhReceiverInfo* NewLC(); + + /** + * C++ destructor. + */ + IMPORT_C ~CDvbhReceiverInfo(); + + /** + * @param aState Updated with the current state of the receiver. + * @return KErrNone on success, otherwise a system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * + * Retrieves the current state of the receiver. + */ + IMPORT_C static TInt GetState( TDvbhState& aState ); + + /** + * @param aObserver An instance of an MDvbhStateObserver implementation. + * @return KErrNone on success, otherwise a system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * @see MDvbhStateObserver + * + * Used to register an MDvbhStateObserver implementation with the object. Once a client + * has registered such an observer, it will be notified of any changes in receiver + * state via that observer until either a new observer is registered or this object is + * destroyed. + * + * If called more than once on an instance, the most recent observer registered + * overrides any previously registered observers. + */ + IMPORT_C TInt SetStateObserver( MDvbhStateObserver& aObserver ); + + /** + * @param aSignalQuality Updated with the current signal quality value. + * @return KErrNone on success, KErrNotReady if receiver is not in the Receiving state, or another system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * + * Retrieves the current signal quality value. + */ + IMPORT_C static TInt GetSignalQuality( TDvbhSignalQuality& aSignalQuality ); + + /** + * @param aObserver An instance of an MDvbhSignalQualityObserver implementation. + * @return KErrNone on success, otherwise a system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * @see MDvbhSignalQualityObserver + * + * Used to register an MDvbhSignalQualityObserver implementation with the object. Once a client + * has registered such an observer, it will be notified of any changes to signal + * quality via that observer until either a new observer is registered or this object is + * destroyed. + * + * If called more than once on an instance, the most recent observer registered + * overrides any previously registered observers. + */ + IMPORT_C TInt SetSignalQualityObserver( MDvbhSignalQualityObserver& aObserver ); + + /** + * @param aPlatform Updated with the currently active IP platform. + * @param aESGRoot Updated with the IP address of the bootstrap ESG service on the platform. + * @return KErrNone on success, KErrNotReady if platform has not been set on the receiver, or another system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * + * Retrieves the currently active IP platform and IP address of its bootstrap ESG service. + */ + IMPORT_C static TInt GetPlatform( TDvbhPlatform& aPlatform, TIp6Addr& aESGRoot ); + + /** + * @param aObserver An instance of an MDvbhPlatformObserver implementation. + * @return KErrNone on success, otherwise a system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * @see MDvbhPlatformObserver + * + * Used to register an MDvbhPlatformObserver implementation with the object. Once a client + * has registered such an observer, it will be notified of any changes to IP platform + * via that observer until either a new observer is registered or this object is + * destroyed. + * + * If called more than once on an instance, the most recent observer registered + * overrides any previously registered observers. + */ + IMPORT_C TInt SetPlatformObserver( MDvbhPlatformObserver& aObserver ); + + /** + * @param aNetworkTime Upated with the current network time. + * @param aValid Updated with ETrue if the receiver is in Ready or Receiving state; or EFalse if the time offset of a previous platform is available and has been used as a fallback to calculate the given time. + * @return KErrNone on success, KErrNotReady if no platform has ever been set on the receiver, or another system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * @see RDvbhReceiver::UpdateNetworkTime() + * + * Retrieves the current network time by calculating it from the offset obtained + * after the last call to RDvbhReceiver::UpdateNetworkTime(). + */ + IMPORT_C static TInt GetNetworkTime( TTime& aNetworkTime, TBool& aValid ); + + /** + * @param aObserver An instance of an MDvbhNetworkTimeObserver implementation. + * @return KErrNone on success, otherwise a system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * @see MDvbhNetworkTimeObserver + * + * Used to register an MDvbhNetworkTimeObserver implementation with the object. Once a client + * has registered such an observer, it will be notified whenever the network time has been + * updated via that observer until either a new observer is registered or this object is + * destroyed. + * + * If called more than once on an instance, the most recent observer registered + * overrides any previously registered observers. + */ + IMPORT_C TInt SetNetworkTimeObserver( MDvbhNetworkTimeObserver& aObserver ); + + /** + * @param aPerformanceData Updated with the current usage and performance data of the receiver. + * @return KErrNone on success, KErrNotReady if the receiver is not in Receiving state, or another system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * + * Retrieves the current performance and usage data from the receiver. + */ + IMPORT_C static TInt GetPerformanceData( TDvbhPerformanceData& aPerformanceData ); + + /** + * @param aFrequency Updated with the frequency to which the receiver is currently tuned. + * @return KErrNone on success, KErrNotReady if platform has not been set on the receiver, or another system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * + * Retrieves the frequency to which the receiver is currently tuned. + */ + IMPORT_C static TInt GetFrequency( TDvbhFrequency& aFrequency ); + + /** + * @param aObserver An instance of an MDvbhFrequencyObserver implementation. + * @return KErrNone on success, otherwise a system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * @see MDvbhFrequencyObserver + * + * Used to register an MDvbhFrequencyObserver implementation with the object. Once a client + * has registered such an observer, it will be notified whenever the frequency to which + * the receiver is tuned changes via that observer until either a new observer is + * registered or this object is destroyed. + * + * If called more than once on an instance, the most recent observer registered + * overrides any previously registered observers. + */ + IMPORT_C TInt SetFrequencyObserver( MDvbhFrequencyObserver& aObserver ); + + /** + * @param aCellId Updated with the current cellId. + * @return KErrNone on success, KErrNotReady if platform has not been set on the receiver, or another system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * + * Retrieves the current cellId. + */ + IMPORT_C static TInt GetCellId( TDvbhCellId& aCellId ); + + /** + * @param aObserver An instance of an MDvbhCellIdObserver implementation. + * @return KErrNone on success, otherwise a system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * @see MDvbhCellIdObserver + * + * Used to register an MDvbhCellIdObserver implementation with the object. Once a client + * has registered such an observer, it will be notified whenever the current cellId changes + * via that observer until either a new observer is registered or the object is destroyed. + * + * If called more than once on an instance, the most recent observer registered + * overrides any previously registered observers. + */ + IMPORT_C TInt SetCellIdObserver( MDvbhCellIdObserver& aObserver ); + + /** + * @param aNetworkId Updated with the ID of the network to which the receiver is currently tuned. + * @return KErrNone on success, KErrNotReady if platform has not been set on the receiver, or another system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * + * Retrieves the networkId of the network to which the receiver is currently tuned. + */ + IMPORT_C static TInt GetNetworkId( TDvbhNetworkId& aNetworkId ); + + /** + * @param aObserver An instance of an MDvbhNetworkIdObserver implementation. + * @return KErrNone on success, otherwise a system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * @see MDvbhNetworkIdObserver + * + * Used to register an MDvbhNetworkIdObserver implementation with the object. Once a client + * has registered such an observer, it will be notified whenever the ID of the network to which + * the receiver is tuned changes via that observer until either a new observer is + * registered or this object is destroyed. + * + * If called more than once on an instance, the most recent observer registered + * overrides any previously registered observers. + */ + IMPORT_C TInt SetNetworkIdObserver( MDvbhNetworkIdObserver& aObserver ); + + /** + * @param aState Updated with the battery state of external receiver + * @return KErrNone on success, or another system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * + * Retrieves the battery state of external receiver + */ + IMPORT_C static TInt GetBatteryState( TDvbhExtBatteryState& aState ); + + /** + * @param aObserver An instance of an MDvbhExtBatteryStateObserver implementation. + * @return KErrNone on success, otherwise a system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * @see MDvbhExtBatteryStateObserver + * + * Used to register an MDvbhExtBatteryStateObserver implementation with the object. Once a client + * has registered such an observer, it will be notified whenever the battery state of external receiver + * has changed via that observer until either a new observer is + * registered or this object is destroyed. + * + * If called more than once on an instance, the most recent observer registered + * overrides any previously registered observers. + */ + IMPORT_C TInt SetBatteryStateObserver( MDvbhExtBatteryStateObserver& aObserver ); + + /** + * @param aConnectionState Updated with the connection state of external receiver + * @param aReceiver Input for which receiver type the connection state is queried + * @return KErrNone on success, or another system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * + * Retrieves the connection state of external receiver + */ + IMPORT_C static TInt GetExtConnectionState( TDvbhExtConnectionState& aConnectionState, const TDvbhReceiverType& aReceiver ); + + /** + * @param aObserver An instance of an MDvbhExtConnectionObserver implementation. + * @return KErrNone on success, otherwise a system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * @see MDvbhExtConnectionObserver + * + * Used to register an MDvbhExtConnectionObserver implementation with the object. Once a client + * has registered such an observer, it will be notified whenever the connection state of external + * receiver has changed via that observer until either a new observer is + * registered or this object is destroyed. + * + * If called more than once on an instance, the most recent observer registered + * overrides any previously registered observers. + */ + IMPORT_C TInt SetExtConnectionStateObserver( MDvbhExtConnectionObserver& aObserver ); + + /** + * @param aConnectionState Updated with the antenna connection state of external receiver + * @param aReceiver Input for which receiver type the connection state is queried + * @return KErrNone on success, or another system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * + * Retrieves the antenna connection state of external receiver. + */ + IMPORT_C static TInt GetExtAntennaConnectionState( TDvbhExtAntennaConnectionState& aConnectionState, const TDvbhReceiverType& aReceiver ); + + /** + * @param aObserver An instance of an MDvbhExtAntennaConnectionObserver implementation. + * @return KErrNone on success, otherwise a system-wide error code. Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * @see MDvbhExtAntennaConnectionObserver + * + * Used to register an MDvbhExtAntennaConnectionObserver implementation with the object. Once a client + * has registered such an observer, it will be notified whenever the antenna connection state of external + * receiver has changed via that observer until either a new observer is + * registered or this object is destroyed. + * + * If called more than once on an instance, the most recent observer registered + * overrides any previously registered observers. + */ + IMPORT_C TInt SetExtAntennaConnectionStateObserver( MDvbhExtAntennaConnectionObserver& aObserver ); + + /** + * @param aDeviceInfo Updated with the device information of external receiver + * @param aReceiver Input for which receiver type the device information is queried + * @return KErrNone on success, KErrNotSupported if receiver type is not supported, or another system-wide error code. + * Clients should accept unknown error codes gracefully since new error codes may be returned in the future. + * + * Retrieves the device information of external receiver. Please note that the external receiver must be connected to get valid + * device information. + */ + IMPORT_C static TInt GetExtDeviceInfo( TDvbhAccessoryInfo& aDeviceInfo, const TDvbhReceiverType& aReceiver ); + +private: + /** + * C++ constructor. + */ + CDvbhReceiverInfo(); + + /** + * Symbian 2nd phase constructor. + */ + void ConstructL(); + +private: + /* + * Implementers of this interface should declare their own CPrivateData + * class containing whatever private data is needed for their implementation. + */ + class CPrivateData; + CPrivateData* iData; + }; + +#endif // DVBHRECEIVERINFO_H