Alex Cordonnier / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Fork of BLE_API by Bluetooth Low Energy

ble/BLE.h@1201:9b71aac42d14, 2016-09-14 (annotated)

Committer:
Vincent Coubard
Date:
Wed Sep 14 14:17:52 2016 +0100
Branch:
2f55eed1fdde06fdabfb66d41ce6cd14e280978f
Revision:
1201:9b71aac42d14
Parent:
1183:1589830dbdb7
Child:
1202:d5426bb4b03f
Sync with 2f55eed1fdde06fdabfb66d41ce6cd14e280978f



2016-06-06 09:36:57+01:00: Vincent Coubard

Add an interface which allows user code to customise the way BLE events

are processed.



The mechanism is quite simple:

  * user code can process all events pending in the internal BLE stack by

    calling the function BLE::processEvent.

  * user code can be notified when an event become available and the event

    stack has to be processed. The notification is issued by the port of

    mbed BLE.

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 1201:9b71aac42d14 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__ */