/*

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

*                and local SDP database functionality.

*

*/

#ifndef BTENGDISCOVERY_H

#define BTENGDISCOVERY_H

#include <btsdp.h>

#include <btdevice.h>

class CBTEngSdpDbHandler;

class CBTEngSdpQuery;

class CBTEngDeviceSearch;

class TBTEngSdpAttrValue;

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

typedef RArray<TSdpServRecordHandle> RSdpRecHandleArray;

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

typedef RArray<TBTEngSdpAttrValue> RSdpResultArray;

/**

 *  class TBTEngSdpResult

 *

 *  Data structure for passing SDP results to the client.

 *

 *  @lib btengdiscovery.lib

 *  @since S60 v3.2

 */

class TBTEngSdpAttrValue

    {

public:

    /**

     * Data structure containing the SDP attribute value.

     * Note: the member varaible containing the data is dependent 

     * on the data type attribute of the parent class.

     */

    class TSdpAttrValue

        {

    public:

        /**

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

         */

        TInt iValNumeric;

        /**

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

         */

        TPtrC8 iValString;

        };

public: // data

    /**

     * Attribute identifier of this attribute.

     */

    TSdpAttributeID iAttrId;

    /**

     * Attribute type of this attribute.

     */

    TSdpElementType iAttrType;

    /**

     * Attribute value of this attribute.

     */

    TSdpAttrValue iAttrValue;

    };

/**

 *  Class CBTEngDiscovery

 *

 *  Callback interface for receiving results from queries 

 *  of remote SDP databases.

 *  Clients that make SDP queries through CBTEngDiscovery 

 *  must implement this interface to handle the results.

 *

 *  @lib btengdiscovery.lib

 *  @since S60 v3.2

 */

class MBTEngSdpResultReceiver

    {

public:

    /**

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

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

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

     * all the results to the caller at once.

     *

     * @since S60 v3.2

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

     *                Note: the array will not be available anymore after 

     *                this method returns.

     * @param aTotalRecordsCount The total number of records returned.

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

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

     *             KErrCouldNotConnect and KErrCouldDisconnected in case of 

     *             Bluetooth connection errors; otherwise one of the 

     *             system-wide error codes.

     */

    virtual void ServiceSearchComplete( const RSdpRecHandleArray& aResult, 

                                         TUint aTotalRecordsCount, TInt aErr ) = 0;

    /**

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

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

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

     * all the results to the caller at once.

     *

     * @since S60 v3.2

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

     * @param aAttr Array containing the attribute that matches the 

     *              requested attribute.

     *              Note: the array will not be available anymore after 

     *              this method returns.

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

     *             sucessful, KErrEof if the requested attribute was not 

     *             contained in the specified service record, 

     *             KErrCouldNotConnect and KErrCouldDisconnected in case of 

     *             Bluetooth connection errors; otherwise one of the 

     *             system-wide error codes.

     */

    virtual void AttributeSearchComplete( TSdpServRecordHandle aHandle, 

                                           const RSdpResultArray& aAttr, 

                                           TInt aErr ) = 0;

    /**

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

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

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

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

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

     * search has completed. The corresponding CBTEngDiscovery instance

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

     * has completed (KErrEof is received). 

     *

     * @since S60 v3.2

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

     * @param aAttr Array containing the attribute that matches the 

     *              requested attribute.

     *              Note: the array will not be available anymore after 

     *              this method returns.

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

     *             sucessful and more results follow, KErrEof indicates that 

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

     *             was found), KErrCouldNotConnect and KErrCouldDisconnected 

     *             in case of Bluetooth connection errors; otherwise one of 

     *             the system-wide error codes.

     */

    virtual void ServiceAttributeSearchComplete( TSdpServRecordHandle aHandle, 

                                                  const RSdpResultArray& aAttr, 

                                                  TInt aErr ) = 0;

    /**

     * Provides notification of the result of the discovery of nearby 

     * Bluetooth devices.

     *

     * @since S60 v3.2

     * @param aDevice The data structure encapsulates information 

     *                about the selected device. Ownership of the data 

     *                structure has not been transfered and is still with

     *                the API client.

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

     *             sucessful, KErrCancel if the user cancelled the 

     *             dialog, KErrAbort if CBTEngDiscovery::CancelSearchRemoteDevice

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

     */

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

    /**

     * Provides notification of the result of the discovery of nearby 

     * Bluetooth devices and EIR data.

     *

     * @since S60 v5.1

     * @param aDevice The data structure encapsulates information 

     *                about the selected device. 

     *                Ownership of the data structure has not been transfered and

     *                is still with the API client.

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

     *                Ownership of the data structure has not been transfered and

     *                is still with the API client. 

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

     *             sucessful, KErrCancel if the user cancelled the 

     *             dialog, KErrAbort if CBTEngDiscovery::CancelSearchRemoteDevice

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

     */

    IMPORT_C virtual void DeviceSearchComplete( CBTDevice* aDevice, 

            TNameEntry* aNameEntry, TInt aErr );

    /**

     * Provides notification of the result of service UUIDs retrieval.

     *

     * @since S60 v5.1

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

     *                    Ownership of the data structure has not been transfered and

     *                    is still with the API client. 

     * @param aErr KErrNone if sucessful;

     *             otherwise one of the system-wide error codes.

     */

    IMPORT_C virtual void GetEirServiceUUIDsComplete( 

            TNameEntry* aNameEntry, TInt aErr );

    };

