--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/btservices_plat/bluetooth_engine_discovery_api/inc/btengdiscovery.h Mon Jan 18 20:28:57 2010 +0200
@@ -0,0 +1,599 @@
+/*
+* 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
+ */
+ IMPORT_C void CBTEngDiscovery::CloseRemoteSdpConnection();
+
+ /**
+ * 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
+ */
+ IMPORT_C static TInt ParseRfcommChannel( RSdpResultArray& aResultArray,
+ TInt& aChannel );
+
+private:
+
+ /**
+ * C++ default constructor
+ *
+ * @since S60 v3.2
+ * @param aNotifier Pointer to callback interface that receives
+ * the SDP query results.
+ */
+ CBTEngDiscovery( MBTEngSdpResultReceiver* aNotifier );
+
+ /**
+ * Symbian 2nd-phase constructor
+ *
+ * @since S60 v3.2
+ */
+ void ConstructL();
+
+ /**
+ * Helper function to check that a valid session with
+ * the local SDP database exists.
+ *
+ * @since S60 v3.2
+ * @return KErrNone if sucessful, otherwise the error code
+ * indicating the error situation.
+ */
+ TInt CheckSdpDbHandler();
+
+ /**
+ * Helper function to check that a valid handler of
+ * remote SDP queries exists.
+ *
+ * @since S60 v3.2
+ * @return KErrNone if sucessful,
+ * KErrNotReady if no SDP result notifier has been set,
+ * otherwise the error code indicating the error situation.
+ */
+ TInt CheckSdpQueryHandler();
+
+private: // data
+
+ /**
+ * Reference to SDP DB handler.
+ * Own.
+ */
+ CBTEngSdpDbHandler* iSdpDbHandler;
+
+ /**
+ * Reference to handler of remote SDP queries.
+ * Own.
+ */
+ CBTEngSdpQuery* iSdpQueryHandler;
+
+ /**
+ * Reference to handler of remote device searches.
+ * Own.
+ */
+ CBTEngDeviceSearch* iDevSearchHandler;
+
+ /**
+ * Reference to receiver of results.
+ * Not own.
+ */
+ MBTEngSdpResultReceiver* iResultNotifier;
+
+ };
+
+#endif // BTENGDISCOVERY_H