1 /*

     2 * Copyright (c) 2006 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:  Bluetooth Engine API for remote device and service discovery 

    15 *                and local SDP database functionality.

    16 *

    17 */

    18 

    19 

    20 #ifndef BTENGDISCOVERY_H

    21 #define BTENGDISCOVERY_H

    22 

    23 #include <btsdp.h>

    24 #include <btdevice.h>

    25 

    26 class CBTEngSdpDbHandler;

    27 class CBTEngSdpQuery;

    28 class CBTEngDeviceSearch;

    29 class TBTEngSdpAttrValue;

    30 

    31 /**  Array definition for storing SDP record handles */

    32 typedef RArray<TSdpServRecordHandle> RSdpRecHandleArray;

    33 

    34 /**  Array definition for storing SDP attribute values */

    35 typedef RArray<TBTEngSdpAttrValue> RSdpResultArray;

    36 

    37 

    38 /**

    39  *  class TBTEngSdpResult

    40  *

    41  *  Data structure for passing SDP results to the client.

    42  *

    43  *  @lib btengdiscovery.lib

    44  *  @since S60 v3.2

    45  */

    46 class TBTEngSdpAttrValue

    47     {

    48 

    49 public:

    50 

    51     /**

    52      * Data structure containing the SDP attribute value.

    53      * Note: the member varaible containing the data is dependent 

    54      * on the data type attribute of the parent class.

    55      */

    56     class TSdpAttrValue

    57         {

    58 

    59     public:

    60 

    61         /**

    62          * Numeric value (0 if the attribute is non-numeric).

    63          */

    64         TInt iValNumeric;

    65 

    66         /**

    67          * String value (empty if the attribute is numeric).

    68          */

    69         TPtrC8 iValString;

    70 

    71         };

    72 

    73 public: // data

    74 

    75     /**

    76      * Attribute identifier of this attribute.

    77      */

    78     TSdpAttributeID iAttrId;

    79 

    80     /**

    81      * Attribute type of this attribute.

    82      */

    83     TSdpElementType iAttrType;

    84 

    85     /**

    86      * Attribute value of this attribute.

    87      */

    88     TSdpAttrValue iAttrValue;

    89 

    90     };

    91 

    92 

    93 /**

    94  *  Class CBTEngDiscovery

    95  *

    96  *  Callback interface for receiving results from queries 

    97  *  of remote SDP databases.

    98  *  Clients that make SDP queries through CBTEngDiscovery 

    99  *  must implement this interface to handle the results.

   100  *

   101  *  @lib btengdiscovery.lib

   102  *  @since S60 v3.2

   103  */

   104 class MBTEngSdpResultReceiver

   105     {

   106 

   107 public:

   108 

   109     /**

   110      * Provides notification of the result of a service search that matches 

   111      * the requested UUID (through CBTEngDiscovery::RemoteSdpQuery).

   112      * This method indicates that the search has completed, and returns 

   113      * all the results to the caller at once.

   114      *

   115      * @since S60 v3.2

   116      * @param aResult Array of record handles that match the requested UUID.

   117      *                Note: the array will not be available anymore after 

   118      *                this method returns.

   119      * @param aTotalRecordsCount The total number of records returned.

   120      * @param aErr Error code of the service search operation; KErrNone if 

   121      *             sucessful, KErrEof if no record matched the requested UUID, 

   122      *             KErrCouldNotConnect and KErrCouldDisconnected in case of 

   123      *             Bluetooth connection errors; otherwise one of the 

   124      *             system-wide error codes.

   125      */

   126     virtual void ServiceSearchComplete( const RSdpRecHandleArray& aResult, 

   127                                          TUint aTotalRecordsCount, TInt aErr ) = 0;

   128 

   129     /**

   130      * Provides notification of the result of an attribute search that matches 

   131      * the requested attribute (through CBTEngDiscovery::RemoteSdpQuery).

   132      * This method indicates that the search has completed, and returns 

   133      * all the results to the caller at once.

   134      *

   135      * @since S60 v3.2

   136      * @param aHandle Record handle of the service record containing the result.

   137      * @param aAttr Array containing the attribute that matches the 

   138      *              requested attribute.

   139      *              Note: the array will not be available anymore after 

   140      *              this method returns.

   141      * @param aErr Error code of the service search operation; KErrNone if 

   142      *             sucessful, KErrEof if the requested attribute was not 

   143      *             contained in the specified service record, 

   144      *             KErrCouldNotConnect and KErrCouldDisconnected in case of 

   145      *             Bluetooth connection errors; otherwise one of the 

   146      *             system-wide error codes.

   147      */

   148     virtual void AttributeSearchComplete( TSdpServRecordHandle aHandle, 

   149                                            const RSdpResultArray& aAttr, 

   150                                            TInt aErr ) = 0;

   151 

   152     /**

   153      * Provides notification of the result of an combination of a service 

   154      * and attribute search (through CBTEngDiscovery::RemoteSdpQuery).

   155      * This method is called for each service and attribute combination for 

   156      * which a match was found. The last result (which could be empty if no 

   157      * match was found) contain error code KErrEof to indicate that the 

   158      * search has completed. The corresponding CBTEngDiscovery instance

   159      * can only be deleted inside the callback method if the serach

   160      * has completed (KErrEof is received). 

   161      *

   162      * @since S60 v3.2

   163      * @param aHandle Record handle of the service record containing the result.

   164      * @param aAttr Array containing the attribute that matches the 

   165      *              requested attribute.

   166      *              Note: the array will not be available anymore after 

   167      *              this method returns.

   168      * @param aErr Error code of the service search operation; KErrNone if 

   169      *             sucessful and more results follow, KErrEof indicates that 

   170      *             this is the last result (which could be empty if no match 

   171      *             was found), KErrCouldNotConnect and KErrCouldDisconnected 

   172      *             in case of Bluetooth connection errors; otherwise one of 

   173      *             the system-wide error codes.

   174      */

   175     virtual void ServiceAttributeSearchComplete( TSdpServRecordHandle aHandle, 

   176                                                   const RSdpResultArray& aAttr, 

   177                                                   TInt aErr ) = 0;

   178 

   179     /**

   180      * Provides notification of the result of the discovery of nearby 

   181      * Bluetooth devices.

   182      *

   183      * @since S60 v3.2

   184      * @param aDevice The data structure encapsulates information 

   185      *                about the selected device. Ownership of the data 

   186      *                structure has not been transfered and is still with

   187      *                the API client.

   188      * @param aErr Error code of the device search operation; KErrNone if 

   189      *             sucessful, KErrCancel if the user cancelled the 

   190      *             dialog, KErrAbort if CBTEngDiscovery::CancelSearchRemoteDevice

   191      *             was called; otherwise one of the system-wide error codes.

   192      */

   193     virtual void DeviceSearchComplete( CBTDevice* aDevice, TInt aErr ) = 0;

   194     

   195     /**

   196      * Provides notification of the result of the discovery of nearby 

   197      * Bluetooth devices and EIR data.

   198      *

   199      * @since S60 v5.1

   200      * @param aDevice The data structure encapsulates information 

   201      *                about the selected device. 

   202      *                Ownership of the data structure has not been transfered and

   203      *                is still with the API client.

   204      * @param aNameEntry Contains the EIR data of the remote device.

   205      *                Ownership of the data structure has not been transfered and

   206      *                is still with the API client. 

   207      * @param aErr Error code of the device search operation; KErrNone if 

   208      *             sucessful, KErrCancel if the user cancelled the 

   209      *             dialog, KErrAbort if CBTEngDiscovery::CancelSearchRemoteDevice

   210      *             was called; otherwise one of the system-wide error codes.

   211      */

   212     IMPORT_C virtual void DeviceSearchComplete( CBTDevice* aDevice, 

   213             TNameEntry* aNameEntry, TInt aErr );

   214     

   215     /**

   216      * Provides notification of the result of service UUIDs retrieval.

   217      *

   218      * @since S60 v5.1

   219      * @param aNameEntry Contains the EIR data of the remote device.

   220      *                    Ownership of the data structure has not been transfered and

   221      *                    is still with the API client. 

   222      * @param aErr KErrNone if sucessful;

   223      *             otherwise one of the system-wide error codes.

   224      */

   225     IMPORT_C virtual void GetEirServiceUUIDsComplete( 

   226             TNameEntry* aNameEntry, TInt aErr );

   227     

   228     };

   229 

   230 /**

   231  *  Class CBTEngDiscovery

   232  *

   233  *  This is a helper class that simplifies the usage of Symbian's 

   234  *  BluetoothT SDP interface, for registration of SDP records in 

   235  *  the local database and for queries of remote SDP databases.

   236  *  Additionally, functionality for searching for and pairing with 

   237  *  remote Bluetooth devices.

   238  *

   239  *  @lib btengdiscovery.lib

   240  *  @since S60 v3.2

   241  */

   242 class CBTEngDiscovery : public CBase

   243     {

   244 

   245 public:

   246     /**

   247      * Two-phase constructor

   248      *

   249      * @since S60 v3.2

   250      * @param aNotifier Pointer to callback interface that receives 

   251      *                  the SDP query results.

   252      * @return Pointer to the constructed CBTEngDiscovery object.

   253      */

   254     IMPORT_C static CBTEngDiscovery* NewL( MBTEngSdpResultReceiver* aNotifier = NULL );

   255 

   256     /**

   257      * Two-phase constructor

   258      *

   259      * @since S60 v3.2

   260      * @param aNotifier Pointer to callback interface that receives 

   261      *                  the SDP query results.

   262      * @return Pointer to the constructed CBTEngDiscovery object.

   263      */

   264     IMPORT_C static CBTEngDiscovery* NewLC( MBTEngSdpResultReceiver* aNotifier = NULL );

   265 

   266     /**

   267      * Destructor

   268      */

   269     virtual ~CBTEngDiscovery();

   270 

   271     /**

   272      * Launches to notifier for discovering nearby Bluetooth devices and 

   273      * user selection of one device.

   274      * When completed, the selected device is passed back to the client 

   275      * through the callback interface 

   276      * method MBTEngSdpResultReceiver::DeviceSearchComplete().

   277      *

   278      * @since S60 v3.2

   279      * @param aDevice The data structure in which the result will be stored 

   280      *                (passed back thorugh DeviceSearchComplete()).

   281      *                Ownership of the data structure remains with the caller 

   282      *                of this method.

   283      * @param aServiceClass Filter for device search; this will filter the 

   284      *                      results according to the specified major service 

   285      *                      class field of the CoD. The default value 

   286      *                      is zero and will not apply any filter.

   287      * @return KErrNone if sucessful, otherwise the error code 

   288      *         indicating the error situation.

   289      */

   290     IMPORT_C TInt SearchRemoteDevice( CBTDevice* aDevice, TUint aServiceClass = 0 );

   291 

   292     /**

   293      * Launches to notifier for discovering nearby Bluetooth devices and 

   294      * user selection of one device. Additionally, this method returns service 

   295      * UUIDs in the EIR data of the selected device.

   296      * When completed, the selected device and its serivice UUID list are passed 

   297      * back to the client through the callback interface 

   298      * method MBTEngSdpResultReceiver::DeviceSearchComplete().

   299      * 

   300      * @since S60 v5.1

   301      * @param aDevice The data structure in which the result will be stored 

   302      *                (passed back thorugh DeviceSearchComplete()).

   303      *                Ownership of the data structure remains with the caller 

   304      *                of this method.

   305      * @param aNameEntry The data structure in which the EIR data of the 

   306      *                   selected device will be stored

   307      *                   (passed back thorugh DeviceSearchComplete()).

   308      *                   TBluetoothNameRecordWrapper can be constructed from a 

   309      *                   TNameRecord instance for the purpose of parsing and 

   310      *                   getting Extended Inquiry Response tags.

   311      *                   Ownership of the data structure remains with the caller 

   312      *                   of this method.

   313      * @param aServiceClass Filter for device search; this will filter the 

   314      *                      results according to the specified major service 

   315      *                      class field of the CoD. The default value 

   316      *                      is zero and will not apply any filter.

   317      * @return KErrNone if sucessful, otherwise the error code 

   318      *         indicating the error situation.

   319      */

   320     IMPORT_C TInt SearchRemoteDevice( CBTDevice* aDevice, 

   321             TNameEntry* aNameEntry, TUint aServiceClass = 0 );

   322     

   323     /**

   324      * Cancels an ongoing search for nearby Bluetooth devices.

   325      * This results in a call to the callback interface 

   326      * method MBTEngSdpResultReceiver::ServiceSearchComplete() with error

   327      * code KErrAbort.

   328      *

   329      * @since S60 v3.2

   330      */

   331     IMPORT_C void CancelSearchRemoteDevice();

   332 

   333     /**

   334      * Retieves the information about the service UUIDs in the EIR data

   335      * of a device specified by a BD address.  

   336      * 

   337      * The EIR data got through this API is cached data and depends 

   338      * on a previous inquiry that has taken place. Moreover, a lagecy 

   339      * device (pre BT v2.1) doesn't have EIR data at all. Thus to ensure

   340      * wether a device supports a service or not at present, SDP query 

   341      * would still be the most reliable approach.

   342      *

   343      * When completed, the information are passed 

   344      * back to the client through the callback interface 

   345      * method MBTEngSdpResultReceiver::GetEirServiceUUIDsComplete().

   346      *

   347      * @since S60 v5.1

   348      * @param aAddr The BD address of the device.

   349      * @param aNameEntry The data structure in which the EIR data of the 

   350      *                   selected device will be stored

   351      *                   (passed back thorugh DeviceSearchComplete()).

   352      *                   TBluetoothNameRecordWrapper can be constructed from a 

   353      *                   TNameRecord instance for the purpose of parsing and 

   354      *                   getting Extended Inquiry Response tags.

   355      *                   Ownership of the data structure remains with the caller 

   356      *                   of this method.

   357      * @return KErrNone if sucessful, otherwise the error code 

   358      *         indicating the error situation.

   359      */

   360     IMPORT_C TInt GetEirServiceUUIDs( const TBTDevAddr& aAddr, TNameEntry* aNameEntry);    

   361     

   362     /**

   363      * Cancels an ongoing device service UUIDs retrieval.

   364      * 

   365      * @since S60 5.1

   366      */

   367     IMPORT_C void CancelGetEirServiceUUIDs();

   368     

   369     /**

   370      * Registers an service record in the local SDP database, based on 

   371      * a known service as defined in Bluetooth Engine resource file.

   372      * The instance of CBTEngDiscovery must be kept alive as long as

   373      * the service record is needed to be stored (deletion of CBTEngDiscovery

   374      * will remove all the records stored during the same session).

   375      *

   376      * @since S60 v3.2

   377      * @param aService UUID of the service to be registered.

   378      * @param aChannel The value of the channel of the ProtocolDescriptorList 

   379                        attribute (e.g. the RFCOMM channel), if applicable.

   380      * @param aHandle On return, contains the service record handle 

   381      *                identifying the created service record.

   382      * @return KErrNone if sucessful, otherwise the error code 

   383      *                  indicating the error situation.

   384      */

   385     IMPORT_C TInt RegisterSdpRecord( const TUUID& aService, const TUint aChannel, 

   386                                       TSdpServRecordHandle& aHandle );

   387 

   388     /**

   389      * Deletes a service record from the local SDP database that was 

   390      * previously registered by through this instance of CBTEngDiscovery.

   391      *

   392      * @since S60 v3.2

   393      * @param aHandle Handle to the SDP record to be deleted. Note that 

   394      *                this has to be a valid (existing) SDP record.

   395      * @return KErrNone if sucessful, otherwise the error code 

   396      *                  indicating the error situation.

   397      */

   398     IMPORT_C TInt DeleteSdpRecord( const TSdpServRecordHandle aHandle );

   399 

   400     /**

   401      * Sets the callback class for receiving SDP query results. This will

   402      * replace the current callback interface used to pass back the 

   403      * SDP query results.

   404      *

   405      * @since S60 v3.2

   406      * @param aNotifier Callback class to receive the SDP results.

   407      */

   408     IMPORT_C void SetNotifier( MBTEngSdpResultReceiver* aNotifier );

   409 

   410     /**

   411      * Starts an SDP query. The remote SDP database is searched 

   412      * for service records containing the specified UUID, the 

   413      * equivalent of an SDP ServiceSearch transaction.

   414      * When completed, record handles for all matching service records 

   415      * are passed back to the client through the callback interface 

   416      * method MBTEngSdpResultReceiver::ServiceSearchComplete().

   417      *

   418      * @since S60 v3.2

   419      * @param aAddr Target Bluetooth device address for the SDP query.

   420      * @param aService The UUID to search for.

   421      * @return KErrNone if sucessful, otherwise the error code 

   422      *                  indicating the error situation.

   423      */

   424     IMPORT_C TInt RemoteSdpQuery( const TBTDevAddr& aAddr, const TUUID& aService );

   425 

   426     /**

   427      * Starts an SDP query. A specific service record on the remote SDP 

   428      * database is queried for the value of a specified attribute, the 

   429      * equivalent of an SDP ServiceAttribute transaction.

   430      * When completed, the result is passed back to the client 

   431      * through the callback interface method 

   432      * MBTEngSdpResultReceiver::AttributeSearchComplete().

   433      *

   434      * @since S60 v3.2

   435      * @param aAddr Target Bluetooth device address for the SDP query.

   436      * @param aHandle The service record handle identifying the 

   437      *                service record to search the attribute from.

   438      * @param aAttrId The service attribute to search for.

   439      * @return KErrNone if sucessful, otherwise the error code 

   440      *                  indicating the error situation.

   441      */

   442     IMPORT_C TInt RemoteSdpQuery( const TBTDevAddr& aAddr, 

   443                                    const TSdpServRecordHandle aHandle, 

   444                                    const TSdpAttributeID aAttrId );

   445 

   446     /**

   447      * Starts an SDP query. The remote SDP database is searched for 

   448      * the value of a specified attribute in a service record 

   449      * containing the specified UUID, the equivalent of an 

   450      * SDP ServiceAttributeSearch transaction.

   451      * When completed, the results are passed back to the client 

   452      * through the callback interface method 

   453      * MBTEngSdpResultReceiver::ServiceAttributeSearchComplete().

   454      *

   455      * @since S60 v3.2

   456      * @param aAddr Target Bluetooth device address for the SDP query.

   457      * @param aService The UUID to search for.

   458      * @param aAttrId The service attribute to search for.

   459      * @return KErrNone if sucessful, otherwise the error code 

   460      *                  indicating the error situation.

   461      */

   462     IMPORT_C TInt RemoteSdpQuery( const TBTDevAddr& aAddr, const TUUID& aService, 

   463                                    const TSdpAttributeID aAttrId );

   464 

   465     /**

   466      * Starts an SDP query. The remote SDP database is searched for the 

   467      * value of the ProtocolDescriptorList attribute in a service record 

   468      * containing the specified UUID, the equivalent of an SDP 

   469      * ServiceAttributeSearch transaction with ProtocolDescriptorList as 

   470      * attribute. This can e.g. be used to search the remote RFCOMM channel.

   471      * When completed, the results are passed back to the client 

   472      * through the callback interface method 

   473      * MBTEngSdpResultReceiver::AttributeSearchComplete().

   474      *

   475      * @since S60 v3.2

   476      * @param aAddr Target Bluetooth device address for the SDP query.

   477      * @param aService The UUID to search for.

   478      * @return KErrNone if sucessful, otherwise the error code 

   479      *                  indicating the error situation.

   480      */

   481     IMPORT_C TInt RemoteProtocolChannelQuery( const TBTDevAddr& aAddr, 

   482                                                const TUUID& aService );

   483 

   484     /**

   485      * Cancels an ongoing SDP query.

   486      *

   487      * @since S60 v3.2

   488      */

   489     IMPORT_C void CancelRemoteSdpQuery();

   490 

   491     /**

   492     * Closes a remote SDP connection. The method should be called after

   493     * RemoteSdpQuery and RemoteProtocolChannelQuery methods are completed

   494     * and the CBTEngDiscovery obejct

   495     * is still kept alive.

   496     *

   497     * @since S60 v3.2

   498     */

   499     IMPORT_C void CBTEngDiscovery::CloseRemoteSdpConnection();

   500 

   501     /**

   502      * Static helper function to return the SDP element type 

   503      * of an indexed element in a list (DES or DEA).

   504      *

   505      * @param aResultArray The array containing the SDP attribute.

   506      * @param aIndex The position of the element to be parsed, relative 

   507      *               to zero (i.e. zero is the first element).

   508      * @param aType On return, contains the element type 

   509      *              of the element at position aIndex.

   510      * @return KErrNone if sucessful, 

   511      *         KErrEof if the index is greater than the number of items in the array.

   512      * @since S60 v3.2

   513      */

   514     IMPORT_C static TInt ParseNextSdpAttrValueType( RSdpResultArray& aResultArray, 

   515                                                      TInt aIndex, TSdpElementType& aType );

   516 

   517     /**

   518      * Static helper function to return the protocol channel number from the 

   519      * result array of a ServiceAttributeSearch. This value can be used to 

   520      * obtain e.g. the remote RFCOMM channel after a RemoteProtocolChannelQuery 

   521      * has completed.

   522      *

   523      * @param aResultArray The array containing the SDP attribute.

   524      * @param aType On return, contains the channel number.

   525      * @return KErrNone if sucessful, KErrArgument if the SDP attribute is not 

   526      *         of type ProtocolDescriptorList.

   527      * @since S60 v3.2

   528      */

   529     IMPORT_C static TInt ParseRfcommChannel( RSdpResultArray& aResultArray, 

   530                                               TInt& aChannel );

   531 

   532 private:

   533 

   534     /**

   535      * C++ default constructor

   536      *

   537      * @since S60 v3.2

   538      * @param aNotifier Pointer to callback interface that receives 

   539      *                  the SDP query results.

   540      */

   541     CBTEngDiscovery( MBTEngSdpResultReceiver* aNotifier );

   542 

   543     /**

   544      * Symbian 2nd-phase constructor

   545      *

   546      * @since S60 v3.2

   547      */

   548     void ConstructL();

   549 

   550     /**

   551      * Helper function to check that a valid session with 

   552      * the local SDP database exists.

   553      *

   554      * @since S60 v3.2

   555      * @return KErrNone if sucessful, otherwise the error code 

   556      *                  indicating the error situation.

   557      */

   558     TInt CheckSdpDbHandler();

   559 

   560     /**

   561      * Helper function to check that a valid handler of 

   562      * remote SDP queries exists.

   563      *

   564      * @since S60 v3.2

   565      * @return KErrNone if sucessful, 

   566      *         KErrNotReady if no SDP result notifier has been set,

   567      *          otherwise the error code indicating the error situation.

   568      */

   569     TInt CheckSdpQueryHandler();

   570 

   571 private: // data

   572 

   573     /**

   574      * Reference to SDP DB handler.

   575      * Own.

   576      */

   577     CBTEngSdpDbHandler* iSdpDbHandler;

   578 

   579     /**

   580      * Reference to handler of remote SDP queries.

   581      * Own.

   582      */

   583     CBTEngSdpQuery* iSdpQueryHandler;

   584 

   585     /**

   586      * Reference to handler of remote device searches.

   587      * Own.

   588      */

   589     CBTEngDeviceSearch* iDevSearchHandler;

   590 

   591     /**

   592      * Reference to receiver of results.

   593      * Not own.

   594      */

   595     MBTEngSdpResultReceiver* iResultNotifier;

   596 

   597     };

   598 

   599 #endif // BTENGDISCOVERY_H