Mbed OS Reference | ServiceDiscovery.h Source File

 /* mbed Microcontroller Library
  * Copyright (c) 2006-2020 ARM Limited
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * 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 "ble/common/blecommon.h"
 #include "ble/common/UUID.h"
 #include "ble/gatt/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 = nullptr,
                                CharacteristicCallback_t  cc = nullptr,
                                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() const = 0;
 
     /**
      * Terminate an ongoing service discovery. This should result in an
      * invocation of the TerminationCallback if service discovery is active.
      */
     virtual void        terminate() = 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() {
         connHandle                 = 0;
         matchingServiceUUID        = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
         serviceCallback            = nullptr;
         matchingCharacteristicUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
         characteristicCallback     = nullptr;
 
         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__ */
Important Information for this Arm website
