diff -r 0ba996a9b75d -r 613943a21004 bluetoothengine/btserviceutil/export/btdevextension.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/bluetoothengine/btserviceutil/export/btdevextension.h Tue Aug 31 15:25:10 2010 +0300 @@ -0,0 +1,247 @@ +/* +* 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 +#include +#include +#include + +/** + * 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 RDevExtensionArray; + +#endif /*BTDEVEXTENSION_H*/