Maxim nexpaq / nexpaq_dev

Preliminary main mbed library for nexpaq development

features/FEATURE_BLE/ble/ServiceDiscovery.h@0:6c56fb4bc5f0, 2016-11-04 (annotated)

Committer:
nexpaq
Date:
Fri Nov 04 20:27:58 2016 +0000
Revision:
0:6c56fb4bc5f0
Moving to library for sharing updates

Who changed what in which revision?

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