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