Simon Cooksey / mbed-os

Pinned to some recent date

features/FEATURE_BLE/ble/ServiceDiscovery.h@0:fb7af294d5d9, 2016-11-17 (annotated)

Committer:
Simon Cooksey
Date:
Thu Nov 17 16:43:53 2016 +0000
Revision:
0:fb7af294d5d9
Initial commit

Who changed what in which revision?

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