/*
* Copyright (c) 2010 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:  an extended BT device offering properties of
* a Bluetooth device that may be needed by Bluetooth UIs
*
*/

#ifndef BTDEVEXTENSION_H
#define BTDEVEXTENSION_H

#include <btdevice.h>
#include <btmanclient.h>
#include <bt_sock.h>
#include <btengconstants.h>

/**
 * APIs from this class offer functionalities that are common in mw and app 
 * components of Bluetooth packages. They do not serve as domain APIs.
 * 
 * Using these from external components is risky, due to possible source
 * and binary breaks in future.
 * 
 */

/**
 * The option for specify the default name for a BT device in 
 * case the device has neither a device name nor a friendly name.
 */
enum TDefaultDevNameOption
    {
    ENoDefaultName,
    EColonSeperatedBDAddr, // device name will be formated
    EPlainBDAddr,
    };

/**
 *  Class CBtDevExtension
 *
 *  This class provides the access to the properties of devices from BT registry.
 *  In addition, it provides other dynamic properties such as the connection 
 *  and proximity statuses. Note that client should not store the dynamic 
 *  properties for future use since they may change frequently.
 *
 */
NONSHARABLE_CLASS( CBtDevExtension ) : public CBase
    {

public:
    // placeholder for providing more properties of a device
    enum TBtDevStatus
        {
        EUndefinedStatus,
        EInRangUnknown = 0x01,
        EInRange = 0x02,
        EPermanentInRegistry = 0x04,
        };
    
    /**
     * Two-phase constructor
     * @param aDev a CBTDevice instance. The ownership is transferred.
     * @param aNameOption the option for formating the default device
     *  name when the given aDev instance has no valid name.
     */
    IMPORT_C static CBtDevExtension* NewLC( CBTDevice* aDev, 
            TDefaultDevNameOption aNameOption = EColonSeperatedBDAddr );    

    /**
     * Two-phase constructor
     * @param aAddr the inquiry socket address of the device.
     * @param aName the device-name of the device.
     * @param aNameOption the option for formating the default device
     *  name when the given name is empty.
     */
    IMPORT_C static CBtDevExtension* NewLC( 
            const TInquirySockAddr& aAddr, 
            const TDesC& aName = KNullDesC,
            TDefaultDevNameOption aNameOption = EColonSeperatedBDAddr );        

    /**
     * Two-phase constructor
     * @param aAddr the bd_addr of the device.
     * @param aName the device-name of the device.
     * @param aNameOption the option for formating the default device
     *  name when the given name is empty.
     */
    IMPORT_C static CBtDevExtension* NewLC( 
            const TBTDevAddr& aAddr, 
            const TDesC& aName = KNullDesC,
            TDefaultDevNameOption aNameOption = EColonSeperatedBDAddr );      
    
    /**
     * Destructor
     */
    IMPORT_C virtual ~CBtDevExtension();
    
    /**
     * Tells if the given device is bonded regardless of whether the pairing was 
     * performed under user awareness.
     * 
     * @return ETrue if it is bonded.
    */
    IMPORT_C static TBool IsBonded( const TBTNamelessDevice &dev );
    
    /**
     * Tells if the given device is bonded with the Just Works pairing model.
     * 
     * @return ETrue if it is bonded and the pairing was performed with Just Works.
     */
    IMPORT_C static TBool IsJustWorksBonded( const TBTNamelessDevice &dev );
    
    /**
     *   Tells if the given device has been bonded under user awareness.
     *   User awareness refers that the user interacted or was informed during or 
     *   immediately after the pairing completed.
     *   
     *   @return ETrue if the user is aware of the bonding.
     */
    IMPORT_C static TBool IsUserAwareBonded( const TBTNamelessDevice &dev );
    
    /**
     *   Guesses if the given device is a headset.
     *   
     *   @param the Class of Device of the device of which the type is
     *          determined.
     *   @return ETrue if it is probably a headset. EFalse otherwise.
     */
    IMPORT_C static TBool IsHeadset( const TBTDeviceClass &aCod );    
    
    /**
     * Returns the display name of this device for end users. 
     * @return the friendly name of the device if it is available; else, the device
     * name if it is available; otherwise, the BDADDR seperated with ":".
     */
    IMPORT_C const TDesC& Alias() const;
    
    /**
     * Gets the device address.
     * @return the device.
     */
    IMPORT_C const TBTDevAddr& Addr() const;    
    
    /**
     * Gets the CBTDevice instance.
     * @return the device.
     */
    IMPORT_C const CBTDevice& Device() const;
    
    /**
     * Checks if this device was bonded under user awareness.
     * @return ETrue if it is user-aware bonded.
     */
    IMPORT_C TBool IsUserAwareBonded() const;
    
    /**
     * 
     * Returns the service (limited to services managed in bteng scope)
     * level connection status of the specified device.
     *
     * @param aAddr the address of the device
     * @return one of TBTEngConnectionStatus enums
     */
    IMPORT_C TBTEngConnectionStatus ServiceConnectionStatus() const;
    
    /**
     * Sets a device. The ownership is transferred.
     * 
     * @param aDev the device to be set.
     */
    IMPORT_C void SetDeviceL( CBTDevice* aDev );

    /**
     * Make a copy of this evice.
     * 
     * @return a new device instance.
     */
    IMPORT_C CBtDevExtension* CopyL();
    
public:
    
    /**
     * Internally invoked in this module, not a DLL level API.
     *
     * Sets the service connection status of this device.
     */
    void SetServiceConnectionStatus( TBTEngConnectionStatus aStatus ); 
    
private:
    
    /**
     * C++ default constructor
     */
    CBtDevExtension( TDefaultDevNameOption aNameOption );
    
    /**
     * Symbian 2nd-phase constructor
     */
    void ConstructL( CBTDevice* aDev );
    
    /**
     * Update device properties due to setDeviceL or other events.
     */
    void UpdateNameL();
    
    /**
     * Update the service connection status for this device:
     */
    //void UpdateServiceStatusL();
    
    /**
     * formats the BD_Addr as the device name. 
     */
    void FormatAddressAsNameL();
    
private:
    
    RBuf iAlias; // contains: 
                 // friendly name, if it is not empty; else
                 // device name, if it is not empty; else
                 // the assignment depending on the option chosen by client.
    
    // The Device instance ( in most case it is given by registry)
    CBTDevice* iDev;
    
    // The bits of dynamic status
    TInt iDynamicStatus;
    
    // Indicates the service connection status of this device
    TBTEngConnectionStatus iServiceStatus;
    
    // The option chosen by the client to deal with default BT name assignment.
    TDefaultDevNameOption iNameOption;
    };

typedef RPointerArray<CBtDevExtension> RDevExtensionArray;

#endif /*BTDEVEXTENSION_H*/