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