Marco Zecchini / Mbed OS Example_RTOS

Rtos API example

mbed-os/features/FEATURE_BLE/ble/ServiceDiscovery.h@0:9fca2b23d0ba, 2019-02-23 (annotated)

Committer:
marcozecchini
Date:
Sat Feb 23 12:13:36 2019 +0000
Revision:
0:9fca2b23d0ba
final commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
marcozecchini 0:9fca2b23d0ba 1 /* mbed Microcontroller Library
marcozecchini 0:9fca2b23d0ba 2 * Copyright (c) 2006-2013 ARM Limited
marcozecchini 0:9fca2b23d0ba 3 *
marcozecchini 0:9fca2b23d0ba 4 * Licensed under the Apache License, Version 2.0 (the "License");
marcozecchini 0:9fca2b23d0ba 5 * you may not use this file except in compliance with the License.
marcozecchini 0:9fca2b23d0ba 6 * You may obtain a copy of the License at
marcozecchini 0:9fca2b23d0ba 7 *
marcozecchini 0:9fca2b23d0ba 8 * http://www.apache.org/licenses/LICENSE-2.0
marcozecchini 0:9fca2b23d0ba 9 *
marcozecchini 0:9fca2b23d0ba 10 * Unless required by applicable law or agreed to in writing, software
marcozecchini 0:9fca2b23d0ba 11 * distributed under the License is distributed on an "AS IS" BASIS,
marcozecchini 0:9fca2b23d0ba 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
marcozecchini 0:9fca2b23d0ba 13 * See the License for the specific language governing permissions and
marcozecchini 0:9fca2b23d0ba 14 * limitations under the License.
marcozecchini 0:9fca2b23d0ba 15 */
marcozecchini 0:9fca2b23d0ba 16
marcozecchini 0:9fca2b23d0ba 17 #ifndef MBED_BLE_SERVICE_DISOVERY_H__
marcozecchini 0:9fca2b23d0ba 18 #define MBED_BLE_SERVICE_DISOVERY_H__
marcozecchini 0:9fca2b23d0ba 19
marcozecchini 0:9fca2b23d0ba 20 #include "UUID.h"
marcozecchini 0:9fca2b23d0ba 21 #include "Gap.h"
marcozecchini 0:9fca2b23d0ba 22 #include "GattAttribute.h"
marcozecchini 0:9fca2b23d0ba 23
marcozecchini 0:9fca2b23d0ba 24 class DiscoveredService;
marcozecchini 0:9fca2b23d0ba 25 class DiscoveredCharacteristic;
marcozecchini 0:9fca2b23d0ba 26
marcozecchini 0:9fca2b23d0ba 27 /**
marcozecchini 0:9fca2b23d0ba 28 * @addtogroup ble
marcozecchini 0:9fca2b23d0ba 29 * @{
marcozecchini 0:9fca2b23d0ba 30 * @addtogroup gatt
marcozecchini 0:9fca2b23d0ba 31 * @{
marcozecchini 0:9fca2b23d0ba 32 * @addtogroup client
marcozecchini 0:9fca2b23d0ba 33 * @{
marcozecchini 0:9fca2b23d0ba 34 */
marcozecchini 0:9fca2b23d0ba 35
marcozecchini 0:9fca2b23d0ba 36 /**
marcozecchini 0:9fca2b23d0ba 37 * Host callback types needed by the service discovery procedure.
marcozecchini 0:9fca2b23d0ba 38 *
marcozecchini 0:9fca2b23d0ba 39 * This class is also an interface that may be used in vendor port to model
marcozecchini 0:9fca2b23d0ba 40 * the service discovery process. This interface is not used in user code.
marcozecchini 0:9fca2b23d0ba 41 *
marcozecchini 0:9fca2b23d0ba 42 * @important Implementing this interface is not a requirement for the
marcozecchini 0:9fca2b23d0ba 43 * implementation of the service discover process.
marcozecchini 0:9fca2b23d0ba 44 */
marcozecchini 0:9fca2b23d0ba 45 class ServiceDiscovery {
marcozecchini 0:9fca2b23d0ba 46 public:
marcozecchini 0:9fca2b23d0ba 47 /**
marcozecchini 0:9fca2b23d0ba 48 * Service discovered event handler.
marcozecchini 0:9fca2b23d0ba 49 *
marcozecchini 0:9fca2b23d0ba 50 * The callback accepts a pointer to a DiscoveredService as parameter.
marcozecchini 0:9fca2b23d0ba 51 *
marcozecchini 0:9fca2b23d0ba 52 * @important The argument passed to the callback may not persist after the
marcozecchini 0:9fca2b23d0ba 53 * callback invocation; therefore, the callbacks must make a shallow copy
marcozecchini 0:9fca2b23d0ba 54 * of the DiscoveredService passed as parameter to access its value beyond
marcozecchini 0:9fca2b23d0ba 55 * the callback scope.
marcozecchini 0:9fca2b23d0ba 56 */
marcozecchini 0:9fca2b23d0ba 57 typedef FunctionPointerWithContext<const DiscoveredService *>
marcozecchini 0:9fca2b23d0ba 58 ServiceCallback_t;
marcozecchini 0:9fca2b23d0ba 59
marcozecchini 0:9fca2b23d0ba 60 /**
marcozecchini 0:9fca2b23d0ba 61 * Characteristic discovered event handler.
marcozecchini 0:9fca2b23d0ba 62 *
marcozecchini 0:9fca2b23d0ba 63 * The callback accepts a pointer to a DiscoveredCharacteristic as
marcozecchini 0:9fca2b23d0ba 64 * parameter.
marcozecchini 0:9fca2b23d0ba 65 *
marcozecchini 0:9fca2b23d0ba 66 * @important The argument passed to the callback may not persist after the
marcozecchini 0:9fca2b23d0ba 67 * callback invocation; therefore, the callbacks must make a shallow copy
marcozecchini 0:9fca2b23d0ba 68 * of the DiscoveredCharacteristic passed as parameter to access its value
marcozecchini 0:9fca2b23d0ba 69 * beyond the callback scope.
marcozecchini 0:9fca2b23d0ba 70 */
marcozecchini 0:9fca2b23d0ba 71 typedef FunctionPointerWithContext<const DiscoveredCharacteristic *>
marcozecchini 0:9fca2b23d0ba 72 CharacteristicCallback_t;
marcozecchini 0:9fca2b23d0ba 73
marcozecchini 0:9fca2b23d0ba 74 /**
marcozecchini 0:9fca2b23d0ba 75 * Service discovery ended event.
marcozecchini 0:9fca2b23d0ba 76 *
marcozecchini 0:9fca2b23d0ba 77 * The callback accepts a connection handle as parameter. This
marcozecchini 0:9fca2b23d0ba 78 * parameter is used to identify on which connection the service discovery
marcozecchini 0:9fca2b23d0ba 79 * process ended.
marcozecchini 0:9fca2b23d0ba 80 */
marcozecchini 0:9fca2b23d0ba 81 typedef FunctionPointerWithContext<Gap::Handle_t> TerminationCallback_t;
marcozecchini 0:9fca2b23d0ba 82
marcozecchini 0:9fca2b23d0ba 83 public:
marcozecchini 0:9fca2b23d0ba 84 /**
marcozecchini 0:9fca2b23d0ba 85 * Launch service discovery. Once launched, service discovery remains
marcozecchini 0:9fca2b23d0ba 86 * active with callbacks being issued back into the application for matching
marcozecchini 0:9fca2b23d0ba 87 * services or characteristics. isActive() can be used to determine status, and
marcozecchini 0:9fca2b23d0ba 88 * a termination callback (if set up) is invoked at the end. Service
marcozecchini 0:9fca2b23d0ba 89 * discovery can be terminated prematurely, if needed, using terminate().
marcozecchini 0:9fca2b23d0ba 90 *
marcozecchini 0:9fca2b23d0ba 91 * @param connectionHandle
marcozecchini 0:9fca2b23d0ba 92 * Handle for the connection with the peer.
marcozecchini 0:9fca2b23d0ba 93 * @param sc
marcozecchini 0:9fca2b23d0ba 94 * This is the application callback for a matching service. Taken as
marcozecchini 0:9fca2b23d0ba 95 * NULL by default. Note: service discovery may still be active
marcozecchini 0:9fca2b23d0ba 96 * when this callback is issued; calling asynchronous BLE-stack
marcozecchini 0:9fca2b23d0ba 97 * APIs from within this application callback might cause the
marcozecchini 0:9fca2b23d0ba 98 * stack to abort service discovery. If this becomes an issue, it
marcozecchini 0:9fca2b23d0ba 99 * may be better to make a local copy of the discoveredService and
marcozecchini 0:9fca2b23d0ba 100 * wait for service discovery to terminate before operating on the
marcozecchini 0:9fca2b23d0ba 101 * service.
marcozecchini 0:9fca2b23d0ba 102 * @param cc
marcozecchini 0:9fca2b23d0ba 103 * This is the application callback for a matching characteristic.
marcozecchini 0:9fca2b23d0ba 104 * Taken as NULL by default. Note: service discovery may still be
marcozecchini 0:9fca2b23d0ba 105 * active when this callback is issued; calling asynchronous
marcozecchini 0:9fca2b23d0ba 106 * BLE-stack APIs from within this application callback might cause
marcozecchini 0:9fca2b23d0ba 107 * the stack to abort service discovery. If this becomes an issue,
marcozecchini 0:9fca2b23d0ba 108 * it may be better to make a local copy of the discoveredCharacteristic
marcozecchini 0:9fca2b23d0ba 109 * and wait for service discovery to terminate before operating on the
marcozecchini 0:9fca2b23d0ba 110 * characteristic.
marcozecchini 0:9fca2b23d0ba 111 * @param matchingServiceUUID
marcozecchini 0:9fca2b23d0ba 112 * UUID-based filter for specifying a service in which the application is
marcozecchini 0:9fca2b23d0ba 113 * interested. By default, it is set as the wildcard UUID_UNKNOWN,
marcozecchini 0:9fca2b23d0ba 114 * in which case it matches all services. If characteristic-UUID
marcozecchini 0:9fca2b23d0ba 115 * filter (below) is set to the wildcard value, then a service
marcozecchini 0:9fca2b23d0ba 116 * callback is invoked for the matching service (or for every
marcozecchini 0:9fca2b23d0ba 117 * service if the service filter is a wildcard).
marcozecchini 0:9fca2b23d0ba 118 * @param matchingCharacteristicUUIDIn
marcozecchini 0:9fca2b23d0ba 119 * UUID-based filter for specifying a characteristic in which the application
marcozecchini 0:9fca2b23d0ba 120 * is interested. By default, it is set as the wildcard UUID_UKNOWN
marcozecchini 0:9fca2b23d0ba 121 * to match against any characteristic. If both service-UUID
marcozecchini 0:9fca2b23d0ba 122 * filter and characteristic-UUID filter are used with nonwildcard
marcozecchini 0:9fca2b23d0ba 123 * values, then only a single characteristic callback is
marcozecchini 0:9fca2b23d0ba 124 * invoked for the matching characteristic.
marcozecchini 0:9fca2b23d0ba 125 *
marcozecchini 0:9fca2b23d0ba 126 * @note Using wildcard values for both service-UUID and characteristic-
marcozecchini 0:9fca2b23d0ba 127 * UUID result in complete service discovery: callbacks being
marcozecchini 0:9fca2b23d0ba 128 * called for every service and characteristic.
marcozecchini 0:9fca2b23d0ba 129 *
marcozecchini 0:9fca2b23d0ba 130 * @note Providing NULL for the characteristic callback results in
marcozecchini 0:9fca2b23d0ba 131 * characteristic discovery being skipped for each matching
marcozecchini 0:9fca2b23d0ba 132 * service. This allows for an inexpensive method to discover only
marcozecchini 0:9fca2b23d0ba 133 * services.
marcozecchini 0:9fca2b23d0ba 134 *
marcozecchini 0:9fca2b23d0ba 135 * @return
marcozecchini 0:9fca2b23d0ba 136 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
marcozecchini 0:9fca2b23d0ba 137 */
marcozecchini 0:9fca2b23d0ba 138 virtual ble_error_t launch(Gap::Handle_t connectionHandle,
marcozecchini 0:9fca2b23d0ba 139 ServiceCallback_t sc = NULL,
marcozecchini 0:9fca2b23d0ba 140 CharacteristicCallback_t cc = NULL,
marcozecchini 0:9fca2b23d0ba 141 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
marcozecchini 0:9fca2b23d0ba 142 const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) = 0;
marcozecchini 0:9fca2b23d0ba 143
marcozecchini 0:9fca2b23d0ba 144 /**
marcozecchini 0:9fca2b23d0ba 145 * Check whether service-discovery is currently active.
marcozecchini 0:9fca2b23d0ba 146 */
marcozecchini 0:9fca2b23d0ba 147 virtual bool isActive(void) const = 0;
marcozecchini 0:9fca2b23d0ba 148
marcozecchini 0:9fca2b23d0ba 149 /**
marcozecchini 0:9fca2b23d0ba 150 * Terminate an ongoing service discovery. This should result in an
marcozecchini 0:9fca2b23d0ba 151 * invocation of the TerminationCallback if service discovery is active.
marcozecchini 0:9fca2b23d0ba 152 */
marcozecchini 0:9fca2b23d0ba 153 virtual void terminate(void) = 0;
marcozecchini 0:9fca2b23d0ba 154
marcozecchini 0:9fca2b23d0ba 155 /**
marcozecchini 0:9fca2b23d0ba 156 * Set up a callback to be invoked when service discovery is terminated.
marcozecchini 0:9fca2b23d0ba 157 */
marcozecchini 0:9fca2b23d0ba 158 virtual void onTermination(TerminationCallback_t callback) = 0;
marcozecchini 0:9fca2b23d0ba 159
marcozecchini 0:9fca2b23d0ba 160 /**
marcozecchini 0:9fca2b23d0ba 161 * Clear all ServiceDiscovery state of the associated object.
marcozecchini 0:9fca2b23d0ba 162 *
marcozecchini 0:9fca2b23d0ba 163 * This function is meant to be overridden in the platform-specific
marcozecchini 0:9fca2b23d0ba 164 * subclass. Nevertheless, the subclass is only expected to reset its
marcozecchini 0:9fca2b23d0ba 165 * state and not the data held in ServiceDiscovery members. This is
marcozecchini 0:9fca2b23d0ba 166 * achieved by a call to ServiceDiscovery::reset() from the subclass'
marcozecchini 0:9fca2b23d0ba 167 * reset() implementation.
marcozecchini 0:9fca2b23d0ba 168 *
marcozecchini 0:9fca2b23d0ba 169 * @return BLE_ERROR_NONE on success.
marcozecchini 0:9fca2b23d0ba 170 */
marcozecchini 0:9fca2b23d0ba 171 virtual ble_error_t reset(void) {
marcozecchini 0:9fca2b23d0ba 172 connHandle = 0;
marcozecchini 0:9fca2b23d0ba 173 matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
marcozecchini 0:9fca2b23d0ba 174 serviceCallback = NULL;
marcozecchini 0:9fca2b23d0ba 175 matchingCharacteristicUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
marcozecchini 0:9fca2b23d0ba 176 characteristicCallback = NULL;
marcozecchini 0:9fca2b23d0ba 177
marcozecchini 0:9fca2b23d0ba 178 return BLE_ERROR_NONE;
marcozecchini 0:9fca2b23d0ba 179 }
marcozecchini 0:9fca2b23d0ba 180
marcozecchini 0:9fca2b23d0ba 181 protected:
marcozecchini 0:9fca2b23d0ba 182 /**
marcozecchini 0:9fca2b23d0ba 183 * Connection handle as provided by the SoftDevice.
marcozecchini 0:9fca2b23d0ba 184 */
marcozecchini 0:9fca2b23d0ba 185 Gap::Handle_t connHandle;
marcozecchini 0:9fca2b23d0ba 186 /**
marcozecchini 0:9fca2b23d0ba 187 * UUID-based filter that specifies the service that the application is
marcozecchini 0:9fca2b23d0ba 188 * interested in.
marcozecchini 0:9fca2b23d0ba 189 */
marcozecchini 0:9fca2b23d0ba 190 UUID matchingServiceUUID;
marcozecchini 0:9fca2b23d0ba 191 /**
marcozecchini 0:9fca2b23d0ba 192 * The registered callback handle for when a matching service is found
marcozecchini 0:9fca2b23d0ba 193 * during service-discovery.
marcozecchini 0:9fca2b23d0ba 194 */
marcozecchini 0:9fca2b23d0ba 195 ServiceCallback_t serviceCallback;
marcozecchini 0:9fca2b23d0ba 196 /**
marcozecchini 0:9fca2b23d0ba 197 * UUID-based filter that specifies the characteristic that the
marcozecchini 0:9fca2b23d0ba 198 * application is interested in.
marcozecchini 0:9fca2b23d0ba 199 */
marcozecchini 0:9fca2b23d0ba 200 UUID matchingCharacteristicUUID;
marcozecchini 0:9fca2b23d0ba 201 /**
marcozecchini 0:9fca2b23d0ba 202 * The registered callback handler for when a matching characteristic is
marcozecchini 0:9fca2b23d0ba 203 * found during service-discovery.
marcozecchini 0:9fca2b23d0ba 204 */
marcozecchini 0:9fca2b23d0ba 205 CharacteristicCallback_t characteristicCallback;
marcozecchini 0:9fca2b23d0ba 206 };
marcozecchini 0:9fca2b23d0ba 207
marcozecchini 0:9fca2b23d0ba 208 /**
marcozecchini 0:9fca2b23d0ba 209 * @}
marcozecchini 0:9fca2b23d0ba 210 * @}
marcozecchini 0:9fca2b23d0ba 211 * @}
marcozecchini 0:9fca2b23d0ba 212 */
marcozecchini 0:9fca2b23d0ba 213
marcozecchini 0:9fca2b23d0ba 214 #endif /* ifndef MBED_BLE_SERVICE_DISOVERY_H__ */