Greg Steiert / maxim_dev

Dependents:   sensomed

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

Committer:
switches
Date:
Tue Nov 08 18:27:11 2016 +0000
Revision:
0:0e018d759a2a
Initial commit

Who changed what in which revision?

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