1 /*

     2 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  an extended BT device offering properties of

    15 * a Bluetooth device that may be needed by Bluetooth UIs

    16 *

    17 */

    18 

    19 #ifndef BTDEVEXTENSION_H

    20 #define BTDEVEXTENSION_H

    21 

    22 #include <btdevice.h>

    23 #include <btmanclient.h>

    24 #include <bt_sock.h>

    25 #include <btengconstants.h>

    26 

    27 /**

    28  * APIs from this class offer functionalities that are common in mw and app 

    29  * components of Bluetooth packages. They do not serve as domain APIs.

    30  * 

    31  * Using these from external components is risky, due to possible source

    32  * and binary breaks in future.

    33  * 

    34  */

    35 

    36 /**

    37  * The option for specify the default name for a BT device in 

    38  * case the device has neither a device name nor a friendly name.

    39  */

    40 enum TDefaultDevNameOption

    41     {

    42     ENoDefaultName,

    43     EColonSeperatedBDAddr, // device name will be formated

    44     EPlainBDAddr,

    45     };

    46 

    47 /**

    48  *  Class CBtDevExtension

    49  *

    50  *  This class provides the access to the properties of devices from BT registry.

    51  *  In addition, it provides other dynamic properties such as the connection 

    52  *  and proximity statuses. Note that client should not store the dynamic 

    53  *  properties for future use since they may change frequently.

    54  *

    55  */

    56 NONSHARABLE_CLASS( CBtDevExtension ) : public CBase

    57     {

    58 

    59 public:

    60     // placeholder for providing more properties of a device

    61     enum TBtDevStatus

    62         {

    63         EUndefinedStatus,

    64         EInRangUnknown = 0x01,

    65         EInRange = 0x02,

    66         EPermanentInRegistry = 0x04,

    67         };

    68     

    69     /**

    70      * Two-phase constructor

    71      * @param aDev a CBTDevice instance. The ownership is transferred.

    72      * @param aNameOption the option for formating the default device

    73      *  name when the given aDev instance has no valid name.

    74      */

    75     IMPORT_C static CBtDevExtension* NewLC( CBTDevice* aDev, 

    76             TDefaultDevNameOption aNameOption = EColonSeperatedBDAddr );    

    77 

    78     /**

    79      * Two-phase constructor

    80      * @param aDev a CBTDevice instance. The ownership is transferred.

    81      * @param aNameOption the option for formating the default device

    82      *  name when the given aDev instance has no valid name.

    83      */

    84     IMPORT_C static CBtDevExtension* NewLC( 

    85             const TInquirySockAddr& aAddr, 

    86             const TDesC& aName = KNullDesC,

    87             TDefaultDevNameOption aNameOption = EColonSeperatedBDAddr );        

    88     

    89     /**

    90      * Destructor

    91      */

    92     IMPORT_C virtual ~CBtDevExtension();

    93     

    94     /**

    95      * Tells if the given device is bonded regardless of whether the pairing was 

    96      * performed under user awareness.

    97      * 

    98      * @return ETrue if it is bonded.

    99     */

   100     IMPORT_C static TBool IsBonded( const TBTNamelessDevice &dev );

   101     

   102     /**

   103      * Tells if the given device is bonded with the Just Works pairing model.

   104      * 

   105      * @return ETrue if it is bonded and the pairing was performed with Just Works.

   106      */

   107     IMPORT_C static TBool IsJustWorksBonded( const TBTNamelessDevice &dev );

   108     

   109     /**

   110      *   Tells if the given device has been bonded under user awareness.

   111      *   User awareness refers that the user interacted or was informed during or 

   112      *   immediately after the pairing completed.

   113      *   

   114      *   @return ETrue if the user is aware of the bonding.

   115      */

   116     IMPORT_C static TBool IsUserAwareBonded( const TBTNamelessDevice &dev );

   117     

   118     /**

   119      * Returns the display name of this device for end users. 

   120      * @return the friendly name of the device if it is available; else, the device

   121      * name if it is available; otherwise, the BDADDR seperated with ":".

   122      */

   123     IMPORT_C const TDesC& Alias() const;

   124     

   125     /**

   126      * Gets the device address.

   127      * @return the device.

   128      */

   129     IMPORT_C const TBTDevAddr& Addr() const;    

   130     

   131     /**

   132      * Gets the CBTDevice instance.

   133      * @return the device.

   134      */

   135     IMPORT_C const CBTDevice& Device() const;

   136     

   137     /**

   138      * Checks if this device was bonded under user awareness.

   139      * @return ETrue if it is user-aware bonded.

   140      */

   141     IMPORT_C TBool IsUserAwareBonded() const;

   142     

   143     /**

   144      * 

   145      * Returns the service (limited to services managed in bteng scope)

   146      * level connection status of the specified device.

   147      *

   148      * @param aAddr the address of the device

   149      * @return one of TBTEngConnectionStatus enums

   150      */

   151     IMPORT_C TBTEngConnectionStatus ServiceConnectionStatus() const;

   152     

   153     /**

   154      * Sets a device. The ownership is transferred.

   155      * 

   156      * @param aDev the device to be set.

   157      */

   158     IMPORT_C void SetDeviceL( CBTDevice* aDev );

   159 

   160     /**

   161      * Make a copy of this evice.

   162      * 

   163      * @return a new device instance.

   164      */

   165     IMPORT_C CBtDevExtension* CopyL();

   166     

   167 public:

   168     

   169     /**

   170      * Internally invoked in this module, not a DLL level API.

   171      *

   172      * Sets the service connection status of this device.

   173      */

   174     void SetServiceConnectionStatus( TBTEngConnectionStatus aStatus ); 

   175     

   176 private:

   177     

   178     /**

   179      * C++ default constructor

   180      */

   181     CBtDevExtension( TDefaultDevNameOption aNameOption );

   182     

   183     /**

   184      * Symbian 2nd-phase constructor

   185      */

   186     void ConstructL( CBTDevice* aDev );

   187     

   188     /**

   189      * Update device properties due to setDeviceL or other events.

   190      */

   191     void UpdateNameL();

   192     

   193     /**

   194      * Update the service connection status for this device:

   195      */

   196     //void UpdateServiceStatusL();

   197     

   198     /**

   199      * formats the BD_Addr as the device name. 

   200      */

   201     void FormatAddressAsNameL();

   202     

   203 private:

   204     

   205     RBuf iAlias; // contains: 

   206                  // friendly name, if it is not empty; else

   207                  // device name, if it is not empty; else

   208                  // the assignment depending on the option chosen by client.

   209     

   210     // The Device instance ( in most case it is given by registry)

   211     CBTDevice* iDev;

   212     

   213     // The bits of dynamic status

   214     TInt iDynamicStatus;

   215     

   216     // Indicates the service connection status of this device

   217     TBTEngConnectionStatus iServiceStatus;

   218     

   219     // The option chosen by the client to deal with default BT name assignment.

   220     TDefaultDevNameOption iNameOption;

   221     };

   222 

   223 typedef RPointerArray<CBtDevExtension> RDevExtensionArray;

   224 

   225 #endif /*BTDEVEXTENSION_H*/