/**

 *  Class CBTEngDiscovery

 *

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

 *  BluetoothT SDP interface, for registration of SDP records in 

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

 *  Additionally, functionality for searching for and pairing with 

 *  remote Bluetooth devices.

 *

 *  @lib btengdiscovery.lib

 *  @since S60 v3.2

 */

class CBTEngDiscovery : public CBase

    {

public:

    /**

     * Two-phase constructor

     *

     * @since S60 v3.2

     * @param aNotifier Pointer to callback interface that receives 

     *                  the SDP query results.

     * @return Pointer to the constructed CBTEngDiscovery object.

     */

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

    /**

     * Two-phase constructor

     *

     * @since S60 v3.2

     * @param aNotifier Pointer to callback interface that receives 

     *                  the SDP query results.

     * @return Pointer to the constructed CBTEngDiscovery object.

     */

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

    /**

     * Destructor

     */

    virtual ~CBTEngDiscovery();

    /**

     * Launches to notifier for discovering nearby Bluetooth devices and 

     * user selection of one device.

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

     * through the callback interface 

     * method MBTEngSdpResultReceiver::DeviceSearchComplete().

     *

     * @since S60 v3.2

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

     *                (passed back thorugh DeviceSearchComplete()).

     *                Ownership of the data structure remains with the caller 

     *                of this method.

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

     *                      results according to the specified major service 

     *                      class field of the CoD. The default value 

     *                      is zero and will not apply any filter.

     * @return KErrNone if sucessful, otherwise the error code 

     *         indicating the error situation.

     */

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

    /**

     * Launches to notifier for discovering nearby Bluetooth devices and 

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

     * UUIDs in the EIR data of the selected device.

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

     * back to the client through the callback interface 

     * method MBTEngSdpResultReceiver::DeviceSearchComplete().

     * 

     * @since S60 v5.1

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

     *                (passed back thorugh DeviceSearchComplete()).

     *                Ownership of the data structure remains with the caller 

     *                of this method.

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

     *                   selected device will be stored

     *                   (passed back thorugh DeviceSearchComplete()).

     *                   TBluetoothNameRecordWrapper can be constructed from a 

     *                   TNameRecord instance for the purpose of parsing and 

     *                   getting Extended Inquiry Response tags.

     *                   Ownership of the data structure remains with the caller 

     *                   of this method.

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

     *                      results according to the specified major service 

     *                      class field of the CoD. The default value 

     *                      is zero and will not apply any filter.

     * @return KErrNone if sucessful, otherwise the error code 

     *         indicating the error situation.

     */

    IMPORT_C TInt SearchRemoteDevice( CBTDevice* aDevice, 

            TNameEntry* aNameEntry, TUint aServiceClass = 0 );

    /**

     * Cancels an ongoing search for nearby Bluetooth devices.

     * This results in a call to the callback interface 

     * method MBTEngSdpResultReceiver::ServiceSearchComplete() with error

     * code KErrAbort.

     *

     * @since S60 v3.2

     */

    IMPORT_C void CancelSearchRemoteDevice();

    /**

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

     * of a device specified by a BD address.  

     * 

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

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

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

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

     * would still be the most reliable approach.

     *

     * When completed, the information are passed 

     * back to the client through the callback interface 

     * method MBTEngSdpResultReceiver::GetEirServiceUUIDsComplete().

     *

     * @since S60 v5.1

     * @param aAddr The BD address of the device.

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

     *                   selected device will be stored

     *                   (passed back thorugh DeviceSearchComplete()).

     *                   TBluetoothNameRecordWrapper can be constructed from a 

     *                   TNameRecord instance for the purpose of parsing and 

     *                   getting Extended Inquiry Response tags.

     *                   Ownership of the data structure remains with the caller 

     *                   of this method.

     * @return KErrNone if sucessful, otherwise the error code 

     *         indicating the error situation.

     */

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

    /**

     * Cancels an ongoing device service UUIDs retrieval.

     * 

     * @since S60 5.1

     */

    IMPORT_C void CancelGetEirServiceUUIDs();

    /**

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

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

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

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

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

     *

     * @since S60 v3.2

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

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

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

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

     *                identifying the created service record.

     * @return KErrNone if sucessful, otherwise the error code 

     *                  indicating the error situation.

     */

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

                                      TSdpServRecordHandle& aHandle );

    /**

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

     * previously registered by through this instance of CBTEngDiscovery.

     *

     * @since S60 v3.2

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

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

     * @return KErrNone if sucessful, otherwise the error code 

     *                  indicating the error situation.

     */

    IMPORT_C TInt DeleteSdpRecord( const TSdpServRecordHandle aHandle );

    /**

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

     * replace the current callback interface used to pass back the 

     * SDP query results.

     *

     * @since S60 v3.2

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

     */

    IMPORT_C void SetNotifier( MBTEngSdpResultReceiver* aNotifier );

    /**

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

     * for service records containing the specified UUID, the 

     * equivalent of an SDP ServiceSearch transaction.

     * When completed, record handles for all matching service records 

     * are passed back to the client through the callback interface 

     * method MBTEngSdpResultReceiver::ServiceSearchComplete().

     *

     * @since S60 v3.2

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

     * @param aService The UUID to search for.

     * @return KErrNone if sucessful, otherwise the error code 

     *                  indicating the error situation.

     */

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

    /**

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

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

     * equivalent of an SDP ServiceAttribute transaction.

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

     * through the callback interface method 

     * MBTEngSdpResultReceiver::AttributeSearchComplete().

     *

     * @since S60 v3.2

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

     * @param aHandle The service record handle identifying the 

     *                service record to search the attribute from.

     * @param aAttrId The service attribute to search for.

     * @return KErrNone if sucessful, otherwise the error code 

     *                  indicating the error situation.

     */

    IMPORT_C TInt RemoteSdpQuery( const TBTDevAddr& aAddr, 

                                   const TSdpServRecordHandle aHandle, 

                                   const TSdpAttributeID aAttrId );

    /**

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

     * the value of a specified attribute in a service record 

     * containing the specified UUID, the equivalent of an 

     * SDP ServiceAttributeSearch transaction.

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

     * through the callback interface method 

     * MBTEngSdpResultReceiver::ServiceAttributeSearchComplete().

     *

     * @since S60 v3.2

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

     * @param aService The UUID to search for.

     * @param aAttrId The service attribute to search for.

     * @return KErrNone if sucessful, otherwise the error code 

     *                  indicating the error situation.

     */

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

                                   const TSdpAttributeID aAttrId );

    /**

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

     * value of the ProtocolDescriptorList attribute in a service record 

     * containing the specified UUID, the equivalent of an SDP 

     * ServiceAttributeSearch transaction with ProtocolDescriptorList as 

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

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

     * through the callback interface method 

     * MBTEngSdpResultReceiver::AttributeSearchComplete().

     *

     * @since S60 v3.2

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

     * @param aService The UUID to search for.

     * @return KErrNone if sucessful, otherwise the error code 

     *                  indicating the error situation.

     */

    IMPORT_C TInt RemoteProtocolChannelQuery( const TBTDevAddr& aAddr, 

                                               const TUUID& aService );

    /**

     * Cancels an ongoing SDP query.

     *

     * @since S60 v3.2

     */

    IMPORT_C void CancelRemoteSdpQuery();

    /**

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

    * RemoteSdpQuery and RemoteProtocolChannelQuery methods are completed

    * and the CBTEngDiscovery obejct

    * is still kept alive.

    *

    * @since S60 v3.2

    */

    /**

     * Static helper function to return the SDP element type 

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

     *

     * @param aResultArray The array containing the SDP attribute.

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

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

     * @param aType On return, contains the element type 

     *              of the element at position aIndex.

     * @return KErrNone if sucessful, 

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

     * @since S60 v3.2

     */

    IMPORT_C static TInt ParseNextSdpAttrValueType( RSdpResultArray& aResultArray, 

                                                     TInt aIndex, TSdpElementType& aType );

    /**

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

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

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

     * has completed.

     *

     * @param aResultArray The array containing the SDP attribute.

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

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

     *         of type ProtocolDescriptorList.

     * @since S60 v3.2

     */