Simon Cooksey / mbed-os

Pinned to some recent date

features/FEATURE_BLE/ble/BLE.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 __BLE_H__
Simon Cooksey 0:fb7af294d5d9 18 #define __BLE_H__
Simon Cooksey 0:fb7af294d5d9 19
Simon Cooksey 0:fb7af294d5d9 20 #include "blecommon.h"
Simon Cooksey 0:fb7af294d5d9 21 #include "Gap.h"
Simon Cooksey 0:fb7af294d5d9 22 #include "GattServer.h"
Simon Cooksey 0:fb7af294d5d9 23 #include "GattClient.h"
Simon Cooksey 0:fb7af294d5d9 24
Simon Cooksey 0:fb7af294d5d9 25 #include "ble/FunctionPointerWithContext.h"
Simon Cooksey 0:fb7af294d5d9 26
Simon Cooksey 0:fb7af294d5d9 27 #ifdef YOTTA_CFG_MBED_OS
Simon Cooksey 0:fb7af294d5d9 28 #include "mbed-drivers/mbed_error.h"
Simon Cooksey 0:fb7af294d5d9 29 #else
Simon Cooksey 0:fb7af294d5d9 30 #include "mbed_error.h"
Simon Cooksey 0:fb7af294d5d9 31 #endif
Simon Cooksey 0:fb7af294d5d9 32
Simon Cooksey 0:fb7af294d5d9 33 /* Forward declaration for the implementation class */
Simon Cooksey 0:fb7af294d5d9 34 class BLEInstanceBase;
Simon Cooksey 0:fb7af294d5d9 35
Simon Cooksey 0:fb7af294d5d9 36 /**
Simon Cooksey 0:fb7af294d5d9 37 * The base class used to abstract away BLE-capable radio transceivers or SOCs,
Simon Cooksey 0:fb7af294d5d9 38 * so that the BLE API can work with any radio transparently.
Simon Cooksey 0:fb7af294d5d9 39 */
Simon Cooksey 0:fb7af294d5d9 40 class BLE
Simon Cooksey 0:fb7af294d5d9 41 {
Simon Cooksey 0:fb7af294d5d9 42 public:
Simon Cooksey 0:fb7af294d5d9 43 typedef unsigned InstanceID_t; /**< The type returned by BLE::getInstanceID(). */
Simon Cooksey 0:fb7af294d5d9 44
Simon Cooksey 0:fb7af294d5d9 45 /**
Simon Cooksey 0:fb7af294d5d9 46 * Parameters provided to the callback registered by onEventsToProcess
Simon Cooksey 0:fb7af294d5d9 47 * when there is events to process.
Simon Cooksey 0:fb7af294d5d9 48 */
Simon Cooksey 0:fb7af294d5d9 49 struct OnEventsToProcessCallbackContext {
Simon Cooksey 0:fb7af294d5d9 50 /**
Simon Cooksey 0:fb7af294d5d9 51 * The ble instance which have events to process.
Simon Cooksey 0:fb7af294d5d9 52 */
Simon Cooksey 0:fb7af294d5d9 53 BLE& ble;
Simon Cooksey 0:fb7af294d5d9 54 };
Simon Cooksey 0:fb7af294d5d9 55
Simon Cooksey 0:fb7af294d5d9 56 /**
Simon Cooksey 0:fb7af294d5d9 57 * Callback type used by the onEventsToProcess function.
Simon Cooksey 0:fb7af294d5d9 58 */
Simon Cooksey 0:fb7af294d5d9 59 typedef FunctionPointerWithContext<OnEventsToProcessCallbackContext*> OnEventsToProcessCallback_t;
Simon Cooksey 0:fb7af294d5d9 60
Simon Cooksey 0:fb7af294d5d9 61 /**
Simon Cooksey 0:fb7af294d5d9 62 * The context provided to init-completion-callbacks (see init() below).
Simon Cooksey 0:fb7af294d5d9 63 *
Simon Cooksey 0:fb7af294d5d9 64 * @param ble
Simon Cooksey 0:fb7af294d5d9 65 * A reference to the BLE instance being initialized.
Simon Cooksey 0:fb7af294d5d9 66 * @param error
Simon Cooksey 0:fb7af294d5d9 67 * Captures the result of initialization. It is set to
Simon Cooksey 0:fb7af294d5d9 68 * BLE_ERROR_NONE if initialization completed successfully. Else
Simon Cooksey 0:fb7af294d5d9 69 * the error value is implementation specific.
Simon Cooksey 0:fb7af294d5d9 70 */
Simon Cooksey 0:fb7af294d5d9 71 struct InitializationCompleteCallbackContext {
Simon Cooksey 0:fb7af294d5d9 72 BLE& ble; /**< Reference to the BLE object that has been initialized */
Simon Cooksey 0:fb7af294d5d9 73 ble_error_t error; /**< Error status of the initialization. It is set to BLE_ERROR_NONE if initialization completed successfully. */
Simon Cooksey 0:fb7af294d5d9 74 };
Simon Cooksey 0:fb7af294d5d9 75
Simon Cooksey 0:fb7af294d5d9 76 /**
Simon Cooksey 0:fb7af294d5d9 77 * The signature for function-pointer like callbacks for initialization-completion.
Simon Cooksey 0:fb7af294d5d9 78 *
Simon Cooksey 0:fb7af294d5d9 79 * @note There are two versions of init(). In addition to the simple
Simon Cooksey 0:fb7af294d5d9 80 * function-pointer, init() can also take a <Object, member> tuple as its
Simon Cooksey 0:fb7af294d5d9 81 * callback target. In case of the latter, the following declaration doesn't apply.
Simon Cooksey 0:fb7af294d5d9 82 */
Simon Cooksey 0:fb7af294d5d9 83 typedef void (*InitializationCompleteCallback_t)(InitializationCompleteCallbackContext *context);
Simon Cooksey 0:fb7af294d5d9 84
Simon Cooksey 0:fb7af294d5d9 85 /**
Simon Cooksey 0:fb7af294d5d9 86 * Initialize the BLE controller. This should be called before using
Simon Cooksey 0:fb7af294d5d9 87 * anything else in the BLE API.
Simon Cooksey 0:fb7af294d5d9 88 *
Simon Cooksey 0:fb7af294d5d9 89 * init() hands control to the underlying BLE module to accomplish
Simon Cooksey 0:fb7af294d5d9 90 * initialization. This initialization may tacitly depend on other hardware
Simon Cooksey 0:fb7af294d5d9 91 * setup (such as clocks or power-modes) that happens early on during
Simon Cooksey 0:fb7af294d5d9 92 * system startup. It may not be safe to call init() from a global static
Simon Cooksey 0:fb7af294d5d9 93 * context where ordering is compiler-specific and can't be guaranteed - it
Simon Cooksey 0:fb7af294d5d9 94 * is safe to call BLE::init() from within main().
Simon Cooksey 0:fb7af294d5d9 95 *
Simon Cooksey 0:fb7af294d5d9 96 * @param initCompleteCallback
Simon Cooksey 0:fb7af294d5d9 97 * A callback for when initialization completes for a BLE
Simon Cooksey 0:fb7af294d5d9 98 * instance. This is an optional parameter; if no callback is
Simon Cooksey 0:fb7af294d5d9 99 * set up the application can still determine the status of
Simon Cooksey 0:fb7af294d5d9 100 * initialization using BLE::hasInitialized() (see below).
Simon Cooksey 0:fb7af294d5d9 101 *
Simon Cooksey 0:fb7af294d5d9 102 * @return BLE_ERROR_NONE if the initialization procedure was started
Simon Cooksey 0:fb7af294d5d9 103 * successfully.
Simon Cooksey 0:fb7af294d5d9 104 *
Simon Cooksey 0:fb7af294d5d9 105 * @note If init() returns BLE_ERROR_NONE, the underlying stack must invoke
Simon Cooksey 0:fb7af294d5d9 106 * the initialization completion callback at some point.
Simon Cooksey 0:fb7af294d5d9 107 *
Simon Cooksey 0:fb7af294d5d9 108 * @note Nearly all BLE APIs would return
Simon Cooksey 0:fb7af294d5d9 109 * BLE_ERROR_INITIALIZATION_INCOMPLETE if used on an instance before the
Simon Cooksey 0:fb7af294d5d9 110 * corresponding transport is initialized.
Simon Cooksey 0:fb7af294d5d9 111 *
Simon Cooksey 0:fb7af294d5d9 112 * @note There are two versions of init(). In addition to the simple
Simon Cooksey 0:fb7af294d5d9 113 * function-pointer, init() can also take an <Object, member> tuple as its
Simon Cooksey 0:fb7af294d5d9 114 * callback target.
Simon Cooksey 0:fb7af294d5d9 115 */
Simon Cooksey 0:fb7af294d5d9 116 ble_error_t init(InitializationCompleteCallback_t initCompleteCallback = NULL) {
Simon Cooksey 0:fb7af294d5d9 117 FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback(initCompleteCallback);
Simon Cooksey 0:fb7af294d5d9 118 return initImplementation(callback);
Simon Cooksey 0:fb7af294d5d9 119 }
Simon Cooksey 0:fb7af294d5d9 120
Simon Cooksey 0:fb7af294d5d9 121 /**
Simon Cooksey 0:fb7af294d5d9 122 * An alternate declaration for init(). This one takes an <Object, member> tuple as its
Simon Cooksey 0:fb7af294d5d9 123 * callback target.
Simon Cooksey 0:fb7af294d5d9 124 */
Simon Cooksey 0:fb7af294d5d9 125 template<typename T>
Simon Cooksey 0:fb7af294d5d9 126 ble_error_t init(T *object, void (T::*initCompleteCallback)(InitializationCompleteCallbackContext *context)) {
Simon Cooksey 0:fb7af294d5d9 127 FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback(object, initCompleteCallback);
Simon Cooksey 0:fb7af294d5d9 128 return initImplementation(callback);
Simon Cooksey 0:fb7af294d5d9 129 }
Simon Cooksey 0:fb7af294d5d9 130
Simon Cooksey 0:fb7af294d5d9 131 /**
Simon Cooksey 0:fb7af294d5d9 132 * @return true if initialization has completed for the underlying BLE
Simon Cooksey 0:fb7af294d5d9 133 * transport.
Simon Cooksey 0:fb7af294d5d9 134 *
Simon Cooksey 0:fb7af294d5d9 135 * The application can set up a callback to signal completion of
Simon Cooksey 0:fb7af294d5d9 136 * initialization when using init(). Otherwise, this method can be used to
Simon Cooksey 0:fb7af294d5d9 137 * poll the state of initialization.
Simon Cooksey 0:fb7af294d5d9 138 */
Simon Cooksey 0:fb7af294d5d9 139 bool hasInitialized(void) const;
Simon Cooksey 0:fb7af294d5d9 140
Simon Cooksey 0:fb7af294d5d9 141 /**
Simon Cooksey 0:fb7af294d5d9 142 * Purge the BLE stack of GATT and GAP state. init() must be called
Simon Cooksey 0:fb7af294d5d9 143 * afterwards to re-instate services and GAP state. This API offers a way to
Simon Cooksey 0:fb7af294d5d9 144 * repopulate the GATT database with new services and characteristics.
Simon Cooksey 0:fb7af294d5d9 145 */
Simon Cooksey 0:fb7af294d5d9 146 ble_error_t shutdown(void);
Simon Cooksey 0:fb7af294d5d9 147
Simon Cooksey 0:fb7af294d5d9 148 /**
Simon Cooksey 0:fb7af294d5d9 149 * This call allows the application to get the BLE stack version information.
Simon Cooksey 0:fb7af294d5d9 150 *
Simon Cooksey 0:fb7af294d5d9 151 * @return A pointer to a const string representing the version.
Simon Cooksey 0:fb7af294d5d9 152 *
Simon Cooksey 0:fb7af294d5d9 153 * @note The string returned is owned by BLE API.
Simon Cooksey 0:fb7af294d5d9 154 */
Simon Cooksey 0:fb7af294d5d9 155 const char *getVersion(void);
Simon Cooksey 0:fb7af294d5d9 156
Simon Cooksey 0:fb7af294d5d9 157 /**
Simon Cooksey 0:fb7af294d5d9 158 * Accessor to Gap. All Gap related functionality requires
Simon Cooksey 0:fb7af294d5d9 159 * going through this accessor.
Simon Cooksey 0:fb7af294d5d9 160 *
Simon Cooksey 0:fb7af294d5d9 161 * @return A reference to a Gap object associated to this BLE instance.
Simon Cooksey 0:fb7af294d5d9 162 */
Simon Cooksey 0:fb7af294d5d9 163 Gap &gap();
Simon Cooksey 0:fb7af294d5d9 164
Simon Cooksey 0:fb7af294d5d9 165 /**
Simon Cooksey 0:fb7af294d5d9 166 * A const alternative to gap().
Simon Cooksey 0:fb7af294d5d9 167 *
Simon Cooksey 0:fb7af294d5d9 168 * @return A const reference to a Gap object associated to this BLE instance.
Simon Cooksey 0:fb7af294d5d9 169 */
Simon Cooksey 0:fb7af294d5d9 170 const Gap &gap() const;
Simon Cooksey 0:fb7af294d5d9 171
Simon Cooksey 0:fb7af294d5d9 172 /**
Simon Cooksey 0:fb7af294d5d9 173 * Accessor to GattServer. All GattServer related functionality requires
Simon Cooksey 0:fb7af294d5d9 174 * going through this accessor.
Simon Cooksey 0:fb7af294d5d9 175 *
Simon Cooksey 0:fb7af294d5d9 176 * @return A reference to a GattServer object associated to this BLE instance.
Simon Cooksey 0:fb7af294d5d9 177 */
Simon Cooksey 0:fb7af294d5d9 178 GattServer& gattServer();
Simon Cooksey 0:fb7af294d5d9 179
Simon Cooksey 0:fb7af294d5d9 180 /**
Simon Cooksey 0:fb7af294d5d9 181 * A const alternative to gattServer().
Simon Cooksey 0:fb7af294d5d9 182 *
Simon Cooksey 0:fb7af294d5d9 183 * @return A const reference to a GattServer object associated to this BLE instance.
Simon Cooksey 0:fb7af294d5d9 184 */
Simon Cooksey 0:fb7af294d5d9 185 const GattServer& gattServer() const;
Simon Cooksey 0:fb7af294d5d9 186
Simon Cooksey 0:fb7af294d5d9 187 /**
Simon Cooksey 0:fb7af294d5d9 188 * Accessors to GattClient. All GattClient related functionality requires going
Simon Cooksey 0:fb7af294d5d9 189 * through this accessor.
Simon Cooksey 0:fb7af294d5d9 190 *
Simon Cooksey 0:fb7af294d5d9 191 * @return A reference to a GattClient object associated to this BLE instance.
Simon Cooksey 0:fb7af294d5d9 192 */
Simon Cooksey 0:fb7af294d5d9 193 GattClient& gattClient();
Simon Cooksey 0:fb7af294d5d9 194
Simon Cooksey 0:fb7af294d5d9 195 /**
Simon Cooksey 0:fb7af294d5d9 196 * A const alternative to gattClient().
Simon Cooksey 0:fb7af294d5d9 197 *
Simon Cooksey 0:fb7af294d5d9 198 * @return A const reference to a GattClient object associated to this BLE instance.
Simon Cooksey 0:fb7af294d5d9 199 */
Simon Cooksey 0:fb7af294d5d9 200 const GattClient& gattClient() const;
Simon Cooksey 0:fb7af294d5d9 201
Simon Cooksey 0:fb7af294d5d9 202 /**
Simon Cooksey 0:fb7af294d5d9 203 * Accessors to SecurityManager. All SecurityManager related functionality requires
Simon Cooksey 0:fb7af294d5d9 204 * going through this accessor.
Simon Cooksey 0:fb7af294d5d9 205 *
Simon Cooksey 0:fb7af294d5d9 206 * @return A reference to a SecurityManager object associated to this BLE instance.
Simon Cooksey 0:fb7af294d5d9 207 */
Simon Cooksey 0:fb7af294d5d9 208 SecurityManager& securityManager();
Simon Cooksey 0:fb7af294d5d9 209
Simon Cooksey 0:fb7af294d5d9 210 /**
Simon Cooksey 0:fb7af294d5d9 211 * A const alternative to securityManager().
Simon Cooksey 0:fb7af294d5d9 212 *
Simon Cooksey 0:fb7af294d5d9 213 * @return A const reference to a SecurityManager object associated to this BLE instance.
Simon Cooksey 0:fb7af294d5d9 214 */
Simon Cooksey 0:fb7af294d5d9 215 const SecurityManager& securityManager() const;
Simon Cooksey 0:fb7af294d5d9 216
Simon Cooksey 0:fb7af294d5d9 217 /**
Simon Cooksey 0:fb7af294d5d9 218 * Yield control to the BLE stack or to other tasks waiting for events. This
Simon Cooksey 0:fb7af294d5d9 219 * is a sleep function that will return when there is an application-specific
Simon Cooksey 0:fb7af294d5d9 220 * interrupt, but the MCU might wake up several times before
Simon Cooksey 0:fb7af294d5d9 221 * returning (to service the stack). This is not always interchangeable with
Simon Cooksey 0:fb7af294d5d9 222 * WFE().
Simon Cooksey 0:fb7af294d5d9 223 */
Simon Cooksey 0:fb7af294d5d9 224 void waitForEvent(void);
Simon Cooksey 0:fb7af294d5d9 225
Simon Cooksey 0:fb7af294d5d9 226 public:
Simon Cooksey 0:fb7af294d5d9 227 /**
Simon Cooksey 0:fb7af294d5d9 228 * The value of the BLE::InstanceID_t for the default BLE instance.
Simon Cooksey 0:fb7af294d5d9 229 */
Simon Cooksey 0:fb7af294d5d9 230 static const InstanceID_t DEFAULT_INSTANCE = 0;
Simon Cooksey 0:fb7af294d5d9 231 #ifndef YOTTA_CFG_BLE_INSTANCES_COUNT
Simon Cooksey 0:fb7af294d5d9 232 /**
Simon Cooksey 0:fb7af294d5d9 233 * The number of permitted BLE instances for the application.
Simon Cooksey 0:fb7af294d5d9 234 */
Simon Cooksey 0:fb7af294d5d9 235 static const InstanceID_t NUM_INSTANCES = 1;
Simon Cooksey 0:fb7af294d5d9 236 #else
Simon Cooksey 0:fb7af294d5d9 237 /**
Simon Cooksey 0:fb7af294d5d9 238 * The number of permitted BLE instances for the application.
Simon Cooksey 0:fb7af294d5d9 239 */
Simon Cooksey 0:fb7af294d5d9 240 static const InstanceID_t NUM_INSTANCES = YOTTA_CFG_BLE_INSTANCES_COUNT;
Simon Cooksey 0:fb7af294d5d9 241 #endif
Simon Cooksey 0:fb7af294d5d9 242
Simon Cooksey 0:fb7af294d5d9 243 /**
Simon Cooksey 0:fb7af294d5d9 244 * Get a reference to the BLE singleton corresponding to a given interface.
Simon Cooksey 0:fb7af294d5d9 245 * There is a static array of BLE singletons.
Simon Cooksey 0:fb7af294d5d9 246 *
Simon Cooksey 0:fb7af294d5d9 247 * @note Calling Instance() is preferred over constructing a BLE object
Simon Cooksey 0:fb7af294d5d9 248 * directly, as it returns references to singletons.
Simon Cooksey 0:fb7af294d5d9 249 *
Simon Cooksey 0:fb7af294d5d9 250 * @param[in] id
Simon Cooksey 0:fb7af294d5d9 251 * Instance-ID. This should be less than NUM_INSTANCES
Simon Cooksey 0:fb7af294d5d9 252 * for the returned BLE singleton to be useful.
Simon Cooksey 0:fb7af294d5d9 253 *
Simon Cooksey 0:fb7af294d5d9 254 * @return A reference to a single object.
Simon Cooksey 0:fb7af294d5d9 255 */
Simon Cooksey 0:fb7af294d5d9 256 static BLE &Instance(InstanceID_t id = DEFAULT_INSTANCE);
Simon Cooksey 0:fb7af294d5d9 257
Simon Cooksey 0:fb7af294d5d9 258 /**
Simon Cooksey 0:fb7af294d5d9 259 * Constructor for a handle to a BLE instance (the BLE stack). BLE handles
Simon Cooksey 0:fb7af294d5d9 260 * are thin wrappers around a transport object (that is, ptr. to
Simon Cooksey 0:fb7af294d5d9 261 * BLEInstanceBase).
Simon Cooksey 0:fb7af294d5d9 262 *
Simon Cooksey 0:fb7af294d5d9 263 * It is better to create BLE objects as singletons accessed through the
Simon Cooksey 0:fb7af294d5d9 264 * Instance() method. If multiple BLE handles are constructed for the same
Simon Cooksey 0:fb7af294d5d9 265 * interface (using this constructor), they will share the same underlying
Simon Cooksey 0:fb7af294d5d9 266 * transport object.
Simon Cooksey 0:fb7af294d5d9 267 */
Simon Cooksey 0:fb7af294d5d9 268 BLE(InstanceID_t instanceID = DEFAULT_INSTANCE);
Simon Cooksey 0:fb7af294d5d9 269
Simon Cooksey 0:fb7af294d5d9 270 /**
Simon Cooksey 0:fb7af294d5d9 271 * Fetch the ID of a BLE instance. Typically there would only be the DEFAULT_INSTANCE.
Simon Cooksey 0:fb7af294d5d9 272 */
Simon Cooksey 0:fb7af294d5d9 273 InstanceID_t getInstanceID(void) const {
Simon Cooksey 0:fb7af294d5d9 274 return instanceID;
Simon Cooksey 0:fb7af294d5d9 275 }
Simon Cooksey 0:fb7af294d5d9 276
Simon Cooksey 0:fb7af294d5d9 277 /*
Simon Cooksey 0:fb7af294d5d9 278 * Deprecation alert!
Simon Cooksey 0:fb7af294d5d9 279 * All of the following are deprecated and may be dropped in a future
Simon Cooksey 0:fb7af294d5d9 280 * release. Documentation should refer to alternative APIs.
Simon Cooksey 0:fb7af294d5d9 281 */
Simon Cooksey 0:fb7af294d5d9 282
Simon Cooksey 0:fb7af294d5d9 283 /* GAP specific APIs. */
Simon Cooksey 0:fb7af294d5d9 284 public:
Simon Cooksey 0:fb7af294d5d9 285 /**
Simon Cooksey 0:fb7af294d5d9 286 * Set the BTLE MAC address and type.
Simon Cooksey 0:fb7af294d5d9 287 * @return BLE_ERROR_NONE on success.
Simon Cooksey 0:fb7af294d5d9 288 *
Simon Cooksey 0:fb7af294d5d9 289 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 290 * Gap::setAddress(). A former call to
Simon Cooksey 0:fb7af294d5d9 291 * ble.setAddress(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 292 * ble.gap().setAddress(...).
Simon Cooksey 0:fb7af294d5d9 293 */
Simon Cooksey 0:fb7af294d5d9 294 ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
Simon Cooksey 0:fb7af294d5d9 295 return gap().setAddress(type, address);
Simon Cooksey 0:fb7af294d5d9 296 }
Simon Cooksey 0:fb7af294d5d9 297
Simon Cooksey 0:fb7af294d5d9 298 /**
Simon Cooksey 0:fb7af294d5d9 299 * Fetch the Bluetooth Low Energy MAC address and type.
Simon Cooksey 0:fb7af294d5d9 300 * @return BLE_ERROR_NONE on success.
Simon Cooksey 0:fb7af294d5d9 301 *
Simon Cooksey 0:fb7af294d5d9 302 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 303 * Gap::getAddress(). A former call to
Simon Cooksey 0:fb7af294d5d9 304 * ble.getAddress(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 305 * ble.gap().getAddress(...).
Simon Cooksey 0:fb7af294d5d9 306 */
Simon Cooksey 0:fb7af294d5d9 307 ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
Simon Cooksey 0:fb7af294d5d9 308 return gap().getAddress(typeP, address);
Simon Cooksey 0:fb7af294d5d9 309 }
Simon Cooksey 0:fb7af294d5d9 310
Simon Cooksey 0:fb7af294d5d9 311 /**
Simon Cooksey 0:fb7af294d5d9 312 * Set the GAP advertising mode to use for this device.
Simon Cooksey 0:fb7af294d5d9 313 *
Simon Cooksey 0:fb7af294d5d9 314 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 315 * Gap::setAdvertisingType(). A former call to
Simon Cooksey 0:fb7af294d5d9 316 * ble.setAdvertisingType(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 317 * ble.gap().setAdvertisingType(...).
Simon Cooksey 0:fb7af294d5d9 318 */
Simon Cooksey 0:fb7af294d5d9 319 void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) {
Simon Cooksey 0:fb7af294d5d9 320 gap().setAdvertisingType(advType);
Simon Cooksey 0:fb7af294d5d9 321 }
Simon Cooksey 0:fb7af294d5d9 322
Simon Cooksey 0:fb7af294d5d9 323 /**
Simon Cooksey 0:fb7af294d5d9 324 * @param[in] interval
Simon Cooksey 0:fb7af294d5d9 325 * Advertising interval in units of milliseconds. Advertising
Simon Cooksey 0:fb7af294d5d9 326 * is disabled if interval is 0. If interval is smaller than
Simon Cooksey 0:fb7af294d5d9 327 * the minimum supported value, then the minimum supported
Simon Cooksey 0:fb7af294d5d9 328 * value is used instead. This minimum value can be discovered
Simon Cooksey 0:fb7af294d5d9 329 * using getMinAdvertisingInterval().
Simon Cooksey 0:fb7af294d5d9 330 *
Simon Cooksey 0:fb7af294d5d9 331 * This field must be set to 0 if connectionMode is equal
Simon Cooksey 0:fb7af294d5d9 332 * to ADV_CONNECTABLE_DIRECTED.
Simon Cooksey 0:fb7af294d5d9 333 *
Simon Cooksey 0:fb7af294d5d9 334 * @note Decreasing this value allows central devices to detect a
Simon Cooksey 0:fb7af294d5d9 335 * peripheral faster, at the expense of more power being used by the radio
Simon Cooksey 0:fb7af294d5d9 336 * due to the higher data transmit rate.
Simon Cooksey 0:fb7af294d5d9 337 *
Simon Cooksey 0:fb7af294d5d9 338 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 339 * Gap::setAdvertisingInterval(). A former call to
Simon Cooksey 0:fb7af294d5d9 340 * ble.setAdvertisingInterval(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 341 * ble.gap().setAdvertisingInterval(...).
Simon Cooksey 0:fb7af294d5d9 342 *
Simon Cooksey 0:fb7af294d5d9 343 * @note WARNING: This API previously used 0.625ms as the unit for its
Simon Cooksey 0:fb7af294d5d9 344 * 'interval' argument. That required an explicit conversion from
Simon Cooksey 0:fb7af294d5d9 345 * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
Simon Cooksey 0:fb7af294d5d9 346 * no longer required as the new units are milliseconds. Any application
Simon Cooksey 0:fb7af294d5d9 347 * code depending on the old semantics needs to be updated accordingly.
Simon Cooksey 0:fb7af294d5d9 348 */
Simon Cooksey 0:fb7af294d5d9 349 void setAdvertisingInterval(uint16_t interval) {
Simon Cooksey 0:fb7af294d5d9 350 gap().setAdvertisingInterval(interval);
Simon Cooksey 0:fb7af294d5d9 351 }
Simon Cooksey 0:fb7af294d5d9 352
Simon Cooksey 0:fb7af294d5d9 353 /**
Simon Cooksey 0:fb7af294d5d9 354 * @return Minimum Advertising interval in milliseconds.
Simon Cooksey 0:fb7af294d5d9 355 *
Simon Cooksey 0:fb7af294d5d9 356 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 357 * Gap::getMinAdvertisingInterval(). A former call to
Simon Cooksey 0:fb7af294d5d9 358 * ble.getMinAdvertisingInterval(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 359 * ble.gap().getMinAdvertisingInterval(...).
Simon Cooksey 0:fb7af294d5d9 360 */
Simon Cooksey 0:fb7af294d5d9 361 uint16_t getMinAdvertisingInterval(void) const {
Simon Cooksey 0:fb7af294d5d9 362 return gap().getMinAdvertisingInterval();
Simon Cooksey 0:fb7af294d5d9 363 }
Simon Cooksey 0:fb7af294d5d9 364
Simon Cooksey 0:fb7af294d5d9 365 /**
Simon Cooksey 0:fb7af294d5d9 366 * @return Minimum Advertising interval in milliseconds for non-connectible mode.
Simon Cooksey 0:fb7af294d5d9 367 *
Simon Cooksey 0:fb7af294d5d9 368 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 369 * Gap::MinNonConnectableAdvertisingInterval(). A former call to
Simon Cooksey 0:fb7af294d5d9 370 * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 371 * ble.gap().getMinNonConnectableAdvertisingInterval(...).
Simon Cooksey 0:fb7af294d5d9 372 */
Simon Cooksey 0:fb7af294d5d9 373 uint16_t getMinNonConnectableAdvertisingInterval(void) const {
Simon Cooksey 0:fb7af294d5d9 374 return gap().getMinNonConnectableAdvertisingInterval();
Simon Cooksey 0:fb7af294d5d9 375 }
Simon Cooksey 0:fb7af294d5d9 376
Simon Cooksey 0:fb7af294d5d9 377 /**
Simon Cooksey 0:fb7af294d5d9 378 * @return Maximum Advertising interval in milliseconds.
Simon Cooksey 0:fb7af294d5d9 379 *
Simon Cooksey 0:fb7af294d5d9 380 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 381 * Gap::getMaxAdvertisingInterval(). A former call to
Simon Cooksey 0:fb7af294d5d9 382 * ble.getMaxAdvertisingInterval(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 383 * ble.gap().getMaxAdvertisingInterval(...).
Simon Cooksey 0:fb7af294d5d9 384 */
Simon Cooksey 0:fb7af294d5d9 385 uint16_t getMaxAdvertisingInterval(void) const {
Simon Cooksey 0:fb7af294d5d9 386 return gap().getMaxAdvertisingInterval();
Simon Cooksey 0:fb7af294d5d9 387 }
Simon Cooksey 0:fb7af294d5d9 388
Simon Cooksey 0:fb7af294d5d9 389 /**
Simon Cooksey 0:fb7af294d5d9 390 * @param[in] timeout
Simon Cooksey 0:fb7af294d5d9 391 * Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
Simon Cooksey 0:fb7af294d5d9 392 * and 16383). Use 0 to disable the advertising timeout.
Simon Cooksey 0:fb7af294d5d9 393 *
Simon Cooksey 0:fb7af294d5d9 394 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 395 * Gap::setAdvertisingTimeout(). A former call to
Simon Cooksey 0:fb7af294d5d9 396 * ble.setAdvertisingTimeout(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 397 * ble.gap().setAdvertisingTimeout(...).
Simon Cooksey 0:fb7af294d5d9 398 */
Simon Cooksey 0:fb7af294d5d9 399 void setAdvertisingTimeout(uint16_t timeout) {
Simon Cooksey 0:fb7af294d5d9 400 gap().setAdvertisingTimeout(timeout);
Simon Cooksey 0:fb7af294d5d9 401 }
Simon Cooksey 0:fb7af294d5d9 402
Simon Cooksey 0:fb7af294d5d9 403 /**
Simon Cooksey 0:fb7af294d5d9 404 * Set up a particular, user-constructed set of advertisement parameters for
Simon Cooksey 0:fb7af294d5d9 405 * the underlying stack. It would be uncommon for this API to be used
Simon Cooksey 0:fb7af294d5d9 406 * directly; there are other APIs to tweak advertisement parameters
Simon Cooksey 0:fb7af294d5d9 407 * individually (see above).
Simon Cooksey 0:fb7af294d5d9 408 *
Simon Cooksey 0:fb7af294d5d9 409 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 410 * Gap::setAdvertisingParams(). A former call to
Simon Cooksey 0:fb7af294d5d9 411 * ble.setAdvertisingParams(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 412 * ble.gap().setAdvertisingParams(...).
Simon Cooksey 0:fb7af294d5d9 413 */
Simon Cooksey 0:fb7af294d5d9 414 void setAdvertisingParams(const GapAdvertisingParams &advParams) {
Simon Cooksey 0:fb7af294d5d9 415 gap().setAdvertisingParams(advParams);
Simon Cooksey 0:fb7af294d5d9 416 }
Simon Cooksey 0:fb7af294d5d9 417
Simon Cooksey 0:fb7af294d5d9 418 /**
Simon Cooksey 0:fb7af294d5d9 419 * @return Read back advertising parameters. Useful for storing and
Simon Cooksey 0:fb7af294d5d9 420 * restoring parameters rapidly.
Simon Cooksey 0:fb7af294d5d9 421 *
Simon Cooksey 0:fb7af294d5d9 422 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 423 * Gap::getAdvertisingParams(). A former call to
Simon Cooksey 0:fb7af294d5d9 424 * ble.getAdvertisingParams(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 425 * ble.gap().getAdvertisingParams(...).
Simon Cooksey 0:fb7af294d5d9 426 */
Simon Cooksey 0:fb7af294d5d9 427 const GapAdvertisingParams &getAdvertisingParams(void) const {
Simon Cooksey 0:fb7af294d5d9 428 return gap().getAdvertisingParams();
Simon Cooksey 0:fb7af294d5d9 429 }
Simon Cooksey 0:fb7af294d5d9 430
Simon Cooksey 0:fb7af294d5d9 431 /**
Simon Cooksey 0:fb7af294d5d9 432 * Accumulate an AD structure in the advertising payload. Please note that
Simon Cooksey 0:fb7af294d5d9 433 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
Simon Cooksey 0:fb7af294d5d9 434 * as an additional 31 bytes if the advertising payload is too
Simon Cooksey 0:fb7af294d5d9 435 * small.
Simon Cooksey 0:fb7af294d5d9 436 *
Simon Cooksey 0:fb7af294d5d9 437 * @param[in] flags
Simon Cooksey 0:fb7af294d5d9 438 * The flags to add. Please refer to
Simon Cooksey 0:fb7af294d5d9 439 * GapAdvertisingData::Flags for valid flags. Multiple
Simon Cooksey 0:fb7af294d5d9 440 * flags may be specified in combination.
Simon Cooksey 0:fb7af294d5d9 441 *
Simon Cooksey 0:fb7af294d5d9 442 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 443 * Gap::accumulateAdvertisingPayload(uint8_t). A former call to
Simon Cooksey 0:fb7af294d5d9 444 * ble.accumulateAdvertisingPayload(flags) should be replaced with
Simon Cooksey 0:fb7af294d5d9 445 * ble.gap().accumulateAdvertisingPayload(flags).
Simon Cooksey 0:fb7af294d5d9 446 */
Simon Cooksey 0:fb7af294d5d9 447 ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
Simon Cooksey 0:fb7af294d5d9 448 return gap().accumulateAdvertisingPayload(flags);
Simon Cooksey 0:fb7af294d5d9 449 }
Simon Cooksey 0:fb7af294d5d9 450
Simon Cooksey 0:fb7af294d5d9 451 /**
Simon Cooksey 0:fb7af294d5d9 452 * Accumulate an AD structure in the advertising payload. Please note that
Simon Cooksey 0:fb7af294d5d9 453 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
Simon Cooksey 0:fb7af294d5d9 454 * as an additional 31 bytes if the advertising payload is too
Simon Cooksey 0:fb7af294d5d9 455 * small.
Simon Cooksey 0:fb7af294d5d9 456 *
Simon Cooksey 0:fb7af294d5d9 457 * @param[in] app
Simon Cooksey 0:fb7af294d5d9 458 * The appearance of the peripheral.
Simon Cooksey 0:fb7af294d5d9 459 *
Simon Cooksey 0:fb7af294d5d9 460 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 461 * Gap::accumulateAdvertisingPayload(GapAdvertisingData::Appearance).
Simon Cooksey 0:fb7af294d5d9 462 * A former call to ble.accumulateAdvertisingPayload(appearance)
Simon Cooksey 0:fb7af294d5d9 463 * should be replaced with
Simon Cooksey 0:fb7af294d5d9 464 * ble.gap().accumulateAdvertisingPayload(appearance).
Simon Cooksey 0:fb7af294d5d9 465 */
Simon Cooksey 0:fb7af294d5d9 466 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
Simon Cooksey 0:fb7af294d5d9 467 return gap().accumulateAdvertisingPayload(app);
Simon Cooksey 0:fb7af294d5d9 468 }
Simon Cooksey 0:fb7af294d5d9 469
Simon Cooksey 0:fb7af294d5d9 470 /**
Simon Cooksey 0:fb7af294d5d9 471 * Accumulate an AD structure in the advertising payload. Please note that
Simon Cooksey 0:fb7af294d5d9 472 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
Simon Cooksey 0:fb7af294d5d9 473 * as an additional 31 bytes if the advertising payload is too
Simon Cooksey 0:fb7af294d5d9 474 * small.
Simon Cooksey 0:fb7af294d5d9 475 *
Simon Cooksey 0:fb7af294d5d9 476 * @param[in] power
Simon Cooksey 0:fb7af294d5d9 477 * The max transmit power to be used by the controller. This
Simon Cooksey 0:fb7af294d5d9 478 * is only a hint.
Simon Cooksey 0:fb7af294d5d9 479 *
Simon Cooksey 0:fb7af294d5d9 480 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 481 * Gap::accumulateAdvertisingPayloadTxPower(). A former call to
Simon Cooksey 0:fb7af294d5d9 482 * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
Simon Cooksey 0:fb7af294d5d9 483 * ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
Simon Cooksey 0:fb7af294d5d9 484 */
Simon Cooksey 0:fb7af294d5d9 485 ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
Simon Cooksey 0:fb7af294d5d9 486 return gap().accumulateAdvertisingPayloadTxPower(power);
Simon Cooksey 0:fb7af294d5d9 487 }
Simon Cooksey 0:fb7af294d5d9 488
Simon Cooksey 0:fb7af294d5d9 489 /**
Simon Cooksey 0:fb7af294d5d9 490 * Accumulate a variable length byte-stream as an AD structure in the
Simon Cooksey 0:fb7af294d5d9 491 * advertising payload. Please note that the payload is limited to 31 bytes.
Simon Cooksey 0:fb7af294d5d9 492 * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
Simon Cooksey 0:fb7af294d5d9 493 * advertising payload is too small.
Simon Cooksey 0:fb7af294d5d9 494 *
Simon Cooksey 0:fb7af294d5d9 495 * @param type The type that describes the variable length data.
Simon Cooksey 0:fb7af294d5d9 496 * @param data Data bytes.
Simon Cooksey 0:fb7af294d5d9 497 * @param len Data length.
Simon Cooksey 0:fb7af294d5d9 498 *
Simon Cooksey 0:fb7af294d5d9 499 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 500 * Gap::accumulateAdvertisingPayload(GapAdvertisingData::DataType, const uint8_t, uint8_t).
Simon Cooksey 0:fb7af294d5d9 501 * A former call to ble.accumulateAdvertisingPayload(...) should
Simon Cooksey 0:fb7af294d5d9 502 * be replaced with ble.gap().accumulateAdvertisingPayload(...).
Simon Cooksey 0:fb7af294d5d9 503 */
Simon Cooksey 0:fb7af294d5d9 504 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
Simon Cooksey 0:fb7af294d5d9 505 return gap().accumulateAdvertisingPayload(type, data, len);
Simon Cooksey 0:fb7af294d5d9 506 }
Simon Cooksey 0:fb7af294d5d9 507
Simon Cooksey 0:fb7af294d5d9 508 /**
Simon Cooksey 0:fb7af294d5d9 509 * Setup a particular, user-constructed advertisement payload for the
Simon Cooksey 0:fb7af294d5d9 510 * underlying stack. It would be uncommon for this API to be used directly;
Simon Cooksey 0:fb7af294d5d9 511 * there are other APIs to build an advertisement payload (see above).
Simon Cooksey 0:fb7af294d5d9 512 *
Simon Cooksey 0:fb7af294d5d9 513 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 514 * Gap::setAdvertisingData(). A former call to
Simon Cooksey 0:fb7af294d5d9 515 * ble.setAdvertisingData(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 516 * ble.gap().setAdvertisingPayload(...).
Simon Cooksey 0:fb7af294d5d9 517 */
Simon Cooksey 0:fb7af294d5d9 518 ble_error_t setAdvertisingData(const GapAdvertisingData &advData) {
Simon Cooksey 0:fb7af294d5d9 519 return gap().setAdvertisingPayload(advData);
Simon Cooksey 0:fb7af294d5d9 520 }
Simon Cooksey 0:fb7af294d5d9 521
Simon Cooksey 0:fb7af294d5d9 522 /**
Simon Cooksey 0:fb7af294d5d9 523 * @return Read back advertising data. Useful for storing and
Simon Cooksey 0:fb7af294d5d9 524 * restoring payload.
Simon Cooksey 0:fb7af294d5d9 525 *
Simon Cooksey 0:fb7af294d5d9 526 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 527 * Gap::getAdvertisingData(). A former call to
Simon Cooksey 0:fb7af294d5d9 528 * ble.getAdvertisingData(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 529 * ble.gap().getAdvertisingPayload()(...).
Simon Cooksey 0:fb7af294d5d9 530 */
Simon Cooksey 0:fb7af294d5d9 531 const GapAdvertisingData &getAdvertisingData(void) const {
Simon Cooksey 0:fb7af294d5d9 532 return gap().getAdvertisingPayload();
Simon Cooksey 0:fb7af294d5d9 533 }
Simon Cooksey 0:fb7af294d5d9 534
Simon Cooksey 0:fb7af294d5d9 535 /**
Simon Cooksey 0:fb7af294d5d9 536 * Reset any advertising payload prepared from prior calls to
Simon Cooksey 0:fb7af294d5d9 537 * accumulateAdvertisingPayload(). This automatically propagates the re-
Simon Cooksey 0:fb7af294d5d9 538 * initialized advertising payload to the underlying stack.
Simon Cooksey 0:fb7af294d5d9 539 *
Simon Cooksey 0:fb7af294d5d9 540 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 541 * Gap::clearAdvertisingPayload(). A former call to
Simon Cooksey 0:fb7af294d5d9 542 * ble.clearAdvertisingPayload(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 543 * ble.gap().clearAdvertisingPayload(...).
Simon Cooksey 0:fb7af294d5d9 544 */
Simon Cooksey 0:fb7af294d5d9 545 void clearAdvertisingPayload(void) {
Simon Cooksey 0:fb7af294d5d9 546 gap().clearAdvertisingPayload();
Simon Cooksey 0:fb7af294d5d9 547 }
Simon Cooksey 0:fb7af294d5d9 548
Simon Cooksey 0:fb7af294d5d9 549 /**
Simon Cooksey 0:fb7af294d5d9 550 * Dynamically reset the accumulated advertising
Simon Cooksey 0:fb7af294d5d9 551 * payload and scanResponse. The application must clear and re-
Simon Cooksey 0:fb7af294d5d9 552 * accumulates a new advertising payload (and scanResponse) before using this
Simon Cooksey 0:fb7af294d5d9 553 * API.
Simon Cooksey 0:fb7af294d5d9 554 *
Simon Cooksey 0:fb7af294d5d9 555 * @return BLE_ERROR_NONE when the advertising payload is set successfully.
Simon Cooksey 0:fb7af294d5d9 556 *
Simon Cooksey 0:fb7af294d5d9 557 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 558 * Gap::setAdvertisingPayload().
Simon Cooksey 0:fb7af294d5d9 559 *
Simon Cooksey 0:fb7af294d5d9 560 * @note The new APIs in Gap update the underlying advertisement payload
Simon Cooksey 0:fb7af294d5d9 561 * implicitly.
Simon Cooksey 0:fb7af294d5d9 562 */
Simon Cooksey 0:fb7af294d5d9 563 ble_error_t setAdvertisingPayload(void) {
Simon Cooksey 0:fb7af294d5d9 564 return BLE_ERROR_NONE;
Simon Cooksey 0:fb7af294d5d9 565 }
Simon Cooksey 0:fb7af294d5d9 566
Simon Cooksey 0:fb7af294d5d9 567 /**
Simon Cooksey 0:fb7af294d5d9 568 * Accumulate a variable length byte-stream as an AD structure in the
Simon Cooksey 0:fb7af294d5d9 569 * scanResponse payload.
Simon Cooksey 0:fb7af294d5d9 570 *
Simon Cooksey 0:fb7af294d5d9 571 * @param[in] type The type that describes the variable length data.
Simon Cooksey 0:fb7af294d5d9 572 * @param[in] data Data bytes.
Simon Cooksey 0:fb7af294d5d9 573 * @param[in] len Data length.
Simon Cooksey 0:fb7af294d5d9 574 *
Simon Cooksey 0:fb7af294d5d9 575 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 576 * Gap::accumulateScanResponse(). A former call to
Simon Cooksey 0:fb7af294d5d9 577 * ble.accumulateScanResponse(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 578 * ble.gap().accumulateScanResponse(...).
Simon Cooksey 0:fb7af294d5d9 579 */
Simon Cooksey 0:fb7af294d5d9 580 ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
Simon Cooksey 0:fb7af294d5d9 581 return gap().accumulateScanResponse(type, data, len);
Simon Cooksey 0:fb7af294d5d9 582 }
Simon Cooksey 0:fb7af294d5d9 583
Simon Cooksey 0:fb7af294d5d9 584 /**
Simon Cooksey 0:fb7af294d5d9 585 * Reset any scan response prepared from prior calls to
Simon Cooksey 0:fb7af294d5d9 586 * accumulateScanResponse().
Simon Cooksey 0:fb7af294d5d9 587 *
Simon Cooksey 0:fb7af294d5d9 588 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 589 * Gap::clearScanResponse(). A former call to
Simon Cooksey 0:fb7af294d5d9 590 * ble.clearScanResponse(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 591 * ble.gap().clearScanResponse(...).
Simon Cooksey 0:fb7af294d5d9 592 */
Simon Cooksey 0:fb7af294d5d9 593 void clearScanResponse(void) {
Simon Cooksey 0:fb7af294d5d9 594 gap().clearScanResponse();
Simon Cooksey 0:fb7af294d5d9 595 }
Simon Cooksey 0:fb7af294d5d9 596
Simon Cooksey 0:fb7af294d5d9 597 /**
Simon Cooksey 0:fb7af294d5d9 598 * Start advertising.
Simon Cooksey 0:fb7af294d5d9 599 *
Simon Cooksey 0:fb7af294d5d9 600 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 601 * Gap::startAdvertising(). A former call to
Simon Cooksey 0:fb7af294d5d9 602 * ble.startAdvertising(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 603 * ble.gap().startAdvertising(...).
Simon Cooksey 0:fb7af294d5d9 604 */
Simon Cooksey 0:fb7af294d5d9 605 ble_error_t startAdvertising(void) {
Simon Cooksey 0:fb7af294d5d9 606 return gap().startAdvertising();
Simon Cooksey 0:fb7af294d5d9 607 }
Simon Cooksey 0:fb7af294d5d9 608
Simon Cooksey 0:fb7af294d5d9 609 /**
Simon Cooksey 0:fb7af294d5d9 610 * Stop advertising.
Simon Cooksey 0:fb7af294d5d9 611 *
Simon Cooksey 0:fb7af294d5d9 612 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 613 * Gap::stopAdvertising(). A former call to
Simon Cooksey 0:fb7af294d5d9 614 * ble.stopAdvertising(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 615 * ble.gap().stopAdvertising(...).
Simon Cooksey 0:fb7af294d5d9 616 */
Simon Cooksey 0:fb7af294d5d9 617 ble_error_t stopAdvertising(void) {
Simon Cooksey 0:fb7af294d5d9 618 return gap().stopAdvertising();
Simon Cooksey 0:fb7af294d5d9 619 }
Simon Cooksey 0:fb7af294d5d9 620
Simon Cooksey 0:fb7af294d5d9 621 /**
Simon Cooksey 0:fb7af294d5d9 622 * Set up parameters for GAP scanning (observer mode).
Simon Cooksey 0:fb7af294d5d9 623 * @param[in] interval
Simon Cooksey 0:fb7af294d5d9 624 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
Simon Cooksey 0:fb7af294d5d9 625 * @param[in] window
Simon Cooksey 0:fb7af294d5d9 626 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
Simon Cooksey 0:fb7af294d5d9 627 * @param[in] timeout
Simon Cooksey 0:fb7af294d5d9 628 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
Simon Cooksey 0:fb7af294d5d9 629 * @param[in] activeScanning
Simon Cooksey 0:fb7af294d5d9 630 * Set to True if active-scanning is required. This is used to fetch the
Simon Cooksey 0:fb7af294d5d9 631 * scan response from a peer if possible.
Simon Cooksey 0:fb7af294d5d9 632 *
Simon Cooksey 0:fb7af294d5d9 633 * The scanning window divided by the interval determines the duty cycle for
Simon Cooksey 0:fb7af294d5d9 634 * scanning. For example, if the interval is 100ms and the window is 10ms,
Simon Cooksey 0:fb7af294d5d9 635 * then the controller will scan for 10 percent of the time. It is possible
Simon Cooksey 0:fb7af294d5d9 636 * to have the interval and window set to the same value. In this case,
Simon Cooksey 0:fb7af294d5d9 637 * scanning is continuous, with a change of scanning frequency once every
Simon Cooksey 0:fb7af294d5d9 638 * interval.
Simon Cooksey 0:fb7af294d5d9 639 *
Simon Cooksey 0:fb7af294d5d9 640 * Once the scanning parameters have been configured, scanning can be
Simon Cooksey 0:fb7af294d5d9 641 * enabled by using startScan().
Simon Cooksey 0:fb7af294d5d9 642 *
Simon Cooksey 0:fb7af294d5d9 643 * @note The scan interval and window are recommendations to the BLE stack.
Simon Cooksey 0:fb7af294d5d9 644 *
Simon Cooksey 0:fb7af294d5d9 645 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 646 * Gap::setScanParams(). A former call to
Simon Cooksey 0:fb7af294d5d9 647 * ble.setScanParams(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 648 * ble.gap().setScanParams(...).
Simon Cooksey 0:fb7af294d5d9 649 */
Simon Cooksey 0:fb7af294d5d9 650 ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
Simon Cooksey 0:fb7af294d5d9 651 uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
Simon Cooksey 0:fb7af294d5d9 652 uint16_t timeout = 0,
Simon Cooksey 0:fb7af294d5d9 653 bool activeScanning = false) {
Simon Cooksey 0:fb7af294d5d9 654 return gap().setScanParams(interval, window, timeout, activeScanning);
Simon Cooksey 0:fb7af294d5d9 655 }
Simon Cooksey 0:fb7af294d5d9 656
Simon Cooksey 0:fb7af294d5d9 657 /**
Simon Cooksey 0:fb7af294d5d9 658 * Set up the scanInterval parameter for GAP scanning (observer mode).
Simon Cooksey 0:fb7af294d5d9 659 * @param[in] interval
Simon Cooksey 0:fb7af294d5d9 660 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
Simon Cooksey 0:fb7af294d5d9 661 *
Simon Cooksey 0:fb7af294d5d9 662 * The scanning window divided by the interval determines the duty cycle for
Simon Cooksey 0:fb7af294d5d9 663 * scanning. For example, if the interval is 100ms and the window is 10ms,
Simon Cooksey 0:fb7af294d5d9 664 * then the controller will scan for 10 percent of the time. It is possible
Simon Cooksey 0:fb7af294d5d9 665 * to have the interval and window set to the same value. In this case,
Simon Cooksey 0:fb7af294d5d9 666 * scanning is continuous, with a change of scanning frequency once every
Simon Cooksey 0:fb7af294d5d9 667 * interval.
Simon Cooksey 0:fb7af294d5d9 668 *
Simon Cooksey 0:fb7af294d5d9 669 * Once the scanning parameters have been configured, scanning can be
Simon Cooksey 0:fb7af294d5d9 670 * enabled by using startScan().
Simon Cooksey 0:fb7af294d5d9 671 *
Simon Cooksey 0:fb7af294d5d9 672 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 673 * Gap::setScanInterval(). A former call to
Simon Cooksey 0:fb7af294d5d9 674 * ble.setScanInterval(interval) should be replaced with
Simon Cooksey 0:fb7af294d5d9 675 * ble.gap().setScanInterval(interval).
Simon Cooksey 0:fb7af294d5d9 676 */
Simon Cooksey 0:fb7af294d5d9 677 ble_error_t setScanInterval(uint16_t interval) {
Simon Cooksey 0:fb7af294d5d9 678 return gap().setScanInterval(interval);
Simon Cooksey 0:fb7af294d5d9 679 }
Simon Cooksey 0:fb7af294d5d9 680
Simon Cooksey 0:fb7af294d5d9 681 /**
Simon Cooksey 0:fb7af294d5d9 682 * Set up the scanWindow parameter for GAP scanning (observer mode).
Simon Cooksey 0:fb7af294d5d9 683 * @param[in] window
Simon Cooksey 0:fb7af294d5d9 684 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
Simon Cooksey 0:fb7af294d5d9 685 *
Simon Cooksey 0:fb7af294d5d9 686 * The scanning window divided by the interval determines the duty cycle for
Simon Cooksey 0:fb7af294d5d9 687 * scanning. For example, if the interval is 100ms and the window is 10ms,
Simon Cooksey 0:fb7af294d5d9 688 * then the controller will scan for 10 percent of the time. It is possible
Simon Cooksey 0:fb7af294d5d9 689 * to have the interval and window set to the same value. In this case,
Simon Cooksey 0:fb7af294d5d9 690 * scanning is continuous, with a change of scanning frequency once every
Simon Cooksey 0:fb7af294d5d9 691 * interval.
Simon Cooksey 0:fb7af294d5d9 692 *
Simon Cooksey 0:fb7af294d5d9 693 * Once the scanning parameters have been configured, scanning can be
Simon Cooksey 0:fb7af294d5d9 694 * enabled by using startScan().
Simon Cooksey 0:fb7af294d5d9 695 *
Simon Cooksey 0:fb7af294d5d9 696 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 697 * Gap::setScanWindow(). A former call to
Simon Cooksey 0:fb7af294d5d9 698 * ble.setScanWindow(window) should be replaced with
Simon Cooksey 0:fb7af294d5d9 699 * ble.gap().setScanWindow(window).
Simon Cooksey 0:fb7af294d5d9 700 */
Simon Cooksey 0:fb7af294d5d9 701 ble_error_t setScanWindow(uint16_t window) {
Simon Cooksey 0:fb7af294d5d9 702 return gap().setScanWindow(window);
Simon Cooksey 0:fb7af294d5d9 703 }
Simon Cooksey 0:fb7af294d5d9 704
Simon Cooksey 0:fb7af294d5d9 705 /**
Simon Cooksey 0:fb7af294d5d9 706 * Set up parameters for GAP scanning (observer mode).
Simon Cooksey 0:fb7af294d5d9 707 * @param[in] timeout
Simon Cooksey 0:fb7af294d5d9 708 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
Simon Cooksey 0:fb7af294d5d9 709 *
Simon Cooksey 0:fb7af294d5d9 710 * The scanning window divided by the interval determines the duty cycle for
Simon Cooksey 0:fb7af294d5d9 711 * scanning. For example, if the interval is 100ms and the window is 10ms,
Simon Cooksey 0:fb7af294d5d9 712 * then the controller will scan for 10 percent of the time. It is possible
Simon Cooksey 0:fb7af294d5d9 713 * to have the interval and window set to the same value. In this case,
Simon Cooksey 0:fb7af294d5d9 714 * scanning is continuous, with a change of scanning frequency once every
Simon Cooksey 0:fb7af294d5d9 715 * interval.
Simon Cooksey 0:fb7af294d5d9 716 *
Simon Cooksey 0:fb7af294d5d9 717 * Once the scanning parameters have been configured, scanning can be
Simon Cooksey 0:fb7af294d5d9 718 * enabled by using startScan().
Simon Cooksey 0:fb7af294d5d9 719 *
Simon Cooksey 0:fb7af294d5d9 720 * @note The scan interval and window are recommendations to the BLE stack.
Simon Cooksey 0:fb7af294d5d9 721 *
Simon Cooksey 0:fb7af294d5d9 722 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 723 * Gap::setScanTimeout(). A former call to
Simon Cooksey 0:fb7af294d5d9 724 * ble.setScanTimeout(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 725 * ble.gap().setScanTimeout(...).
Simon Cooksey 0:fb7af294d5d9 726 */
Simon Cooksey 0:fb7af294d5d9 727 ble_error_t setScanTimeout(uint16_t timeout) {
Simon Cooksey 0:fb7af294d5d9 728 return gap().setScanTimeout(timeout);
Simon Cooksey 0:fb7af294d5d9 729 }
Simon Cooksey 0:fb7af294d5d9 730
Simon Cooksey 0:fb7af294d5d9 731 /**
Simon Cooksey 0:fb7af294d5d9 732 * Set up parameters for GAP scanning (observer mode).
Simon Cooksey 0:fb7af294d5d9 733 * @param[in] activeScanning
Simon Cooksey 0:fb7af294d5d9 734 * Set to True if active-scanning is required. This is used to fetch the
Simon Cooksey 0:fb7af294d5d9 735 * scan response from a peer if possible.
Simon Cooksey 0:fb7af294d5d9 736 *
Simon Cooksey 0:fb7af294d5d9 737 * Once the scanning parameters have been configured, scanning can be
Simon Cooksey 0:fb7af294d5d9 738 * enabled by using startScan().
Simon Cooksey 0:fb7af294d5d9 739 *
Simon Cooksey 0:fb7af294d5d9 740 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 741 * Gap::setActiveScan(). A former call to
Simon Cooksey 0:fb7af294d5d9 742 * ble.setActiveScan(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 743 * ble.gap().setActiveScanning(...).
Simon Cooksey 0:fb7af294d5d9 744 */
Simon Cooksey 0:fb7af294d5d9 745 void setActiveScan(bool activeScanning) {
Simon Cooksey 0:fb7af294d5d9 746 gap().setActiveScanning(activeScanning);
Simon Cooksey 0:fb7af294d5d9 747 }
Simon Cooksey 0:fb7af294d5d9 748
Simon Cooksey 0:fb7af294d5d9 749 /**
Simon Cooksey 0:fb7af294d5d9 750 * Start scanning (Observer Procedure) based on the parameters currently in
Simon Cooksey 0:fb7af294d5d9 751 * effect.
Simon Cooksey 0:fb7af294d5d9 752 *
Simon Cooksey 0:fb7af294d5d9 753 * @param[in] callback
Simon Cooksey 0:fb7af294d5d9 754 * The application-specific callback to be invoked upon
Simon Cooksey 0:fb7af294d5d9 755 * receiving every advertisement report. This can be passed in
Simon Cooksey 0:fb7af294d5d9 756 * as NULL, in which case scanning may not be enabled at all.
Simon Cooksey 0:fb7af294d5d9 757 *
Simon Cooksey 0:fb7af294d5d9 758 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 759 * Gap::startScan(). A former call to
Simon Cooksey 0:fb7af294d5d9 760 * ble.startScan(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 761 * ble.gap().startScan(callback).
Simon Cooksey 0:fb7af294d5d9 762 */
Simon Cooksey 0:fb7af294d5d9 763 ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params)) {
Simon Cooksey 0:fb7af294d5d9 764 return gap().startScan(callback);
Simon Cooksey 0:fb7af294d5d9 765 }
Simon Cooksey 0:fb7af294d5d9 766
Simon Cooksey 0:fb7af294d5d9 767 /**
Simon Cooksey 0:fb7af294d5d9 768 * Same as above, but this takes an (object, method) pair for a callback.
Simon Cooksey 0:fb7af294d5d9 769 *
Simon Cooksey 0:fb7af294d5d9 770 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 771 * Gap::startScan(). A former call to
Simon Cooksey 0:fb7af294d5d9 772 * ble.startScan(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 773 * ble.gap().startScan(object, callback).
Simon Cooksey 0:fb7af294d5d9 774 */
Simon Cooksey 0:fb7af294d5d9 775 template<typename T>
Simon Cooksey 0:fb7af294d5d9 776 ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params));
Simon Cooksey 0:fb7af294d5d9 777
Simon Cooksey 0:fb7af294d5d9 778 /**
Simon Cooksey 0:fb7af294d5d9 779 * Stop scanning. The current scanning parameters remain in effect.
Simon Cooksey 0:fb7af294d5d9 780 *
Simon Cooksey 0:fb7af294d5d9 781 * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
Simon Cooksey 0:fb7af294d5d9 782 *
Simon Cooksey 0:fb7af294d5d9 783 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 784 * Gap::stopScan(). A former call to
Simon Cooksey 0:fb7af294d5d9 785 * ble.stopScan() should be replaced with
Simon Cooksey 0:fb7af294d5d9 786 * ble.gap().stopScan().
Simon Cooksey 0:fb7af294d5d9 787 */
Simon Cooksey 0:fb7af294d5d9 788 ble_error_t stopScan(void) {
Simon Cooksey 0:fb7af294d5d9 789 return gap().stopScan();
Simon Cooksey 0:fb7af294d5d9 790 }
Simon Cooksey 0:fb7af294d5d9 791
Simon Cooksey 0:fb7af294d5d9 792 /**
Simon Cooksey 0:fb7af294d5d9 793 * Create a connection (GAP Link Establishment).
Simon Cooksey 0:fb7af294d5d9 794 * @param peerAddr
Simon Cooksey 0:fb7af294d5d9 795 * 48-bit address, LSB format.
Simon Cooksey 0:fb7af294d5d9 796 * @param peerAddrType
Simon Cooksey 0:fb7af294d5d9 797 * Address type of the peer.
Simon Cooksey 0:fb7af294d5d9 798 * @param connectionParams
Simon Cooksey 0:fb7af294d5d9 799 * Connection parameters.
Simon Cooksey 0:fb7af294d5d9 800 * @param scanParams
Simon Cooksey 0:fb7af294d5d9 801 * Paramters to use while scanning for the peer.
Simon Cooksey 0:fb7af294d5d9 802 * @return BLE_ERROR_NONE if connection establishment procedure is started
Simon Cooksey 0:fb7af294d5d9 803 * successfully. The onConnection callback (if set) is invoked upon
Simon Cooksey 0:fb7af294d5d9 804 * a connection event.
Simon Cooksey 0:fb7af294d5d9 805 *
Simon Cooksey 0:fb7af294d5d9 806 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 807 * Gap::connect(). A former call to
Simon Cooksey 0:fb7af294d5d9 808 * ble.connect(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 809 * ble.gap().connect(...).
Simon Cooksey 0:fb7af294d5d9 810 */
Simon Cooksey 0:fb7af294d5d9 811 ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
Simon Cooksey 0:fb7af294d5d9 812 BLEProtocol::AddressType_t peerAddrType = BLEProtocol::AddressType::RANDOM_STATIC,
Simon Cooksey 0:fb7af294d5d9 813 const Gap::ConnectionParams_t *connectionParams = NULL,
Simon Cooksey 0:fb7af294d5d9 814 const GapScanningParams *scanParams = NULL) {
Simon Cooksey 0:fb7af294d5d9 815 return gap().connect(peerAddr, peerAddrType, connectionParams, scanParams);
Simon Cooksey 0:fb7af294d5d9 816 }
Simon Cooksey 0:fb7af294d5d9 817
Simon Cooksey 0:fb7af294d5d9 818 /**
Simon Cooksey 0:fb7af294d5d9 819 * This call initiates the disconnection procedure, and its completion is
Simon Cooksey 0:fb7af294d5d9 820 * communicated to the application with an invocation of the
Simon Cooksey 0:fb7af294d5d9 821 * onDisconnection callback.
Simon Cooksey 0:fb7af294d5d9 822 *
Simon Cooksey 0:fb7af294d5d9 823 * @param[in] connectionHandle
Simon Cooksey 0:fb7af294d5d9 824 * @param[in] reason
Simon Cooksey 0:fb7af294d5d9 825 * The reason for disconnection; sent back to the peer.
Simon Cooksey 0:fb7af294d5d9 826 */
Simon Cooksey 0:fb7af294d5d9 827 ble_error_t disconnect(Gap::Handle_t connectionHandle, Gap::DisconnectionReason_t reason) {
Simon Cooksey 0:fb7af294d5d9 828 return gap().disconnect(connectionHandle, reason);
Simon Cooksey 0:fb7af294d5d9 829 }
Simon Cooksey 0:fb7af294d5d9 830
Simon Cooksey 0:fb7af294d5d9 831 /**
Simon Cooksey 0:fb7af294d5d9 832 * This call initiates the disconnection procedure, and its completion
Simon Cooksey 0:fb7af294d5d9 833 * is communicated to the application with an invocation of the
Simon Cooksey 0:fb7af294d5d9 834 * onDisconnection callback.
Simon Cooksey 0:fb7af294d5d9 835 *
Simon Cooksey 0:fb7af294d5d9 836 * @param reason
Simon Cooksey 0:fb7af294d5d9 837 * The reason for disconnection; sent back to the peer.
Simon Cooksey 0:fb7af294d5d9 838 *
Simon Cooksey 0:fb7af294d5d9 839 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 840 * Gap::disconnect(). A former call to
Simon Cooksey 0:fb7af294d5d9 841 * ble.disconnect(reason) should be replaced with
Simon Cooksey 0:fb7af294d5d9 842 * ble.gap().disconnect(reason).
Simon Cooksey 0:fb7af294d5d9 843 *
Simon Cooksey 0:fb7af294d5d9 844 * @note This version of disconnect() doesn't take a connection handle. It
Simon Cooksey 0:fb7af294d5d9 845 * works reliably only for stacks that are limited to a single
Simon Cooksey 0:fb7af294d5d9 846 * connection.
Simon Cooksey 0:fb7af294d5d9 847 */
Simon Cooksey 0:fb7af294d5d9 848 ble_error_t disconnect(Gap::DisconnectionReason_t reason) {
Simon Cooksey 0:fb7af294d5d9 849 return gap().disconnect(reason);
Simon Cooksey 0:fb7af294d5d9 850 }
Simon Cooksey 0:fb7af294d5d9 851
Simon Cooksey 0:fb7af294d5d9 852 /**
Simon Cooksey 0:fb7af294d5d9 853 * Returns the current Gap state of the device using a bitmask that
Simon Cooksey 0:fb7af294d5d9 854 * describes whether the device is advertising or connected.
Simon Cooksey 0:fb7af294d5d9 855 *
Simon Cooksey 0:fb7af294d5d9 856 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 857 * Gap::getState(). A former call to
Simon Cooksey 0:fb7af294d5d9 858 * ble.getGapState() should be replaced with
Simon Cooksey 0:fb7af294d5d9 859 * ble.gap().getState().
Simon Cooksey 0:fb7af294d5d9 860 */
Simon Cooksey 0:fb7af294d5d9 861 Gap::GapState_t getGapState(void) const {
Simon Cooksey 0:fb7af294d5d9 862 return gap().getState();
Simon Cooksey 0:fb7af294d5d9 863 }
Simon Cooksey 0:fb7af294d5d9 864
Simon Cooksey 0:fb7af294d5d9 865 /**
Simon Cooksey 0:fb7af294d5d9 866 * Get the GAP peripheral's preferred connection parameters. These are the
Simon Cooksey 0:fb7af294d5d9 867 * defaults that the peripheral would like to have in a connection. The
Simon Cooksey 0:fb7af294d5d9 868 * choice of the connection parameters is eventually up to the central.
Simon Cooksey 0:fb7af294d5d9 869 *
Simon Cooksey 0:fb7af294d5d9 870 * @param[out] params
Simon Cooksey 0:fb7af294d5d9 871 * The structure where the parameters will be stored. Memory
Simon Cooksey 0:fb7af294d5d9 872 * for this is owned by the caller.
Simon Cooksey 0:fb7af294d5d9 873 *
Simon Cooksey 0:fb7af294d5d9 874 * @return BLE_ERROR_NONE if the parameters were successfully filled into
Simon Cooksey 0:fb7af294d5d9 875 * the given structure pointed to by params.
Simon Cooksey 0:fb7af294d5d9 876 *
Simon Cooksey 0:fb7af294d5d9 877 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 878 * Gap::getPreferredConnectionParams(). A former call to
Simon Cooksey 0:fb7af294d5d9 879 * ble.getPreferredConnectionParams() should be replaced with
Simon Cooksey 0:fb7af294d5d9 880 * ble.gap().getPreferredConnectionParams().
Simon Cooksey 0:fb7af294d5d9 881 */
Simon Cooksey 0:fb7af294d5d9 882 ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params) {
Simon Cooksey 0:fb7af294d5d9 883 return gap().getPreferredConnectionParams(params);
Simon Cooksey 0:fb7af294d5d9 884 }
Simon Cooksey 0:fb7af294d5d9 885
Simon Cooksey 0:fb7af294d5d9 886 /**
Simon Cooksey 0:fb7af294d5d9 887 * Set the GAP peripheral's preferred connection parameters. These are the
Simon Cooksey 0:fb7af294d5d9 888 * defaults that the peripheral would like to have in a connection. The
Simon Cooksey 0:fb7af294d5d9 889 * choice of the connection parameters is eventually up to the central.
Simon Cooksey 0:fb7af294d5d9 890 *
Simon Cooksey 0:fb7af294d5d9 891 * @param[in] params
Simon Cooksey 0:fb7af294d5d9 892 * The structure containing the desired parameters.
Simon Cooksey 0:fb7af294d5d9 893 *
Simon Cooksey 0:fb7af294d5d9 894 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 895 * Gap::setPreferredConnectionParams(). A former call to
Simon Cooksey 0:fb7af294d5d9 896 * ble.setPreferredConnectionParams() should be replaced with
Simon Cooksey 0:fb7af294d5d9 897 * ble.gap().setPreferredConnectionParams().
Simon Cooksey 0:fb7af294d5d9 898 */
Simon Cooksey 0:fb7af294d5d9 899 ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params) {
Simon Cooksey 0:fb7af294d5d9 900 return gap().setPreferredConnectionParams(params);
Simon Cooksey 0:fb7af294d5d9 901 }
Simon Cooksey 0:fb7af294d5d9 902
Simon Cooksey 0:fb7af294d5d9 903 /**
Simon Cooksey 0:fb7af294d5d9 904 * Update connection parameters while in the peripheral role.
Simon Cooksey 0:fb7af294d5d9 905 * @details In the peripheral role, this will send the corresponding L2CAP request to the connected peer and wait for
Simon Cooksey 0:fb7af294d5d9 906 * the central to perform the procedure.
Simon Cooksey 0:fb7af294d5d9 907 * @param[in] handle
Simon Cooksey 0:fb7af294d5d9 908 * Connection Handle
Simon Cooksey 0:fb7af294d5d9 909 * @param[in] params
Simon Cooksey 0:fb7af294d5d9 910 * Pointer to desired connection parameters. If NULL is provided on a peripheral role,
Simon Cooksey 0:fb7af294d5d9 911 * the parameters in the PPCP characteristic of the GAP service will be used instead.
Simon Cooksey 0:fb7af294d5d9 912 *
Simon Cooksey 0:fb7af294d5d9 913 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 914 * Gap::updateConnectionParams(). A former call to
Simon Cooksey 0:fb7af294d5d9 915 * ble.updateConnectionParams() should be replaced with
Simon Cooksey 0:fb7af294d5d9 916 * ble.gap().updateConnectionParams().
Simon Cooksey 0:fb7af294d5d9 917 */
Simon Cooksey 0:fb7af294d5d9 918 ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) {
Simon Cooksey 0:fb7af294d5d9 919 return gap().updateConnectionParams(handle, params);
Simon Cooksey 0:fb7af294d5d9 920 }
Simon Cooksey 0:fb7af294d5d9 921
Simon Cooksey 0:fb7af294d5d9 922 /**
Simon Cooksey 0:fb7af294d5d9 923 * Set the device name characteristic in the Gap service.
Simon Cooksey 0:fb7af294d5d9 924 * @param[in] deviceName
Simon Cooksey 0:fb7af294d5d9 925 * The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
Simon Cooksey 0:fb7af294d5d9 926 *
Simon Cooksey 0:fb7af294d5d9 927 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 928 * Gap::setDeviceName(). A former call to
Simon Cooksey 0:fb7af294d5d9 929 * ble.setDeviceName() should be replaced with
Simon Cooksey 0:fb7af294d5d9 930 * ble.gap().setDeviceName().
Simon Cooksey 0:fb7af294d5d9 931 */
Simon Cooksey 0:fb7af294d5d9 932 ble_error_t setDeviceName(const uint8_t *deviceName) {
Simon Cooksey 0:fb7af294d5d9 933 return gap().setDeviceName(deviceName);
Simon Cooksey 0:fb7af294d5d9 934 }
Simon Cooksey 0:fb7af294d5d9 935
Simon Cooksey 0:fb7af294d5d9 936 /**
Simon Cooksey 0:fb7af294d5d9 937 * Get the value of the device name characteristic in the Gap service.
Simon Cooksey 0:fb7af294d5d9 938 * @param[out] deviceName
Simon Cooksey 0:fb7af294d5d9 939 * Pointer to an empty buffer where the UTF-8 *non NULL-
Simon Cooksey 0:fb7af294d5d9 940 * terminated* string will be placed. Set this
Simon Cooksey 0:fb7af294d5d9 941 * value to NULL in order to obtain the deviceName-length
Simon Cooksey 0:fb7af294d5d9 942 * from the 'length' parameter.
Simon Cooksey 0:fb7af294d5d9 943 *
Simon Cooksey 0:fb7af294d5d9 944 * @param[in,out] lengthP
Simon Cooksey 0:fb7af294d5d9 945 * (on input) Length of the buffer pointed to by deviceName;
Simon Cooksey 0:fb7af294d5d9 946 * (on output) the complete device name length (without the
Simon Cooksey 0:fb7af294d5d9 947 * null terminator).
Simon Cooksey 0:fb7af294d5d9 948 *
Simon Cooksey 0:fb7af294d5d9 949 * @note If the device name is longer than the size of the supplied buffer,
Simon Cooksey 0:fb7af294d5d9 950 * length will return the complete device name length, and not the
Simon Cooksey 0:fb7af294d5d9 951 * number of bytes actually returned in deviceName. The application may
Simon Cooksey 0:fb7af294d5d9 952 * use this information to retry with a suitable buffer size.
Simon Cooksey 0:fb7af294d5d9 953 *
Simon Cooksey 0:fb7af294d5d9 954 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 955 * Gap::getDeviceName(). A former call to
Simon Cooksey 0:fb7af294d5d9 956 * ble.getDeviceName() should be replaced with
Simon Cooksey 0:fb7af294d5d9 957 * ble.gap().getDeviceName().
Simon Cooksey 0:fb7af294d5d9 958 */
Simon Cooksey 0:fb7af294d5d9 959 ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
Simon Cooksey 0:fb7af294d5d9 960 return gap().getDeviceName(deviceName, lengthP);
Simon Cooksey 0:fb7af294d5d9 961 }
Simon Cooksey 0:fb7af294d5d9 962
Simon Cooksey 0:fb7af294d5d9 963 /**
Simon Cooksey 0:fb7af294d5d9 964 * Set the appearance characteristic in the Gap service.
Simon Cooksey 0:fb7af294d5d9 965 * @param[in] appearance
Simon Cooksey 0:fb7af294d5d9 966 * The new value for the device-appearance.
Simon Cooksey 0:fb7af294d5d9 967 *
Simon Cooksey 0:fb7af294d5d9 968 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 969 * Gap::setAppearance(). A former call to
Simon Cooksey 0:fb7af294d5d9 970 * ble.setAppearance() should be replaced with
Simon Cooksey 0:fb7af294d5d9 971 * ble.gap().setAppearance().
Simon Cooksey 0:fb7af294d5d9 972 */
Simon Cooksey 0:fb7af294d5d9 973 ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
Simon Cooksey 0:fb7af294d5d9 974 return gap().setAppearance(appearance);
Simon Cooksey 0:fb7af294d5d9 975 }
Simon Cooksey 0:fb7af294d5d9 976
Simon Cooksey 0:fb7af294d5d9 977 /**
Simon Cooksey 0:fb7af294d5d9 978 * Get the appearance characteristic in the Gap service.
Simon Cooksey 0:fb7af294d5d9 979 * @param[out] appearanceP
Simon Cooksey 0:fb7af294d5d9 980 * The new value for the device-appearance.
Simon Cooksey 0:fb7af294d5d9 981 *
Simon Cooksey 0:fb7af294d5d9 982 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 983 * Gap::getAppearance(). A former call to
Simon Cooksey 0:fb7af294d5d9 984 * ble.getAppearance() should be replaced with
Simon Cooksey 0:fb7af294d5d9 985 * ble.gap().getAppearance().
Simon Cooksey 0:fb7af294d5d9 986 */
Simon Cooksey 0:fb7af294d5d9 987 ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
Simon Cooksey 0:fb7af294d5d9 988 return gap().getAppearance(appearanceP);
Simon Cooksey 0:fb7af294d5d9 989 }
Simon Cooksey 0:fb7af294d5d9 990
Simon Cooksey 0:fb7af294d5d9 991 /**
Simon Cooksey 0:fb7af294d5d9 992 * Set the radio's transmit power.
Simon Cooksey 0:fb7af294d5d9 993 * @param[in] txPower Radio transmit power in dBm.
Simon Cooksey 0:fb7af294d5d9 994 *
Simon Cooksey 0:fb7af294d5d9 995 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 996 * Gap::setTxPower(). A former call to
Simon Cooksey 0:fb7af294d5d9 997 * ble.setTxPower() should be replaced with
Simon Cooksey 0:fb7af294d5d9 998 * ble.gap().setTxPower().
Simon Cooksey 0:fb7af294d5d9 999 */
Simon Cooksey 0:fb7af294d5d9 1000 ble_error_t setTxPower(int8_t txPower) {
Simon Cooksey 0:fb7af294d5d9 1001 return gap().setTxPower(txPower);
Simon Cooksey 0:fb7af294d5d9 1002 }
Simon Cooksey 0:fb7af294d5d9 1003
Simon Cooksey 0:fb7af294d5d9 1004 /**
Simon Cooksey 0:fb7af294d5d9 1005 * Query the underlying stack for permitted arguments for setTxPower().
Simon Cooksey 0:fb7af294d5d9 1006 *
Simon Cooksey 0:fb7af294d5d9 1007 * @param[out] valueArrayPP
Simon Cooksey 0:fb7af294d5d9 1008 * Out parameter to receive the immutable array of Tx values.
Simon Cooksey 0:fb7af294d5d9 1009 * @param[out] countP
Simon Cooksey 0:fb7af294d5d9 1010 * Out parameter to receive the array's size.
Simon Cooksey 0:fb7af294d5d9 1011 *
Simon Cooksey 0:fb7af294d5d9 1012 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 1013 * Gap::getPermittedTxPowerValues(). A former call to
Simon Cooksey 0:fb7af294d5d9 1014 * ble.getPermittedTxPowerValues() should be replaced with
Simon Cooksey 0:fb7af294d5d9 1015 * ble.gap().getPermittedTxPowerValues().
Simon Cooksey 0:fb7af294d5d9 1016 */
Simon Cooksey 0:fb7af294d5d9 1017 void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
Simon Cooksey 0:fb7af294d5d9 1018 gap().getPermittedTxPowerValues(valueArrayPP, countP);
Simon Cooksey 0:fb7af294d5d9 1019 }
Simon Cooksey 0:fb7af294d5d9 1020
Simon Cooksey 0:fb7af294d5d9 1021 /**
Simon Cooksey 0:fb7af294d5d9 1022 * Add a service declaration to the local server ATT table. Also add the
Simon Cooksey 0:fb7af294d5d9 1023 * characteristics contained within.
Simon Cooksey 0:fb7af294d5d9 1024 *
Simon Cooksey 0:fb7af294d5d9 1025 * @deprecated You should use the parallel API from GattServer directly, refer to
Simon Cooksey 0:fb7af294d5d9 1026 * GattServer::addService(). A former call
Simon Cooksey 0:fb7af294d5d9 1027 * to ble.addService() should be replaced with
Simon Cooksey 0:fb7af294d5d9 1028 * ble.gattServer().addService().
Simon Cooksey 0:fb7af294d5d9 1029 */
Simon Cooksey 0:fb7af294d5d9 1030 ble_error_t addService(GattService &service) {
Simon Cooksey 0:fb7af294d5d9 1031 return gattServer().addService(service);
Simon Cooksey 0:fb7af294d5d9 1032 }
Simon Cooksey 0:fb7af294d5d9 1033
Simon Cooksey 0:fb7af294d5d9 1034 /**
Simon Cooksey 0:fb7af294d5d9 1035 * Read the value of a characteristic from the local GattServer.
Simon Cooksey 0:fb7af294d5d9 1036 * @param[in] attributeHandle
Simon Cooksey 0:fb7af294d5d9 1037 * Attribute handle for the value attribute of the characteristic.
Simon Cooksey 0:fb7af294d5d9 1038 * @param[out] buffer
Simon Cooksey 0:fb7af294d5d9 1039 * A buffer to hold the value being read.
Simon Cooksey 0:fb7af294d5d9 1040 * @param[in,out] lengthP
Simon Cooksey 0:fb7af294d5d9 1041 * Length of the buffer being supplied. If the attribute
Simon Cooksey 0:fb7af294d5d9 1042 * value is longer than the size of the supplied buffer,
Simon Cooksey 0:fb7af294d5d9 1043 * this variable will return the total attribute value length
Simon Cooksey 0:fb7af294d5d9 1044 * (excluding offset). The application may use this
Simon Cooksey 0:fb7af294d5d9 1045 * information to allocate a suitable buffer size.
Simon Cooksey 0:fb7af294d5d9 1046 *
Simon Cooksey 0:fb7af294d5d9 1047 * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
Simon Cooksey 0:fb7af294d5d9 1048 *
Simon Cooksey 0:fb7af294d5d9 1049 * @deprecated You should use the parallel API from GattServer directly,
Simon Cooksey 0:fb7af294d5d9 1050 * GattServer::read(GattAttribute::Handle_t,uint8_t,uint16_t). A former call
Simon Cooksey 0:fb7af294d5d9 1051 * to ble.readCharacteristicValue() should be replaced with
Simon Cooksey 0:fb7af294d5d9 1052 * ble.gattServer().read().
Simon Cooksey 0:fb7af294d5d9 1053 */
Simon Cooksey 0:fb7af294d5d9 1054 ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
Simon Cooksey 0:fb7af294d5d9 1055 return gattServer().read(attributeHandle, buffer, lengthP);
Simon Cooksey 0:fb7af294d5d9 1056 }
Simon Cooksey 0:fb7af294d5d9 1057
Simon Cooksey 0:fb7af294d5d9 1058 /**
Simon Cooksey 0:fb7af294d5d9 1059 * Read the value of a characteristic from the local GattServer.
Simon Cooksey 0:fb7af294d5d9 1060 * @param[in] connectionHandle
Simon Cooksey 0:fb7af294d5d9 1061 * Connection Handle.
Simon Cooksey 0:fb7af294d5d9 1062 * @param[in] attributeHandle
Simon Cooksey 0:fb7af294d5d9 1063 * Attribute handle for the value attribute of the characteristic.
Simon Cooksey 0:fb7af294d5d9 1064 * @param[out] buffer
Simon Cooksey 0:fb7af294d5d9 1065 * A buffer to hold the value being read.
Simon Cooksey 0:fb7af294d5d9 1066 * @param[in,out] lengthP
Simon Cooksey 0:fb7af294d5d9 1067 * Length of the buffer being supplied. If the attribute
Simon Cooksey 0:fb7af294d5d9 1068 * value is longer than the size of the supplied buffer,
Simon Cooksey 0:fb7af294d5d9 1069 * this variable will return the total attribute value length
Simon Cooksey 0:fb7af294d5d9 1070 * (excluding offset). The application may use this
Simon Cooksey 0:fb7af294d5d9 1071 * information to allocate a suitable buffer size.
Simon Cooksey 0:fb7af294d5d9 1072 *
Simon Cooksey 0:fb7af294d5d9 1073 * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
Simon Cooksey 0:fb7af294d5d9 1074 *
Simon Cooksey 0:fb7af294d5d9 1075 * @note This API is a version of the above, with an additional connection handle
Simon Cooksey 0:fb7af294d5d9 1076 * parameter to allow fetches for connection-specific multivalued
Simon Cooksey 0:fb7af294d5d9 1077 * attributes (such as the CCCDs).
Simon Cooksey 0:fb7af294d5d9 1078 *
Simon Cooksey 0:fb7af294d5d9 1079 * @deprecated You should use the parallel API from GattServer directly, refer to
Simon Cooksey 0:fb7af294d5d9 1080 * GattServer::read(Gap::Handle_t,GattAttribute::Handle_t,uint8_t,uint16_t).
Simon Cooksey 0:fb7af294d5d9 1081 * A former call to ble.readCharacteristicValue() should be replaced with
Simon Cooksey 0:fb7af294d5d9 1082 * ble.gattServer().read().
Simon Cooksey 0:fb7af294d5d9 1083 */
Simon Cooksey 0:fb7af294d5d9 1084 ble_error_t readCharacteristicValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
Simon Cooksey 0:fb7af294d5d9 1085 return gattServer().read(connectionHandle, attributeHandle, buffer, lengthP);
Simon Cooksey 0:fb7af294d5d9 1086 }
Simon Cooksey 0:fb7af294d5d9 1087
Simon Cooksey 0:fb7af294d5d9 1088 /**
Simon Cooksey 0:fb7af294d5d9 1089 * Update the value of a characteristic on the local GattServer.
Simon Cooksey 0:fb7af294d5d9 1090 *
Simon Cooksey 0:fb7af294d5d9 1091 * @param[in] attributeHandle
Simon Cooksey 0:fb7af294d5d9 1092 * Handle for the value attribute of the characteristic.
Simon Cooksey 0:fb7af294d5d9 1093 * @param[in] value
Simon Cooksey 0:fb7af294d5d9 1094 * A pointer to a buffer holding the new value.
Simon Cooksey 0:fb7af294d5d9 1095 * @param[in] size
Simon Cooksey 0:fb7af294d5d9 1096 * Size of the new value (in bytes).
Simon Cooksey 0:fb7af294d5d9 1097 * @param[in] localOnly
Simon Cooksey 0:fb7af294d5d9 1098 * Should this update be kept on the local
Simon Cooksey 0:fb7af294d5d9 1099 * GattServer regardless of the state of the
Simon Cooksey 0:fb7af294d5d9 1100 * notify/indicate flag in the CCCD for this
Simon Cooksey 0:fb7af294d5d9 1101 * characteristic? If set to true, no notification
Simon Cooksey 0:fb7af294d5d9 1102 * or indication is generated.
Simon Cooksey 0:fb7af294d5d9 1103 *
Simon Cooksey 0:fb7af294d5d9 1104 * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
Simon Cooksey 0:fb7af294d5d9 1105 *
Simon Cooksey 0:fb7af294d5d9 1106 * @deprecated You should use the parallel API from GattServer directly, refer to
Simon Cooksey 0:fb7af294d5d9 1107 * GattServer::write(GattAttribute::Handle_t,const uint8_t,uint16_t,bool).
Simon Cooksey 0:fb7af294d5d9 1108 * A former call to ble.updateCharacteristicValue() should be replaced with
Simon Cooksey 0:fb7af294d5d9 1109 * ble.gattServer().write().
Simon Cooksey 0:fb7af294d5d9 1110 */
Simon Cooksey 0:fb7af294d5d9 1111 ble_error_t updateCharacteristicValue(GattAttribute::Handle_t attributeHandle,
Simon Cooksey 0:fb7af294d5d9 1112 const uint8_t *value,
Simon Cooksey 0:fb7af294d5d9 1113 uint16_t size,
Simon Cooksey 0:fb7af294d5d9 1114 bool localOnly = false) {
Simon Cooksey 0:fb7af294d5d9 1115 return gattServer().write(attributeHandle, value, size, localOnly);
Simon Cooksey 0:fb7af294d5d9 1116 }
Simon Cooksey 0:fb7af294d5d9 1117
Simon Cooksey 0:fb7af294d5d9 1118 /**
Simon Cooksey 0:fb7af294d5d9 1119 * Update the value of a characteristic on the local GattServer. A version
Simon Cooksey 0:fb7af294d5d9 1120 * of the above, with a connection handle parameter to allow updates
Simon Cooksey 0:fb7af294d5d9 1121 * for connection-specific multivalued attributes (such as the CCCDs).
Simon Cooksey 0:fb7af294d5d9 1122 *
Simon Cooksey 0:fb7af294d5d9 1123 * @param[in] connectionHandle
Simon Cooksey 0:fb7af294d5d9 1124 * Connection Handle.
Simon Cooksey 0:fb7af294d5d9 1125 * @param[in] attributeHandle
Simon Cooksey 0:fb7af294d5d9 1126 * Handle for the value attribute of the Characteristic.
Simon Cooksey 0:fb7af294d5d9 1127 * @param[in] value
Simon Cooksey 0:fb7af294d5d9 1128 * A pointer to a buffer holding the new value.
Simon Cooksey 0:fb7af294d5d9 1129 * @param[in] size
Simon Cooksey 0:fb7af294d5d9 1130 * Size of the new value (in bytes).
Simon Cooksey 0:fb7af294d5d9 1131 * @param[in] localOnly
Simon Cooksey 0:fb7af294d5d9 1132 * Should this update be kept on the local
Simon Cooksey 0:fb7af294d5d9 1133 * GattServer regardless of the state of the
Simon Cooksey 0:fb7af294d5d9 1134 * notify/indicate flag in the CCCD for this
Simon Cooksey 0:fb7af294d5d9 1135 * Characteristic? If set to true, no notification
Simon Cooksey 0:fb7af294d5d9 1136 * or indication is generated.
Simon Cooksey 0:fb7af294d5d9 1137 *
Simon Cooksey 0:fb7af294d5d9 1138 * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
Simon Cooksey 0:fb7af294d5d9 1139 *
Simon Cooksey 0:fb7af294d5d9 1140 * @deprecated You should use the parallel API from GattServer directly, refer to
Simon Cooksey 0:fb7af294d5d9 1141 * GattServer::write(Gap::Handle_t,GattAttribute::Handle_t,const uint8_t,uint16_t,bool).
Simon Cooksey 0:fb7af294d5d9 1142 * A former call to ble.updateCharacteristicValue() should be replaced with
Simon Cooksey 0:fb7af294d5d9 1143 * ble.gattServer().write().
Simon Cooksey 0:fb7af294d5d9 1144 */
Simon Cooksey 0:fb7af294d5d9 1145 ble_error_t updateCharacteristicValue(Gap::Handle_t connectionHandle,
Simon Cooksey 0:fb7af294d5d9 1146 GattAttribute::Handle_t attributeHandle,
Simon Cooksey 0:fb7af294d5d9 1147 const uint8_t *value,
Simon Cooksey 0:fb7af294d5d9 1148 uint16_t size,
Simon Cooksey 0:fb7af294d5d9 1149 bool localOnly = false) {
Simon Cooksey 0:fb7af294d5d9 1150 return gattServer().write(connectionHandle, attributeHandle, value, size, localOnly);
Simon Cooksey 0:fb7af294d5d9 1151 }
Simon Cooksey 0:fb7af294d5d9 1152
Simon Cooksey 0:fb7af294d5d9 1153 /**
Simon Cooksey 0:fb7af294d5d9 1154 * Enable the BLE stack's Security Manager. The Security Manager implements
Simon Cooksey 0:fb7af294d5d9 1155 * the cryptographic algorithms and protocol exchanges that allow two
Simon Cooksey 0:fb7af294d5d9 1156 * devices to securely exchange data and privately detect each other.
Simon Cooksey 0:fb7af294d5d9 1157 * Calling this API is a prerequisite for encryption and pairing (bonding).
Simon Cooksey 0:fb7af294d5d9 1158 *
Simon Cooksey 0:fb7af294d5d9 1159 * @param[in] enableBonding Allow for bonding.
Simon Cooksey 0:fb7af294d5d9 1160 * @param[in] requireMITM Require protection against man-in-the-middle attacks.
Simon Cooksey 0:fb7af294d5d9 1161 * @param[in] iocaps To specify the I/O capabilities of this peripheral,
Simon Cooksey 0:fb7af294d5d9 1162 * such as availability of a display or keyboard, to
Simon Cooksey 0:fb7af294d5d9 1163 * support out-of-band exchanges of security data.
Simon Cooksey 0:fb7af294d5d9 1164 * @param[in] passkey To specify a static passkey.
Simon Cooksey 0:fb7af294d5d9 1165 *
Simon Cooksey 0:fb7af294d5d9 1166 * @return BLE_ERROR_NONE on success.
Simon Cooksey 0:fb7af294d5d9 1167 *
Simon Cooksey 0:fb7af294d5d9 1168 * @deprecated You should use the parallel API from SecurityManager directly, refer to
Simon Cooksey 0:fb7af294d5d9 1169 * SecurityManager.init(). A former
Simon Cooksey 0:fb7af294d5d9 1170 * call to ble.initializeSecurity(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1171 * ble.securityManager().init(...).
Simon Cooksey 0:fb7af294d5d9 1172 */
Simon Cooksey 0:fb7af294d5d9 1173 ble_error_t initializeSecurity(bool enableBonding = true,
Simon Cooksey 0:fb7af294d5d9 1174 bool requireMITM = true,
Simon Cooksey 0:fb7af294d5d9 1175 SecurityManager::SecurityIOCapabilities_t iocaps = SecurityManager::IO_CAPS_NONE,
Simon Cooksey 0:fb7af294d5d9 1176 const SecurityManager::Passkey_t passkey = NULL) {
Simon Cooksey 0:fb7af294d5d9 1177 return securityManager().init(enableBonding, requireMITM, iocaps, passkey);
Simon Cooksey 0:fb7af294d5d9 1178 }
Simon Cooksey 0:fb7af294d5d9 1179
Simon Cooksey 0:fb7af294d5d9 1180 /**
Simon Cooksey 0:fb7af294d5d9 1181 * Get the security status of a connection.
Simon Cooksey 0:fb7af294d5d9 1182 *
Simon Cooksey 0:fb7af294d5d9 1183 * @param[in] connectionHandle Handle to identify the connection.
Simon Cooksey 0:fb7af294d5d9 1184 * @param[out] securityStatusP Security status.
Simon Cooksey 0:fb7af294d5d9 1185 *
Simon Cooksey 0:fb7af294d5d9 1186 * @return BLE_SUCCESS or appropriate error code indicating the reason of failure.
Simon Cooksey 0:fb7af294d5d9 1187 *
Simon Cooksey 0:fb7af294d5d9 1188 * @deprecated You should use the parallel API from SecurityManager directly, refer to
Simon Cooksey 0:fb7af294d5d9 1189 * SecurityManager::getLinkSecurity(). A former
Simon Cooksey 0:fb7af294d5d9 1190 * call to ble.getLinkSecurity(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1191 * ble.securityManager().getLinkSecurity(...).
Simon Cooksey 0:fb7af294d5d9 1192 */
Simon Cooksey 0:fb7af294d5d9 1193 ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) {
Simon Cooksey 0:fb7af294d5d9 1194 return securityManager().getLinkSecurity(connectionHandle, securityStatusP);
Simon Cooksey 0:fb7af294d5d9 1195 }
Simon Cooksey 0:fb7af294d5d9 1196
Simon Cooksey 0:fb7af294d5d9 1197 /**
Simon Cooksey 0:fb7af294d5d9 1198 * Delete all peer device context and all related bonding information from
Simon Cooksey 0:fb7af294d5d9 1199 * the database within the security manager.
Simon Cooksey 0:fb7af294d5d9 1200 *
Simon Cooksey 0:fb7af294d5d9 1201 * @retval BLE_ERROR_NONE On success; else returns an error code indicating the reason for the failure.
Simon Cooksey 0:fb7af294d5d9 1202 * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
Simon Cooksey 0:fb7af294d5d9 1203 * application registration.
Simon Cooksey 0:fb7af294d5d9 1204 *
Simon Cooksey 0:fb7af294d5d9 1205 * @deprecated You should use the parallel API from SecurityManager directly, refer to
Simon Cooksey 0:fb7af294d5d9 1206 * SecurityManager::purgeAllBondingState(). A former
Simon Cooksey 0:fb7af294d5d9 1207 * call to ble.purgeAllBondingState() should be replaced with
Simon Cooksey 0:fb7af294d5d9 1208 * ble.securityManager().purgeAllBondingState().
Simon Cooksey 0:fb7af294d5d9 1209 */
Simon Cooksey 0:fb7af294d5d9 1210 ble_error_t purgeAllBondingState(void) {
Simon Cooksey 0:fb7af294d5d9 1211 return securityManager().purgeAllBondingState();
Simon Cooksey 0:fb7af294d5d9 1212 }
Simon Cooksey 0:fb7af294d5d9 1213
Simon Cooksey 0:fb7af294d5d9 1214 /**
Simon Cooksey 0:fb7af294d5d9 1215 * Set up a callback for timeout events. Refer to Gap::TimeoutSource_t for
Simon Cooksey 0:fb7af294d5d9 1216 * possible event types.
Simon Cooksey 0:fb7af294d5d9 1217 *
Simon Cooksey 0:fb7af294d5d9 1218 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 1219 * Gap::onTimeout(). A former call
Simon Cooksey 0:fb7af294d5d9 1220 * to ble.onTimeout(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1221 * ble.gap().onTimeout(callback).
Simon Cooksey 0:fb7af294d5d9 1222 */
Simon Cooksey 0:fb7af294d5d9 1223 void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback) {
Simon Cooksey 0:fb7af294d5d9 1224 gap().onTimeout(timeoutCallback);
Simon Cooksey 0:fb7af294d5d9 1225 }
Simon Cooksey 0:fb7af294d5d9 1226
Simon Cooksey 0:fb7af294d5d9 1227 /**
Simon Cooksey 0:fb7af294d5d9 1228 * Set up a callback for connection events. Refer to Gap::ConnectionEventCallback_t.
Simon Cooksey 0:fb7af294d5d9 1229 *
Simon Cooksey 0:fb7af294d5d9 1230 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 1231 * Gap::onConnection(). A former call
Simon Cooksey 0:fb7af294d5d9 1232 * to ble.onConnection(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1233 * ble.gap().onConnection(callback).
Simon Cooksey 0:fb7af294d5d9 1234 */
Simon Cooksey 0:fb7af294d5d9 1235 void onConnection(Gap::ConnectionEventCallback_t connectionCallback) {
Simon Cooksey 0:fb7af294d5d9 1236 gap().onConnection(connectionCallback);
Simon Cooksey 0:fb7af294d5d9 1237 }
Simon Cooksey 0:fb7af294d5d9 1238
Simon Cooksey 0:fb7af294d5d9 1239 /**
Simon Cooksey 0:fb7af294d5d9 1240 * Append to a chain of callbacks to be invoked upon GAP disconnection.
Simon Cooksey 0:fb7af294d5d9 1241 *
Simon Cooksey 0:fb7af294d5d9 1242 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 1243 * Gap::onDisconnection(). A former call
Simon Cooksey 0:fb7af294d5d9 1244 * to ble.onDisconnection(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1245 * ble.gap().onDisconnection(callback).
Simon Cooksey 0:fb7af294d5d9 1246 */
Simon Cooksey 0:fb7af294d5d9 1247 void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback) {
Simon Cooksey 0:fb7af294d5d9 1248 gap().onDisconnection(disconnectionCallback);
Simon Cooksey 0:fb7af294d5d9 1249 }
Simon Cooksey 0:fb7af294d5d9 1250
Simon Cooksey 0:fb7af294d5d9 1251 /**
Simon Cooksey 0:fb7af294d5d9 1252 * The same as onDisconnection(), but allows an object reference and member function
Simon Cooksey 0:fb7af294d5d9 1253 * to be added to the chain of callbacks.
Simon Cooksey 0:fb7af294d5d9 1254 *
Simon Cooksey 0:fb7af294d5d9 1255 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 1256 * Gap::onDisconnection(). A former call
Simon Cooksey 0:fb7af294d5d9 1257 * to ble.onDisconnection(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1258 * ble.gap().onDisconnection(callback).
Simon Cooksey 0:fb7af294d5d9 1259 */
Simon Cooksey 0:fb7af294d5d9 1260 template<typename T>
Simon Cooksey 0:fb7af294d5d9 1261 void onDisconnection(T *tptr, void (T::*mptr)(const Gap::DisconnectionCallbackParams_t*)) {
Simon Cooksey 0:fb7af294d5d9 1262 gap().onDisconnection(tptr, mptr);
Simon Cooksey 0:fb7af294d5d9 1263 }
Simon Cooksey 0:fb7af294d5d9 1264
Simon Cooksey 0:fb7af294d5d9 1265 /**
Simon Cooksey 0:fb7af294d5d9 1266 * Radio Notification is a feature that enables ACTIVE and INACTIVE
Simon Cooksey 0:fb7af294d5d9 1267 * (nACTIVE) signals from the stack. These notify the application when the
Simon Cooksey 0:fb7af294d5d9 1268 * radio is in use. The signal is sent using software interrupt.
Simon Cooksey 0:fb7af294d5d9 1269 *
Simon Cooksey 0:fb7af294d5d9 1270 * The ACTIVE signal is sent before the radio event starts. The nACTIVE
Simon Cooksey 0:fb7af294d5d9 1271 * signal is sent at the end of the radio event. These signals can be used
Simon Cooksey 0:fb7af294d5d9 1272 * by the application programmer to synchronize application logic with radio
Simon Cooksey 0:fb7af294d5d9 1273 * activity. For example, the ACTIVE signal can be used to shut off external
Simon Cooksey 0:fb7af294d5d9 1274 * devices to manage peak current drawn during periods when the radio is on,
Simon Cooksey 0:fb7af294d5d9 1275 * or to trigger sensor data collection for transmission in the radio event.
Simon Cooksey 0:fb7af294d5d9 1276 *
Simon Cooksey 0:fb7af294d5d9 1277 * @param callback
Simon Cooksey 0:fb7af294d5d9 1278 * The application handler to be invoked in response to a radio
Simon Cooksey 0:fb7af294d5d9 1279 * ACTIVE/INACTIVE event.
Simon Cooksey 0:fb7af294d5d9 1280 *
Simon Cooksey 0:fb7af294d5d9 1281 * @deprecated You should use the parallel API from Gap directly, refer to
Simon Cooksey 0:fb7af294d5d9 1282 * Gap::onRadioNotification(). A former call
Simon Cooksey 0:fb7af294d5d9 1283 * to ble.onRadioNotification(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1284 * ble.gap().onRadioNotification(...).
Simon Cooksey 0:fb7af294d5d9 1285 */
Simon Cooksey 0:fb7af294d5d9 1286 void onRadioNotification(void (*callback)(bool)) {
Simon Cooksey 0:fb7af294d5d9 1287 gap().onRadioNotification(callback);
Simon Cooksey 0:fb7af294d5d9 1288 }
Simon Cooksey 0:fb7af294d5d9 1289
Simon Cooksey 0:fb7af294d5d9 1290 /**
Simon Cooksey 0:fb7af294d5d9 1291 * Add a callback for the GATT event DATA_SENT (which is triggered when
Simon Cooksey 0:fb7af294d5d9 1292 * updates are sent out by GATT in the form of notifications).
Simon Cooksey 0:fb7af294d5d9 1293 *
Simon Cooksey 0:fb7af294d5d9 1294 * @note It is possible to chain together multiple onDataSent callbacks
Simon Cooksey 0:fb7af294d5d9 1295 * (potentially from different modules of an application) to receive updates
Simon Cooksey 0:fb7af294d5d9 1296 * to characteristics.
Simon Cooksey 0:fb7af294d5d9 1297 *
Simon Cooksey 0:fb7af294d5d9 1298 * @note It is also possible to set up a callback into a member function of
Simon Cooksey 0:fb7af294d5d9 1299 * some object.
Simon Cooksey 0:fb7af294d5d9 1300 *
Simon Cooksey 0:fb7af294d5d9 1301 * @deprecated You should use the parallel API from GattServer directly, refer to
Simon Cooksey 0:fb7af294d5d9 1302 * GattServer::onDataSent(). A former call
Simon Cooksey 0:fb7af294d5d9 1303 * to ble.onDataSent(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1304 * ble.gattServer().onDataSent(...).
Simon Cooksey 0:fb7af294d5d9 1305 */
Simon Cooksey 0:fb7af294d5d9 1306 void onDataSent(void (*callback)(unsigned count)) {
Simon Cooksey 0:fb7af294d5d9 1307 gattServer().onDataSent(callback);
Simon Cooksey 0:fb7af294d5d9 1308 }
Simon Cooksey 0:fb7af294d5d9 1309
Simon Cooksey 0:fb7af294d5d9 1310 /**
Simon Cooksey 0:fb7af294d5d9 1311 * The same as onDataSent(), but allows an object reference and member function
Simon Cooksey 0:fb7af294d5d9 1312 * to be added to the chain of callbacks.
Simon Cooksey 0:fb7af294d5d9 1313 *
Simon Cooksey 0:fb7af294d5d9 1314 * @deprecated You should use the parallel API from GattServer directly, refer to
Simon Cooksey 0:fb7af294d5d9 1315 * GattServer::onDataSent(). A former call
Simon Cooksey 0:fb7af294d5d9 1316 * to ble.onDataSent(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1317 * ble.gattServer().onDataSent(...).
Simon Cooksey 0:fb7af294d5d9 1318 */
Simon Cooksey 0:fb7af294d5d9 1319 template <typename T> void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count)) {
Simon Cooksey 0:fb7af294d5d9 1320 gattServer().onDataSent(objPtr, memberPtr);
Simon Cooksey 0:fb7af294d5d9 1321 }
Simon Cooksey 0:fb7af294d5d9 1322
Simon Cooksey 0:fb7af294d5d9 1323 /**
Simon Cooksey 0:fb7af294d5d9 1324 * Set up a callback for when an attribute has its value updated by or at the
Simon Cooksey 0:fb7af294d5d9 1325 * connected peer. For a peripheral, this callback is triggered when the local
Simon Cooksey 0:fb7af294d5d9 1326 * GATT server has an attribute updated by a write command from the peer.
Simon Cooksey 0:fb7af294d5d9 1327 * For a Central, this callback is triggered when a response is received for
Simon Cooksey 0:fb7af294d5d9 1328 * a write request.
Simon Cooksey 0:fb7af294d5d9 1329 *
Simon Cooksey 0:fb7af294d5d9 1330 * @note It is possible to chain together multiple onDataWritten callbacks
Simon Cooksey 0:fb7af294d5d9 1331 * (potentially from different modules of an application) to receive updates
Simon Cooksey 0:fb7af294d5d9 1332 * to characteristics. Many services, such as DFU and UART, add their own
Simon Cooksey 0:fb7af294d5d9 1333 * onDataWritten callbacks behind the scenes to trap interesting events.
Simon Cooksey 0:fb7af294d5d9 1334 *
Simon Cooksey 0:fb7af294d5d9 1335 * @note It is also possible to set up a callback into a member function of
Simon Cooksey 0:fb7af294d5d9 1336 * some object.
Simon Cooksey 0:fb7af294d5d9 1337 *
Simon Cooksey 0:fb7af294d5d9 1338 * @deprecated You should use the parallel API from GattServer directly, refer to
Simon Cooksey 0:fb7af294d5d9 1339 * GattServer::onDataWritten(). A former call
Simon Cooksey 0:fb7af294d5d9 1340 * to ble.onDataWritten(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1341 * ble.gattServer().onDataWritten(...).
Simon Cooksey 0:fb7af294d5d9 1342 */
Simon Cooksey 0:fb7af294d5d9 1343 void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {
Simon Cooksey 0:fb7af294d5d9 1344 gattServer().onDataWritten(callback);
Simon Cooksey 0:fb7af294d5d9 1345 }
Simon Cooksey 0:fb7af294d5d9 1346
Simon Cooksey 0:fb7af294d5d9 1347 /**
Simon Cooksey 0:fb7af294d5d9 1348 * The same as onDataWritten(), but allows an object reference and member function
Simon Cooksey 0:fb7af294d5d9 1349 * to be added to the chain of callbacks.
Simon Cooksey 0:fb7af294d5d9 1350 *
Simon Cooksey 0:fb7af294d5d9 1351 * @deprecated You should use the parallel API from GattServer directly, refer to
Simon Cooksey 0:fb7af294d5d9 1352 * GattServer::onDataWritten(). A former call
Simon Cooksey 0:fb7af294d5d9 1353 * to ble.onDataWritten(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1354 * ble.gattServer().onDataWritten(...).
Simon Cooksey 0:fb7af294d5d9 1355 */
Simon Cooksey 0:fb7af294d5d9 1356 template <typename T> void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
Simon Cooksey 0:fb7af294d5d9 1357 gattServer().onDataWritten(objPtr, memberPtr);
Simon Cooksey 0:fb7af294d5d9 1358 }
Simon Cooksey 0:fb7af294d5d9 1359
Simon Cooksey 0:fb7af294d5d9 1360 /**
Simon Cooksey 0:fb7af294d5d9 1361 * Set up a callback to be invoked on the peripheral when an attribute is
Simon Cooksey 0:fb7af294d5d9 1362 * being read by a remote client.
Simon Cooksey 0:fb7af294d5d9 1363 *
Simon Cooksey 0:fb7af294d5d9 1364 * @note This functionality may not be available on all underlying stacks.
Simon Cooksey 0:fb7af294d5d9 1365 * You could use GattCharacteristic::setReadAuthorizationCallback() as an
Simon Cooksey 0:fb7af294d5d9 1366 * alternative.
Simon Cooksey 0:fb7af294d5d9 1367 *
Simon Cooksey 0:fb7af294d5d9 1368 * @note It is possible to chain together multiple onDataRead callbacks
Simon Cooksey 0:fb7af294d5d9 1369 * (potentially from different modules of an application) to receive updates
Simon Cooksey 0:fb7af294d5d9 1370 * to characteristics. Services may add their own onDataRead callbacks
Simon Cooksey 0:fb7af294d5d9 1371 * behind the scenes to trap interesting events.
Simon Cooksey 0:fb7af294d5d9 1372 *
Simon Cooksey 0:fb7af294d5d9 1373 * @note It is also possible to set up a callback into a member function of
Simon Cooksey 0:fb7af294d5d9 1374 * some object.
Simon Cooksey 0:fb7af294d5d9 1375 *
Simon Cooksey 0:fb7af294d5d9 1376 * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
Simon Cooksey 0:fb7af294d5d9 1377 * else BLE_ERROR_NONE.
Simon Cooksey 0:fb7af294d5d9 1378 *
Simon Cooksey 0:fb7af294d5d9 1379 * @deprecated You should use the parallel API from GattServer directly, refer to
Simon Cooksey 0:fb7af294d5d9 1380 * GattServer::onDataRead(). A former call
Simon Cooksey 0:fb7af294d5d9 1381 * to ble.onDataRead(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1382 * ble.gattServer().onDataRead(...).
Simon Cooksey 0:fb7af294d5d9 1383 */
Simon Cooksey 0:fb7af294d5d9 1384 ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
Simon Cooksey 0:fb7af294d5d9 1385 return gattServer().onDataRead(callback);
Simon Cooksey 0:fb7af294d5d9 1386 }
Simon Cooksey 0:fb7af294d5d9 1387
Simon Cooksey 0:fb7af294d5d9 1388 /**
Simon Cooksey 0:fb7af294d5d9 1389 * The same as onDataRead(), but allows an object reference and member function
Simon Cooksey 0:fb7af294d5d9 1390 * to be added to the chain of callbacks.
Simon Cooksey 0:fb7af294d5d9 1391 *
Simon Cooksey 0:fb7af294d5d9 1392 * @deprecated You should use the parallel API from GattServer directly, refer to
Simon Cooksey 0:fb7af294d5d9 1393 * GattServer::onDataRead(). A former call
Simon Cooksey 0:fb7af294d5d9 1394 * to ble.onDataRead(...) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1395 * ble.gattServer().onDataRead(...).
Simon Cooksey 0:fb7af294d5d9 1396 */
Simon Cooksey 0:fb7af294d5d9 1397 template <typename T> ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
Simon Cooksey 0:fb7af294d5d9 1398 return gattServer().onDataRead(objPtr, memberPtr);
Simon Cooksey 0:fb7af294d5d9 1399 }
Simon Cooksey 0:fb7af294d5d9 1400
Simon Cooksey 0:fb7af294d5d9 1401 /**
Simon Cooksey 0:fb7af294d5d9 1402 * Set up a callback for when notifications or indications are enabled for a
Simon Cooksey 0:fb7af294d5d9 1403 * characteristic on the local GattServer.
Simon Cooksey 0:fb7af294d5d9 1404 *
Simon Cooksey 0:fb7af294d5d9 1405 * @deprecated You should use the parallel API from GattServer directly, refer to
Simon Cooksey 0:fb7af294d5d9 1406 * GattServer::onUpdatesEnabled(). A former call
Simon Cooksey 0:fb7af294d5d9 1407 * to ble.onUpdatesEnabled(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1408 * ble.gattServer().onUpdatesEnabled(callback).
Simon Cooksey 0:fb7af294d5d9 1409 */
Simon Cooksey 0:fb7af294d5d9 1410 void onUpdatesEnabled(GattServer::EventCallback_t callback) {
Simon Cooksey 0:fb7af294d5d9 1411 gattServer().onUpdatesEnabled(callback);
Simon Cooksey 0:fb7af294d5d9 1412 }
Simon Cooksey 0:fb7af294d5d9 1413
Simon Cooksey 0:fb7af294d5d9 1414 /**
Simon Cooksey 0:fb7af294d5d9 1415 * Set up a callback for when notifications or indications are disabled for a
Simon Cooksey 0:fb7af294d5d9 1416 * characteristic on the local GattServer.
Simon Cooksey 0:fb7af294d5d9 1417 *
Simon Cooksey 0:fb7af294d5d9 1418 * @deprecated You should use the parallel API from GattServer directly, refer to
Simon Cooksey 0:fb7af294d5d9 1419 * GattServer::onUpdatesDisabled(). A former call
Simon Cooksey 0:fb7af294d5d9 1420 * to ble.onUpdatesEnabled(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1421 * ble.gattServer().onUpdatesEnabled(callback).
Simon Cooksey 0:fb7af294d5d9 1422 */
Simon Cooksey 0:fb7af294d5d9 1423 void onUpdatesDisabled(GattServer::EventCallback_t callback) {
Simon Cooksey 0:fb7af294d5d9 1424 gattServer().onUpdatesDisabled(callback);
Simon Cooksey 0:fb7af294d5d9 1425 }
Simon Cooksey 0:fb7af294d5d9 1426
Simon Cooksey 0:fb7af294d5d9 1427 /**
Simon Cooksey 0:fb7af294d5d9 1428 * Set up a callback for when the GATT server receives a response for an
Simon Cooksey 0:fb7af294d5d9 1429 * indication event sent previously.
Simon Cooksey 0:fb7af294d5d9 1430 *
Simon Cooksey 0:fb7af294d5d9 1431 * @deprecated You should use the parallel API from GattServer directly, refer to
Simon Cooksey 0:fb7af294d5d9 1432 * GattServer::onConfirmationReceived(). A former call
Simon Cooksey 0:fb7af294d5d9 1433 * to ble.onConfirmationReceived(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1434 * ble.gattServer().onConfirmationReceived(callback).
Simon Cooksey 0:fb7af294d5d9 1435 */
Simon Cooksey 0:fb7af294d5d9 1436 void onConfirmationReceived(GattServer::EventCallback_t callback) {
Simon Cooksey 0:fb7af294d5d9 1437 gattServer().onConfirmationReceived(callback);
Simon Cooksey 0:fb7af294d5d9 1438 }
Simon Cooksey 0:fb7af294d5d9 1439
Simon Cooksey 0:fb7af294d5d9 1440 /**
Simon Cooksey 0:fb7af294d5d9 1441 * Set up a callback for when the security setup procedure (key generation
Simon Cooksey 0:fb7af294d5d9 1442 * and exchange) for a link has started. This will be skipped for bonded
Simon Cooksey 0:fb7af294d5d9 1443 * devices. The callback is passed in parameters received from the peer's
Simon Cooksey 0:fb7af294d5d9 1444 * security request: bool allowBonding, bool requireMITM, and
Simon Cooksey 0:fb7af294d5d9 1445 * SecurityIOCapabilities_t.
Simon Cooksey 0:fb7af294d5d9 1446 *
Simon Cooksey 0:fb7af294d5d9 1447 * @deprecated You should use the parallel API from SecurityManager directly, refer to
Simon Cooksey 0:fb7af294d5d9 1448 * SecurityManager::onSecuritySetupInitiated(). A former
Simon Cooksey 0:fb7af294d5d9 1449 * call to ble.onSecuritySetupInitiated(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1450 * ble.securityManager().onSecuritySetupInitiated(callback).
Simon Cooksey 0:fb7af294d5d9 1451 */
Simon Cooksey 0:fb7af294d5d9 1452 void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) {
Simon Cooksey 0:fb7af294d5d9 1453 securityManager().onSecuritySetupInitiated(callback);
Simon Cooksey 0:fb7af294d5d9 1454 }
Simon Cooksey 0:fb7af294d5d9 1455
Simon Cooksey 0:fb7af294d5d9 1456 /**
Simon Cooksey 0:fb7af294d5d9 1457 * Set up a callback for when the security setup procedure (key generation
Simon Cooksey 0:fb7af294d5d9 1458 * and exchange) for a link has completed. This will be skipped for bonded
Simon Cooksey 0:fb7af294d5d9 1459 * devices. The callback is passed in the success/failure status of the
Simon Cooksey 0:fb7af294d5d9 1460 * security setup procedure.
Simon Cooksey 0:fb7af294d5d9 1461 *
Simon Cooksey 0:fb7af294d5d9 1462 * @deprecated You should use the parallel API from SecurityManager directly, refer to
Simon Cooksey 0:fb7af294d5d9 1463 * SecurityManager::onSecuritySetupCompleted(). A former
Simon Cooksey 0:fb7af294d5d9 1464 * call to ble.onSecuritySetupCompleted(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1465 * ble.securityManager().onSecuritySetupCompleted(callback).
Simon Cooksey 0:fb7af294d5d9 1466 */
Simon Cooksey 0:fb7af294d5d9 1467 void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) {
Simon Cooksey 0:fb7af294d5d9 1468 securityManager().onSecuritySetupCompleted(callback);
Simon Cooksey 0:fb7af294d5d9 1469 }
Simon Cooksey 0:fb7af294d5d9 1470
Simon Cooksey 0:fb7af294d5d9 1471 /**
Simon Cooksey 0:fb7af294d5d9 1472 * Set up a callback for when a link with the peer is secured. For bonded
Simon Cooksey 0:fb7af294d5d9 1473 * devices, subsequent reconnections with a bonded peer will result only in
Simon Cooksey 0:fb7af294d5d9 1474 * this callback when the link is secured, and setup procedures will not
Simon Cooksey 0:fb7af294d5d9 1475 * occur unless the bonding information is either lost or deleted on either
Simon Cooksey 0:fb7af294d5d9 1476 * or both sides. The callback is passed in a SecurityManager::SecurityMode_t according
Simon Cooksey 0:fb7af294d5d9 1477 * to the level of security in effect for the secured link.
Simon Cooksey 0:fb7af294d5d9 1478 *
Simon Cooksey 0:fb7af294d5d9 1479 * @deprecated You should use the parallel API from SecurityManager directly, refer to
Simon Cooksey 0:fb7af294d5d9 1480 * SecurityManager::onLinkSecured(). A former
Simon Cooksey 0:fb7af294d5d9 1481 * call to ble.onLinkSecured(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1482 * ble.securityManager().onLinkSecured(callback).
Simon Cooksey 0:fb7af294d5d9 1483 */
Simon Cooksey 0:fb7af294d5d9 1484 void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) {
Simon Cooksey 0:fb7af294d5d9 1485 securityManager().onLinkSecured(callback);
Simon Cooksey 0:fb7af294d5d9 1486 }
Simon Cooksey 0:fb7af294d5d9 1487
Simon Cooksey 0:fb7af294d5d9 1488 /**
Simon Cooksey 0:fb7af294d5d9 1489 * Set up a callback for successful bonding, meaning that link-specific security
Simon Cooksey 0:fb7af294d5d9 1490 * context is stored persistently for a peer device.
Simon Cooksey 0:fb7af294d5d9 1491 *
Simon Cooksey 0:fb7af294d5d9 1492 * @deprecated You should use the parallel API from SecurityManager directly, refer to
Simon Cooksey 0:fb7af294d5d9 1493 * SecurityManager::onSecurityContextStored(). A former
Simon Cooksey 0:fb7af294d5d9 1494 * call to ble.onSecurityContextStored(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1495 * ble.securityManager().onSecurityContextStored(callback).
Simon Cooksey 0:fb7af294d5d9 1496 */
Simon Cooksey 0:fb7af294d5d9 1497 void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) {
Simon Cooksey 0:fb7af294d5d9 1498 securityManager().onSecurityContextStored(callback);
Simon Cooksey 0:fb7af294d5d9 1499 }
Simon Cooksey 0:fb7af294d5d9 1500
Simon Cooksey 0:fb7af294d5d9 1501 /**
Simon Cooksey 0:fb7af294d5d9 1502 * Set up a callback for when the passkey needs to be displayed on a
Simon Cooksey 0:fb7af294d5d9 1503 * peripheral with DISPLAY capability. This happens when security is
Simon Cooksey 0:fb7af294d5d9 1504 * configured to prevent Man-In-The-Middle attacks, and the peers need to exchange
Simon Cooksey 0:fb7af294d5d9 1505 * a passkey (or PIN) to authenticate the connection
Simon Cooksey 0:fb7af294d5d9 1506 * attempt.
Simon Cooksey 0:fb7af294d5d9 1507 *
Simon Cooksey 0:fb7af294d5d9 1508 * @deprecated You should use the parallel API from SecurityManager directly, refer to
Simon Cooksey 0:fb7af294d5d9 1509 * SecurityManager::onPasskeyDisplay(). A former
Simon Cooksey 0:fb7af294d5d9 1510 * call to ble.onPasskeyDisplay(callback) should be replaced with
Simon Cooksey 0:fb7af294d5d9 1511 * ble.securityManager().onPasskeyDisplay(callback).
Simon Cooksey 0:fb7af294d5d9 1512 */
Simon Cooksey 0:fb7af294d5d9 1513 void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) {
Simon Cooksey 0:fb7af294d5d9 1514 return securityManager().onPasskeyDisplay(callback);
Simon Cooksey 0:fb7af294d5d9 1515 }
Simon Cooksey 0:fb7af294d5d9 1516
Simon Cooksey 0:fb7af294d5d9 1517 /**
Simon Cooksey 0:fb7af294d5d9 1518 * Process ALL pending events living in the BLE stack .
Simon Cooksey 0:fb7af294d5d9 1519 * Return once all events have been consumed.
Simon Cooksey 0:fb7af294d5d9 1520 * This function is called by user in their while loop (mbed Classic)
Simon Cooksey 0:fb7af294d5d9 1521 * or automatically by Minar (mbed OS) when BLE event processing is scheduled.
Simon Cooksey 0:fb7af294d5d9 1522 * Internally, this function will call BLEInstanceBase::processEvent.
Simon Cooksey 0:fb7af294d5d9 1523 */
Simon Cooksey 0:fb7af294d5d9 1524 void processEvents();
Simon Cooksey 0:fb7af294d5d9 1525
Simon Cooksey 0:fb7af294d5d9 1526 /**
Simon Cooksey 0:fb7af294d5d9 1527 * Register a hook which will be called every time the BLE stack has pending
Simon Cooksey 0:fb7af294d5d9 1528 * work.
Simon Cooksey 0:fb7af294d5d9 1529 * By registering a callback, user code can know when event processing has to be
Simon Cooksey 0:fb7af294d5d9 1530 * scheduled.
Simon Cooksey 0:fb7af294d5d9 1531 * Callback format is void (*)(BLE& ble);
Simon Cooksey 0:fb7af294d5d9 1532 */
Simon Cooksey 0:fb7af294d5d9 1533 void onEventsToProcess(const OnEventsToProcessCallback_t& callback);
Simon Cooksey 0:fb7af294d5d9 1534
Simon Cooksey 0:fb7af294d5d9 1535 private:
Simon Cooksey 0:fb7af294d5d9 1536
Simon Cooksey 0:fb7af294d5d9 1537 friend class BLEInstanceBase;
Simon Cooksey 0:fb7af294d5d9 1538
Simon Cooksey 0:fb7af294d5d9 1539 /**
Simon Cooksey 0:fb7af294d5d9 1540 * This function allow the BLE stack to signal that their is work to do and
Simon Cooksey 0:fb7af294d5d9 1541 * event processing should be done (BLE::processEvent()).
Simon Cooksey 0:fb7af294d5d9 1542 * This function should be called by the port of BLE_API, it shouldn't be
Simon Cooksey 0:fb7af294d5d9 1543 * accessible to end users.
Simon Cooksey 0:fb7af294d5d9 1544 */
Simon Cooksey 0:fb7af294d5d9 1545 void signalEventsToProcess();
Simon Cooksey 0:fb7af294d5d9 1546
Simon Cooksey 0:fb7af294d5d9 1547 /**
Simon Cooksey 0:fb7af294d5d9 1548 * Implementation of init() [internal to BLE_API].
Simon Cooksey 0:fb7af294d5d9 1549 *
Simon Cooksey 0:fb7af294d5d9 1550 * The implementation is separated into a private method because it isn't
Simon Cooksey 0:fb7af294d5d9 1551 * suitable to be included in the header.
Simon Cooksey 0:fb7af294d5d9 1552 */
Simon Cooksey 0:fb7af294d5d9 1553 ble_error_t initImplementation(FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback);
Simon Cooksey 0:fb7af294d5d9 1554
Simon Cooksey 0:fb7af294d5d9 1555 private:
Simon Cooksey 0:fb7af294d5d9 1556 BLE(const BLE&);
Simon Cooksey 0:fb7af294d5d9 1557 BLE &operator=(const BLE &);
Simon Cooksey 0:fb7af294d5d9 1558
Simon Cooksey 0:fb7af294d5d9 1559 private:
Simon Cooksey 0:fb7af294d5d9 1560 InstanceID_t instanceID;
Simon Cooksey 0:fb7af294d5d9 1561 BLEInstanceBase *transport; /* The device-specific backend */
Simon Cooksey 0:fb7af294d5d9 1562 OnEventsToProcessCallback_t whenEventsToProcess;
Simon Cooksey 0:fb7af294d5d9 1563 };
Simon Cooksey 0:fb7af294d5d9 1564
Simon Cooksey 0:fb7af294d5d9 1565 typedef BLE BLEDevice; /**< @deprecated This type alias is retained for the
Simon Cooksey 0:fb7af294d5d9 1566 * sake of compatibility with older
Simon Cooksey 0:fb7af294d5d9 1567 * code. Will be dropped at some point soon.*/
Simon Cooksey 0:fb7af294d5d9 1568
Simon Cooksey 0:fb7af294d5d9 1569 #endif /* ifndef __BLE_H__ */