/*
* 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