Jörg Küfen / BLE_API

fka mod

Fork of BLE_API by Bluetooth Low Energy

ble/BLE.h@1205:b717ee89504d, 2016-09-14 (annotated)

Committer:
Vincent Coubard
Date:
Wed Sep 14 14:17:57 2016 +0100
Branch:
6a3b7c7dc9acadc400d8e4ab635a009eac25f2aa
Revision:
1205:b717ee89504d
Parent:
1202:d5426bb4b03f 
Sync with 6a3b7c7dc9acadc400d8e4ab635a009eac25f2aa



2016-08-31 10:11:40+01:00: Vincent Coubard

Update documentation.

Who changed what in which revision?

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