/*

* Copyright (c) 2006 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:  Bluetooth Engine API for managing device settings.

*

*/

#ifndef BTENGSETTINGS_H

#define BTENGSETTINGS_H

#include <btengdomaincrkeys.h>

#include <btengconstants.h>

#include <CoreApplicationUIsSDKCRKeys.h>

class CBase;

class CBTEngSettingsNotify;

/**

 *  Class MBTEngSettingsObserver

 *

 *  Callback interface for receiving events related to changes 

 *  in Bluetooth power and discoverability mode settings.

 *

 *  @lib btengsettings.lib

 *  @since S60 v3.2

 */

class MBTEngSettingsObserver

    {

public:

    /**

     * Provides notification of changes in the power state 

     * of the Bluetooth hardware.

     *

     * @since S60 v3.2

     * @param aState EBTPowerOff if the BT hardware has been turned off, 

     *               EBTPowerOn if it has been turned off.

     */

    virtual void PowerStateChanged( TBTPowerStateValue aState ) = 0;

    /**

     * Provides notification of changes in the discoverability 

     * mode of the Bluetooth hardware.

     *

     * @since S60 v3.2

     * @param aState EBTDiscModeHidden if the BT hardware is in hidden mode, 

     *               EBTDiscModeGeneral if it is in visible mode.

     */

    virtual void VisibilityModeChanged( TBTVisibilityMode aState ) = 0;

    };

/**

 *  Class CBTEngSettings

 *

 *  This class provides functionality for 

 *  getting and setting Bluetooth settings.

 *

 *  @lib btengsettings.lib

 *  @since S60 v3.2

 */

