/* mbed Microcontroller Library
* Copyright (c) 2006-2013 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef MBED_BLE_SERVICE_DISOVERY_H__
#define MBED_BLE_SERVICE_DISOVERY_H__
#include "UUID.h"
#include "ble/Gap.h"
#include "GattAttribute.h"
class DiscoveredService;
class DiscoveredCharacteristic;
/**
* @addtogroup ble
* @{
* @addtogroup gatt
* @{
* @addtogroup client
* @{
*/
/**
* Host callback types needed by the service discovery procedure.
*
* This class is also an interface that may be used in vendor port to model
* the service discovery process. This interface is not used in user code.
*
* @attention Implementing this interface is not a requirement for the
* implementation of the service discover process.
*/
class ServiceDiscovery {
public:
/**
* Service discovered event handler.
*
* The callback accepts a pointer to a DiscoveredService as parameter.
*
* @attention The argument passed to the callback may not persist after the
* callback invocation; therefore, the callbacks must make a shallow copy
* of the DiscoveredService passed as parameter to access its value beyond
* the callback scope.
*/
typedef FunctionPointerWithContext<const DiscoveredService *>
ServiceCallback_t;
/**
* Characteristic discovered event handler.
*
* The callback accepts a pointer to a DiscoveredCharacteristic as
* parameter.
*
* @attention The argument passed to the callback may not persist after the
* callback invocation; therefore, the callbacks must make a shallow copy
* of the DiscoveredCharacteristic passed as parameter to access its value
* beyond the callback scope.
*/
typedef FunctionPointerWithContext<const DiscoveredCharacteristic *>
CharacteristicCallback_t;
/**
* Service discovery ended event.
*
* The callback accepts a connection handle as parameter. This
* parameter is used to identify on which connection the service discovery
* process ended.
*/
typedef FunctionPointerWithContext<ble::connection_handle_t> TerminationCallback_t;
public:
/**
* Launch service discovery. Once launched, service discovery remains
* active with callbacks being issued back into the application for matching
* services or characteristics. isActive() can be used to determine status, and
* a termination callback (if set up) is invoked at the end. Service
* discovery can be terminated prematurely, if needed, using terminate().
*
* @param connectionHandle
* Handle for the connection with the peer.
* @param sc
* This is the application callback for a matching service. Taken as
* NULL by default. Note: service discovery may still be active
* when this callback is issued; calling asynchronous BLE-stack
* APIs from within this application callback might cause the
* stack to abort service discovery. If this becomes an issue, it
* may be better to make a local copy of the discoveredService and
* wait for service discovery to terminate before operating on the
* service.
* @param cc
* This is the application callback for a matching characteristic.
* Taken as NULL by default. Note: service discovery may still be
* active when this callback is issued; calling asynchronous
* BLE-stack APIs from within this application callback might cause
* the stack to abort service discovery. If this becomes an issue,
* it may be better to make a local copy of the discoveredCharacteristic
* and wait for service discovery to terminate before operating on the
* characteristic.
* @param matchingServiceUUID
* UUID-based filter for specifying a service in which the application is
* interested. By default, it is set as the wildcard UUID_UNKNOWN,
* in which case it matches all services. If characteristic-UUID
* filter (below) is set to the wildcard value, then a service
* callback is invoked for the matching service (or for every
* service if the service filter is a wildcard).
* @param matchingCharacteristicUUIDIn
* UUID-based filter for specifying a characteristic in which the application
* is interested. By default, it is set as the wildcard UUID_UKNOWN
* to match against any characteristic. If both service-UUID
* filter and characteristic-UUID filter are used with nonwildcard
* values, then only a single characteristic callback is
* invoked for the matching characteristic.
*
* @note Using wildcard values for both service-UUID and characteristic-
* UUID result in complete service discovery: callbacks being
* called for every service and characteristic.
*
* @note Providing NULL for the characteristic callback results in
* characteristic discovery being skipped for each matching
* service. This allows for an inexpensive method to discover only
* services.
*
* @return
* BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
*/
virtual ble_error_t launch(ble::connection_handle_t connectionHandle,
ServiceCallback_t sc = NULL,
CharacteristicCallback_t cc = NULL,
const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) = 0;
/**
* Check whether service-discovery is currently active.
*/
virtual bool isActive(void) const = 0;
/**
* Terminate an ongoing service discovery. This should result in an
* invocation of the TerminationCallback if service discovery is active.
*/
virtual void terminate(void) = 0;
/**
* Set up a callback to be invoked when service discovery is terminated.
*/
virtual void onTermination(TerminationCallback_t callback) = 0;
/**
* Clear all ServiceDiscovery state of the associated object.
*
* This function is meant to be overridden in the platform-specific
* subclass. Nevertheless, the subclass is only expected to reset its
* state and not the data held in ServiceDiscovery members. This is
* achieved by a call to ServiceDiscovery::reset() from the subclass'
* reset() implementation.
*
* @return BLE_ERROR_NONE on success.
*/
virtual ble_error_t reset(void) {
connHandle = 0;
matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
serviceCallback = NULL;
matchingCharacteristicUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
characteristicCallback = NULL;
return BLE_ERROR_NONE;
}
protected:
/**
* Connection handle as provided by the SoftDevice.
*/
ble::connection_handle_t connHandle;
/**
* UUID-based filter that specifies the service that the application is
* interested in.
*/
UUID matchingServiceUUID;
/**
* The registered callback handle for when a matching service is found
* during service-discovery.
*/
ServiceCallback_t serviceCallback;
/**
* UUID-based filter that specifies the characteristic that the
* application is interested in.
*/
UUID matchingCharacteristicUUID;
/**
* The registered callback handler for when a matching characteristic is
* found during service-discovery.
*/
CharacteristicCallback_t characteristicCallback;
};
/**
* @}
* @}
* @}
*/
#endif /* ifndef MBED_BLE_SERVICE_DISOVERY_H__ */
