Neil Johnson / microbit-ARMBand

Official Sheffield ARMBand micro:bit program

microbit/microbit-dal/BLE_API/ble/ServiceDiscovery.h@0:b9164b348919, 2016-10-17 (annotated)

Committer:
MrBedfordVan
Date:
Mon Oct 17 12:41:20 2016 +0000
Revision:
0:b9164b348919
Official Sheffield ARMBand Micro:bit program

Who changed what in which revision?

UserRevisionLine numberNew contents of line
MrBedfordVan 0:b9164b348919 1 /* mbed Microcontroller Library
MrBedfordVan 0:b9164b348919 2 * Copyright (c) 2006-2013 ARM Limited
MrBedfordVan 0:b9164b348919 3 *
MrBedfordVan 0:b9164b348919 4 * Licensed under the Apache License, Version 2.0 (the "License");
MrBedfordVan 0:b9164b348919 5 * you may not use this file except in compliance with the License.
MrBedfordVan 0:b9164b348919 6 * You may obtain a copy of the License at
MrBedfordVan 0:b9164b348919 7 *
MrBedfordVan 0:b9164b348919 8 * http://www.apache.org/licenses/LICENSE-2.0
MrBedfordVan 0:b9164b348919 9 *
MrBedfordVan 0:b9164b348919 10 * Unless required by applicable law or agreed to in writing, software
MrBedfordVan 0:b9164b348919 11 * distributed under the License is distributed on an "AS IS" BASIS,
MrBedfordVan 0:b9164b348919 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
MrBedfordVan 0:b9164b348919 13 * See the License for the specific language governing permissions and
MrBedfordVan 0:b9164b348919 14 * limitations under the License.
MrBedfordVan 0:b9164b348919 15 */
MrBedfordVan 0:b9164b348919 16
MrBedfordVan 0:b9164b348919 17 #ifndef __SERVICE_DISOVERY_H__
MrBedfordVan 0:b9164b348919 18 #define __SERVICE_DISOVERY_H__
MrBedfordVan 0:b9164b348919 19
MrBedfordVan 0:b9164b348919 20 #include "UUID.h"
MrBedfordVan 0:b9164b348919 21 #include "Gap.h"
MrBedfordVan 0:b9164b348919 22 #include "GattAttribute.h"
MrBedfordVan 0:b9164b348919 23
MrBedfordVan 0:b9164b348919 24 class DiscoveredService;
MrBedfordVan 0:b9164b348919 25 class DiscoveredCharacteristic;
MrBedfordVan 0:b9164b348919 26
MrBedfordVan 0:b9164b348919 27 class ServiceDiscovery {
MrBedfordVan 0:b9164b348919 28 public:
MrBedfordVan 0:b9164b348919 29 /*
MrBedfordVan 0:b9164b348919 30 * Exposed application callback types.
MrBedfordVan 0:b9164b348919 31 */
MrBedfordVan 0:b9164b348919 32
MrBedfordVan 0:b9164b348919 33 /**
MrBedfordVan 0:b9164b348919 34 * Callback type for when a matching service is found during service-
MrBedfordVan 0:b9164b348919 35 * discovery. The receiving function is passed in a pointer to a
MrBedfordVan 0:b9164b348919 36 * DiscoveredService object, which will remain valid for the lifetime of the
MrBedfordVan 0:b9164b348919 37 * callback. Memory for this object is owned by the BLE_API eventing
MrBedfordVan 0:b9164b348919 38 * framework. The application can safely make a persistent shallow-copy of
MrBedfordVan 0:b9164b348919 39 * this object to work with the service beyond the callback.
MrBedfordVan 0:b9164b348919 40 */
MrBedfordVan 0:b9164b348919 41 typedef FunctionPointerWithContext<const DiscoveredService *> ServiceCallback_t;
MrBedfordVan 0:b9164b348919 42
MrBedfordVan 0:b9164b348919 43 /**
MrBedfordVan 0:b9164b348919 44 * Callback type for when a matching characteristic is found during service-
MrBedfordVan 0:b9164b348919 45 * discovery. The receiving function is passed in a pointer to a
MrBedfordVan 0:b9164b348919 46 * DiscoveredCharacteristic object, which will remain valid for the lifetime
MrBedfordVan 0:b9164b348919 47 * of the callback. Memory for this object is owned by the BLE_API eventing
MrBedfordVan 0:b9164b348919 48 * framework. The application can safely make a persistent shallow-copy of
MrBedfordVan 0:b9164b348919 49 * this object to work with the characteristic beyond the callback.
MrBedfordVan 0:b9164b348919 50 */
MrBedfordVan 0:b9164b348919 51 typedef FunctionPointerWithContext<const DiscoveredCharacteristic *> CharacteristicCallback_t;
MrBedfordVan 0:b9164b348919 52
MrBedfordVan 0:b9164b348919 53 /**
MrBedfordVan 0:b9164b348919 54 * Callback type for when serviceDiscovery terminates.
MrBedfordVan 0:b9164b348919 55 */
MrBedfordVan 0:b9164b348919 56 typedef FunctionPointerWithContext<Gap::Handle_t> TerminationCallback_t;
MrBedfordVan 0:b9164b348919 57
MrBedfordVan 0:b9164b348919 58 public:
MrBedfordVan 0:b9164b348919 59 /**
MrBedfordVan 0:b9164b348919 60 * Launch service discovery. Once launched, service discovery will remain
MrBedfordVan 0:b9164b348919 61 * active with callbacks being issued back into the application for matching
MrBedfordVan 0:b9164b348919 62 * services or characteristics. isActive() can be used to determine status, and
MrBedfordVan 0:b9164b348919 63 * a termination callback (if set up) will be invoked at the end. Service
MrBedfordVan 0:b9164b348919 64 * discovery can be terminated prematurely, if needed, using terminate().
MrBedfordVan 0:b9164b348919 65 *
MrBedfordVan 0:b9164b348919 66 * @param connectionHandle
MrBedfordVan 0:b9164b348919 67 * Handle for the connection with the peer.
MrBedfordVan 0:b9164b348919 68 * @param sc
MrBedfordVan 0:b9164b348919 69 * This is the application callback for a matching service. Taken as
MrBedfordVan 0:b9164b348919 70 * NULL by default. Note: service discovery may still be active
MrBedfordVan 0:b9164b348919 71 * when this callback is issued; calling asynchronous BLE-stack
MrBedfordVan 0:b9164b348919 72 * APIs from within this application callback might cause the
MrBedfordVan 0:b9164b348919 73 * stack to abort service discovery. If this becomes an issue, it
MrBedfordVan 0:b9164b348919 74 * may be better to make a local copy of the discoveredService and
MrBedfordVan 0:b9164b348919 75 * wait for service discovery to terminate before operating on the
MrBedfordVan 0:b9164b348919 76 * service.
MrBedfordVan 0:b9164b348919 77 * @param cc
MrBedfordVan 0:b9164b348919 78 * This is the application callback for a matching characteristic.
MrBedfordVan 0:b9164b348919 79 * Taken as NULL by default. Note: service discovery may still be
MrBedfordVan 0:b9164b348919 80 * active when this callback is issued; calling asynchronous
MrBedfordVan 0:b9164b348919 81 * BLE-stack APIs from within this application callback might cause
MrBedfordVan 0:b9164b348919 82 * the stack to abort service discovery. If this becomes an issue,
MrBedfordVan 0:b9164b348919 83 * it may be better to make a local copy of the discoveredCharacteristic
MrBedfordVan 0:b9164b348919 84 * and wait for service discovery to terminate before operating on the
MrBedfordVan 0:b9164b348919 85 * characteristic.
MrBedfordVan 0:b9164b348919 86 * @param matchingServiceUUID
MrBedfordVan 0:b9164b348919 87 * UUID-based filter for specifying a service in which the application is
MrBedfordVan 0:b9164b348919 88 * interested. By default it is set as the wildcard UUID_UNKNOWN,
MrBedfordVan 0:b9164b348919 89 * in which case it matches all services. If characteristic-UUID
MrBedfordVan 0:b9164b348919 90 * filter (below) is set to the wildcard value, then a service
MrBedfordVan 0:b9164b348919 91 * callback will be invoked for the matching service (or for every
MrBedfordVan 0:b9164b348919 92 * service if the service filter is a wildcard).
MrBedfordVan 0:b9164b348919 93 * @param matchingCharacteristicUUIDIn
MrBedfordVan 0:b9164b348919 94 * UUID-based filter for specifying a characteristic in which the application
MrBedfordVan 0:b9164b348919 95 * is interested. By default it is set as the wildcard UUID_UKNOWN
MrBedfordVan 0:b9164b348919 96 * to match against any characteristic. If both service-UUID
MrBedfordVan 0:b9164b348919 97 * filter and characteristic-UUID filter are used with non-wildcard
MrBedfordVan 0:b9164b348919 98 * values, then only a single characteristic callback is
MrBedfordVan 0:b9164b348919 99 * invoked for the matching characteristic.
MrBedfordVan 0:b9164b348919 100 *
MrBedfordVan 0:b9164b348919 101 * @note Using wildcard values for both service-UUID and characteristic-
MrBedfordVan 0:b9164b348919 102 * UUID will result in complete service discovery: callbacks being
MrBedfordVan 0:b9164b348919 103 * called for every service and characteristic.
MrBedfordVan 0:b9164b348919 104 *
MrBedfordVan 0:b9164b348919 105 * @note Providing NULL for the characteristic callback will result in
MrBedfordVan 0:b9164b348919 106 * characteristic discovery being skipped for each matching
MrBedfordVan 0:b9164b348919 107 * service. This allows for an inexpensive method to discover only
MrBedfordVan 0:b9164b348919 108 * services.
MrBedfordVan 0:b9164b348919 109 *
MrBedfordVan 0:b9164b348919 110 * @return
MrBedfordVan 0:b9164b348919 111 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
MrBedfordVan 0:b9164b348919 112 */
MrBedfordVan 0:b9164b348919 113 virtual ble_error_t launch(Gap::Handle_t connectionHandle,
MrBedfordVan 0:b9164b348919 114 ServiceCallback_t sc = NULL,
MrBedfordVan 0:b9164b348919 115 CharacteristicCallback_t cc = NULL,
MrBedfordVan 0:b9164b348919 116 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
MrBedfordVan 0:b9164b348919 117 const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) = 0;
MrBedfordVan 0:b9164b348919 118
MrBedfordVan 0:b9164b348919 119 /**
MrBedfordVan 0:b9164b348919 120 * Is service-discovery currently active?
MrBedfordVan 0:b9164b348919 121 */
MrBedfordVan 0:b9164b348919 122 virtual bool isActive(void) const = 0;
MrBedfordVan 0:b9164b348919 123
MrBedfordVan 0:b9164b348919 124 /**
MrBedfordVan 0:b9164b348919 125 * Terminate an ongoing service discovery. This should result in an
MrBedfordVan 0:b9164b348919 126 * invocation of the TerminationCallback if service discovery is active.
MrBedfordVan 0:b9164b348919 127 */
MrBedfordVan 0:b9164b348919 128 virtual void terminate(void) = 0;
MrBedfordVan 0:b9164b348919 129
MrBedfordVan 0:b9164b348919 130 /**
MrBedfordVan 0:b9164b348919 131 * Set up a callback to be invoked when service discovery is terminated.
MrBedfordVan 0:b9164b348919 132 */
MrBedfordVan 0:b9164b348919 133 virtual void onTermination(TerminationCallback_t callback) = 0;
MrBedfordVan 0:b9164b348919 134
MrBedfordVan 0:b9164b348919 135 /**
MrBedfordVan 0:b9164b348919 136 * Clear all ServiceDiscovery state of the associated object.
MrBedfordVan 0:b9164b348919 137 *
MrBedfordVan 0:b9164b348919 138 * This function is meant to be overridden in the platform-specific
MrBedfordVan 0:b9164b348919 139 * sub-class. Nevertheless, the sub-class is only expected to reset its
MrBedfordVan 0:b9164b348919 140 * state and not the data held in ServiceDiscovery members. This shall be
MrBedfordVan 0:b9164b348919 141 * achieved by a call to ServiceDiscovery::reset() from the sub-class'
MrBedfordVan 0:b9164b348919 142 * reset() implementation.
MrBedfordVan 0:b9164b348919 143 *
MrBedfordVan 0:b9164b348919 144 * @return BLE_ERROR_NONE on success.
MrBedfordVan 0:b9164b348919 145 */
MrBedfordVan 0:b9164b348919 146 virtual ble_error_t reset(void) {
MrBedfordVan 0:b9164b348919 147 connHandle = 0;
MrBedfordVan 0:b9164b348919 148 matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
MrBedfordVan 0:b9164b348919 149 serviceCallback = NULL;
MrBedfordVan 0:b9164b348919 150 matchingCharacteristicUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
MrBedfordVan 0:b9164b348919 151 characteristicCallback = NULL;
MrBedfordVan 0:b9164b348919 152
MrBedfordVan 0:b9164b348919 153 return BLE_ERROR_NONE;
MrBedfordVan 0:b9164b348919 154 }
MrBedfordVan 0:b9164b348919 155
MrBedfordVan 0:b9164b348919 156 protected:
MrBedfordVan 0:b9164b348919 157 Gap::Handle_t connHandle; /**< Connection handle as provided by the SoftDevice. */
MrBedfordVan 0:b9164b348919 158 UUID matchingServiceUUID;
MrBedfordVan 0:b9164b348919 159 ServiceCallback_t serviceCallback;
MrBedfordVan 0:b9164b348919 160 UUID matchingCharacteristicUUID;
MrBedfordVan 0:b9164b348919 161 CharacteristicCallback_t characteristicCallback;
MrBedfordVan 0:b9164b348919 162 };
MrBedfordVan 0:b9164b348919 163
MrBedfordVan 0:b9164b348919 164 #endif // ifndef __SERVICE_DISOVERY_H__