class CBTEngSettings : public CBase

    {

public:

    /**

     * Two-phase constructor

     *

     * @since S60 v3.2

     * @param aObserver Pointer to callback interface that receives 

     *                  settings change events.

     * @return Pointer to the constructed CBTEngSettings object.

     */

    IMPORT_C static CBTEngSettings* NewL( MBTEngSettingsObserver* aObserver = NULL );

    /**

     * Two-phase constructor

     *

     * @since S60 v3.2

     * @param aObserver Pointer to callback interface that receives 

     *                  settings change events.

     * @return Pointer to the constructed CBTEngSettings object.

     */

    IMPORT_C static CBTEngSettings* NewLC( MBTEngSettingsObserver* aObserver = NULL );

    /**

     * Destructor

     */

    virtual ~CBTEngSettings();

    /**

     * Gets the Bluetooth power state (on or off).

     *

     * @since S60 v3.2

     * @param aState On return, contains the current power mode.

     * @return KErrNone on success, otherwise a system wide error code.

     */

    IMPORT_C TInt GetPowerState( TBTPowerStateValue& aState );

    /**

     * Sets the Bluetooth power state (on or off). If a callback interface has 

     * been provided, the result is communicated through PowerStateChanged() 

     * when to power state change has been fully completed.

     *

     * @since S60 v3.2

     * @param aState Power mode to be set.

     * @return KErrNone on success, otherwise a system wide error code.

     */

    IMPORT_C TInt SetPowerState( TBTPowerStateValue aState );

    /**

     * Gets Bluetooth visibility mode  (hidden, 

     * limited or general discoverable mode).

     *

     * @since S60 v3.2

     * @param aMode On return, contains the current visibility mode.

     * @return KErrNone on success, otherwise a system wide error code.

     */

    IMPORT_C TInt GetVisibilityMode( TBTVisibilityMode& aMode );

    /**

     * Sets Bluetooth visibility mode  (hidden, 

     * limited or general discoverable mode).

     *

     * @since S60 v3.2

     * @param aMode Discoverability mode to be set to Central Repository.

     * @param aTime Time during which the phone remains in general 

     *              discoverable state  (in minutes), only used with 

     *              EBTDiscModeTemporary  (otherwise ignored).

     * @return KErrNone on success, otherwise a system wide error code.

     */

    IMPORT_C TInt SetVisibilityMode( TBTVisibilityMode aMode, TInt aTime = 0 );

    /**

     * Gets Bluetooth local name. If the name has not been set, a 

     * zero-lenght name is returned.

     *

     * @since S60 v3.2

     * @param aMode On return, contains the current local name.

     * @return KErrNone on success, otherwise a system wide error code.

     */

    IMPORT_C TInt GetLocalName( TDes& aName );

    /**

     * Sets Bluetooth local name.

     *

     * @since S60 v3.2

     * @param aMode Local mode to be set to Central Repository.

     * @return KErrNone on success, otherwise a system wide error code.

     */

    IMPORT_C TInt SetLocalName( const TDes& aName );

    /**

     * Sets the Bluetooth power state (on or off). If a callback interface has 

     * been provided, the result is communicated through PowerStateChanged() 

     * when to power state change has been fully completed.

     * If bluetooth is on, power will be switched off gracefully after 

     * all temporary connections have been disconnected. If a non-temporary 

     * connection has been established in the mean time (e.g. with a headset), 

     * power will be switched on permanently.

     * Note: power will only be switched off gracefully if it has also been 

     * switched on through this method, otherwise KErrAccessDenied will be 

     * returned.

     *

     * @since S60 v5.0

     * @return KErrNone on success, otherwise a system wide error code.

     */

    IMPORT_C TInt ChangePowerStateTemporarily();

    /**

     * Gets Bluetooth offline mode settings.

     *

     * @since S60 v5.0

     * @param aOffline On return, indicates whether Offline Mode is active.

     * @param aOfflineAllowed On return, indicates wether Bluetooth is allowed 

     *                        to be turned on in offline mode.

     * @return KErrNone on success, otherwise a system wide error code.

     */

    IMPORT_C TInt GetOfflineModeSettings( TCoreAppUIsNetworkConnectionAllowed& aOffline, 

                                           TBTEnabledInOfflineMode& aOfflineAllowed );

private:

    /**

     * C++ default constructor

     *

     * @since S60 v3.2

     * @param aObserver Pointer to callback interface that receives 

     *                  settings change events.

     */

    CBTEngSettings( MBTEngSettingsObserver* aObserver );

    /**

     * Symbian 2nd-phase constructor

     *

     * @since S60 v3.2

     */

    void ConstructL();

    /**

     * Helper function to get the status from Central Repository of 

     * whether the local name has been modified.

     *

     * @since S60 v3.2

     * @param aStatus On return, contains the current status of the local name.

     * @return KErrNone on success, otherwise a system wide error code.

     */

    TInt GetLocalNameModified( TBool& aStatus );

    /**

     * Helper function for reading a Central Repository key, and 

     * verifying that the value is within the appropriate range.

     *

     * @since S60 v3.2

     * @param aUid UID of the key to be read.

     * @param aKey The key to be read.

     * @param aValue Default value of the key; on return contains

     *               the value as read from CenRep.

     * @param aMinRange1 Lower limit of the first valid range of key values.

     * @param aMaxRange1 Upper limit of the first valid range of key values.

     * @param aMinRange2 Lower limit of the second valid range of key values.

     * @param aMaxRange2 Upper limit of the second valid range of key values.

     */

    void GetCenRepKeyL( const TUid aUid, const TInt aKey, TInt& aValue, 

                         const TInt aMinRange1, const TInt aMaxRange1,

                         const TInt aMinRange2 = 0, const TInt aMaxRange2 = 0 );

    /**

     * Helper function for getting/setting BT local name in BT Registry.

     *

     * @since S60 v3.2

     * @param aName The BT local device name to be read or written. If it 

     *              contains an empty string, it will hold the name on return,

     *              otherwise the contained string will be set to BT Registry.

     * @return KErrNone on success, otherwise a system wide error code.

     */

    TInt HandleBTRegistryNameSetting( TDes& aName );

private: // data

    /**

     * Timer for temporary discoverable mode.

     * Own.

     */

    CBTEngSettingsNotify* iSettingsWatcher;

    /**

     * Observer for changes in BT settings.

     * Not own.

     */

    MBTEngSettingsObserver* iObserver;

    };

#endif // BTENGSETTINGS_H