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