Magnificent7 / Hackathon

Includes library modifications to allow access to AIN_4 (AIN_0 / 5)

mbd_os/features/FEATURE_BLE/ble/ServiceDiscovery.h@0:eafc3fd41f75, 2016-09-20 (annotated)

Committer:
bryantaylor
Date:
Tue Sep 20 21:26:12 2016 +0000
Revision:
0:eafc3fd41f75
hackathon

Who changed what in which revision?

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