/
BLE_API
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: Peripheral_1_serial_copy Peripheral_1_serial 151006_1st_Scenario_normal
Fork of
BLE_API
by 
Bluetooth Low Energy
Embed:
(wiki syntax)
Show/hide line numbers
BLE.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2006-2013 ARM Limited 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef __BLE_H__ 00018 #define __BLE_H__ 00019 00020 #include "blecommon.h" 00021 #include "Gap.h" 00022 #include "GattServer.h" 00023 #include "GattClient.h" 00024 #include "BLEInstanceBase.h" 00025 00026 #include "mbed_error.h" 00027 00028 /** 00029 * The base class used to abstract away BLE capable radio transceivers or SOCs, 00030 * to enable this BLE API to work with any radio transparently. 00031 */ 00032 class BLE 00033 { 00034 public: 00035 /** 00036 * Initialize the BLE controller. This should be called before using 00037 * anything else in the BLE_API. 00038 * 00039 * init() hands control to the underlying BLE module to accomplish 00040 * initialization. This initialization may tacitly depend on other hardware 00041 * setup (such as clocks or power-modes) which happens early on during 00042 * system startup. It may not be safe to call init() from global static 00043 * context where ordering is compiler specific and can't be guaranteed--it 00044 * is safe to call BLE::init() from within main(). 00045 */ 00046 ble_error_t init(); 00047 00048 /** 00049 * Purge the BLE stack of GATT and GAP state. init() must be called 00050 * afterwards to re-instate services and GAP state. This API offers a way to 00051 * repopulate the GATT database with new services and characteristics. 00052 */ 00053 ble_error_t shutdown(void) { 00054 clearAdvertisingPayload(); 00055 if (!transport) { 00056 error("bad handle to underlying transport"); 00057 } 00058 return transport->shutdown(); 00059 } 00060 00061 /** 00062 * This call allows the application to get the BLE stack version information. 00063 * 00064 * @return A pointer to a const string representing the version. 00065 * Note: The string is owned by the BLE_API. 00066 */ 00067 const char *getVersion(void) { 00068 if (!transport) { 00069 error("bad handle to underlying transport"); 00070 } 00071 return transport->getVersion(); 00072 } 00073 00074 /* 00075 * Accessors to GAP. Please refer to Gap.h. All GAP related functionality requires 00076 * going through this accessor. 00077 */ 00078 const Gap &gap() const { 00079 if (!transport) { 00080 error("bad handle to underlying transport"); 00081 } 00082 return transport->getGap(); 00083 } 00084 Gap &gap() { 00085 if (!transport) { 00086 error("bad handle to underlying transport"); 00087 } 00088 return transport->getGap(); 00089 } 00090 00091 /* 00092 * Accessors to GATT Server. Please refer to GattServer.h. All GATTServer related 00093 * functionality requires going through this accessor. 00094 */ 00095 const GattServer& gattServer() const { 00096 if (!transport) { 00097 error("bad handle to underlying transport"); 00098 } 00099 return transport->getGattServer(); 00100 } 00101 GattServer& gattServer() { 00102 if (!transport) { 00103 error("bad handle to underlying transport"); 00104 } 00105 return transport->getGattServer(); 00106 } 00107 00108 /* 00109 * Accessors to GATT Client. Please refer to GattClient.h. All GATTClient related 00110 * functionality requires going through this accessor. 00111 */ 00112 const GattClient& gattClient() const { 00113 if (!transport) { 00114 error("bad handle to underlying transport"); 00115 } 00116 return transport->getGattClient(); 00117 } 00118 GattClient& gattClient() { 00119 if (!transport) { 00120 error("bad handle to underlying transport"); 00121 } 00122 return transport->getGattClient(); 00123 } 00124 00125 /* 00126 * Accessors to Security Manager. Please refer to SecurityManager.h. All 00127 * SecurityManager related functionality requires going through this 00128 * accessor. 00129 */ 00130 const SecurityManager& securityManager() const { 00131 if (!transport) { 00132 error("bad handle to underlying transport"); 00133 } 00134 return transport->getSecurityManager(); 00135 } 00136 SecurityManager& securityManager() { 00137 if (!transport) { 00138 error("bad handle to underlying transport"); 00139 } 00140 return transport->getSecurityManager(); 00141 } 00142 00143 /** 00144 * Yield control to the BLE stack or to other tasks waiting for events. This 00145 * is a sleep function which will return when there is an application 00146 * specific interrupt, but the MCU might wake up several times before 00147 * returning (to service the stack). This is not always interchangeable with 00148 * WFE(). 00149 */ 00150 void waitForEvent(void) { 00151 if (!transport) { 00152 error("bad handle to underlying transport"); 00153 } 00154 transport->waitForEvent(); 00155 } 00156 00157 public: 00158 typedef unsigned InstanceID_t; 00159 static const InstanceID_t DEFAULT_INSTANCE = 0; 00160 #ifndef YOTTA_CFG_BLE_INSTANCES_COUNT 00161 static const InstanceID_t NUM_INSTANCES = 1; 00162 #else 00163 static const InstanceID_t NUM_INSTANCES = YOTTA_CFG_BLE_INSTANCES_COUNT; 00164 #endif 00165 00166 /** 00167 * Get a reference to the BLE singleton corresponding to a given interface. 00168 * There is a static array of BLE singletons. 00169 * 00170 * @Note: Calling Instance() is preferred over constructing a BLE object 00171 * directly, as it returns references to singletons. 00172 * 00173 * @param[in] id 00174 * Instance-ID. This should be less than NUM_INSTANCES in order 00175 * for the returned BLE singleton to be useful. 00176 * 00177 * @return a reference to a single object 00178 */ 00179 static BLE &Instance(InstanceID_t id = DEFAULT_INSTANCE); 00180 00181 /** 00182 * Constructor for a handle to a BLE instance (i.e. BLE stack). BLE handles 00183 * are thin wrappers around a transport object (i.e. ptr. to 00184 * BLEInstanceBase). 00185 * 00186 * BLE objects are are better created as singletons accessed through the 00187 * Instance() method. If multiple BLE handles are constructed for the same 00188 * interface (using this constructor), they will share the same underlying 00189 * transport object. 00190 */ 00191 BLE(InstanceID_t instanceID = DEFAULT_INSTANCE); 00192 00193 00194 /* 00195 * Deprecation alert! 00196 * All of the following are deprecated and may be dropped in a future 00197 * release. Documentation should refer to alternative APIs. 00198 */ 00199 00200 /* GAP specific APIs. */ 00201 public: 00202 /** 00203 * Set the BTLE MAC address and type. 00204 * @return BLE_ERROR_NONE on success. 00205 * 00206 * @note: This API is now *deprecated* and will be dropped in the future. 00207 * You should use the parallel API from Gap directly. A former call to 00208 * ble.setAddress(...) should be replaced with 00209 * ble.gap().setAddress(...). 00210 */ 00211 ble_error_t setAddress(Gap::AddressType_t type, const Gap::Address_t address) { 00212 return gap().setAddress(type, address); 00213 } 00214 00215 /** 00216 * Fetch the BTLE MAC address and type. 00217 * @return BLE_ERROR_NONE on success. 00218 * 00219 * @note: This API is now *deprecated* and will be dropped in the future. 00220 * You should use the parallel API from Gap directly. A former call to 00221 * ble.getAddress(...) should be replaced with 00222 * ble.gap().getAddress(...). 00223 */ 00224 ble_error_t getAddress(Gap::AddressType_t *typeP, Gap::Address_t address) { 00225 return gap().getAddress(typeP, address); 00226 } 00227 00228 /** 00229 * Set the GAP advertising mode to use for this device. 00230 * 00231 * @note: This API is now *deprecated* and will be dropped in the future. 00232 * You should use the parallel API from Gap directly. A former call to 00233 * ble.setAdvertisingType(...) should be replaced with 00234 * ble.gap().setAdvertisingType(...). 00235 */ 00236 void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) { 00237 gap().setAdvertisingType(advType); 00238 } 00239 00240 /** 00241 * @param[in] interval 00242 * Advertising interval in units of milliseconds. Advertising 00243 * is disabled if interval is 0. If interval is smaller than 00244 * the minimum supported value, then the minimum supported 00245 * value is used instead. This minimum value can be discovered 00246 * using getMinAdvertisingInterval(). 00247 * 00248 * This field must be set to 0 if connectionMode is equal 00249 * to ADV_CONNECTABLE_DIRECTED. 00250 * 00251 * @note: Decreasing this value will allow central devices to detect a 00252 * peripheral faster at the expense of more power being used by the radio 00253 * due to the higher data transmit rate. 00254 * 00255 * @note: This API is now *deprecated* and will be dropped in the future. 00256 * You should use the parallel API from Gap directly. A former call to 00257 * ble.setAdvertisingInterval(...) should be replaced with 00258 * ble.gap().setAdvertisingInterval(...). 00259 * 00260 * @note: [WARNING] This API previously used 0.625ms as the unit for its 00261 * 'interval' argument. That required an explicit conversion from 00262 * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is 00263 * no longer required as the new units are milliseconds. Any application 00264 * code depending on the old semantics would need to be updated accordingly. 00265 */ 00266 void setAdvertisingInterval (uint16_t interval) { 00267 gap().setAdvertisingInterval(interval); 00268 } 00269 00270 /** 00271 * @return Minimum Advertising interval in milliseconds. 00272 * 00273 * @note: This API is now *deprecated* and will be dropped in the future. 00274 * You should use the parallel API from Gap directly. A former call to 00275 * ble.getMinAdvertisingInterval(...) should be replaced with 00276 * ble.gap().getMinAdvertisingInterval(...). 00277 */ 00278 uint16_t getMinAdvertisingInterval (void) const { 00279 return gap().getMinAdvertisingInterval(); 00280 } 00281 00282 /** 00283 * @return Minimum Advertising interval in milliseconds for non-connectible mode. 00284 * 00285 * @note: This API is now *deprecated* and will be dropped in the future. 00286 * You should use the parallel API from Gap directly. A former call to 00287 * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with 00288 * ble.gap().getMinNonConnectableAdvertisingInterval(...). 00289 */ 00290 uint16_t getMinNonConnectableAdvertisingInterval (void) const { 00291 return gap().getMinNonConnectableAdvertisingInterval(); 00292 } 00293 00294 /** 00295 * @return Maximum Advertising interval in milliseconds. 00296 * 00297 * @note: This API is now *deprecated* and will be dropped in the future. 00298 * You should use the parallel API from Gap directly. A former call to 00299 * ble.getMaxAdvertisingInterval(...) should be replaced with 00300 * ble.gap().getMaxAdvertisingInterval(...). 00301 */ 00302 uint16_t getMaxAdvertisingInterval (void) const { 00303 return gap().getMaxAdvertisingInterval(); 00304 } 00305 00306 /** 00307 * @param[in] timeout 00308 * Advertising timeout (in seconds) between 0x1 and 0x3FFF (1 00309 * and 16383). Use 0 to disable the advertising timeout. 00310 * 00311 * @note: This API is now *deprecated* and will be dropped in the future. 00312 * You should use the parallel API from Gap directly. A former call to 00313 * ble.setAdvertisingTimeout(...) should be replaced with 00314 * ble.gap().setAdvertisingTimeout(...). 00315 */ 00316 void setAdvertisingTimeout (uint16_t timeout) { 00317 gap().setAdvertisingTimeout(timeout); 00318 } 00319 00320 /** 00321 * Setup a particular, user-constructed set of advertisement parameters for 00322 * the underlying stack. It would be uncommon for this API to be used 00323 * directly; there are other APIs to tweak advertisement parameters 00324 * individually (see above). 00325 * 00326 * @note: This API is now *deprecated* and will be dropped in the future. 00327 * You should use the parallel API from Gap directly. A former call to 00328 * ble.setAdvertisingParams(...) should be replaced with 00329 * ble.gap().setAdvertisingParams(...). 00330 */ 00331 void setAdvertisingParams(const GapAdvertisingParams &advParams) { 00332 gap().setAdvertisingParams(advParams); 00333 } 00334 00335 /** 00336 * @return Read back advertising parameters. Useful for storing and 00337 * restoring parameters rapidly. 00338 * 00339 * @note: This API is now *deprecated* and will be dropped in the future. 00340 * You should use the parallel API from Gap directly. A former call to 00341 * ble.getAdvertisingParams(...) should be replaced with 00342 * ble.gap().getAdvertisingParams(...). 00343 */ 00344 const GapAdvertisingParams &getAdvertisingParams (void) const { 00345 return gap().getAdvertisingParams(); 00346 } 00347 00348 /** 00349 * Accumulate an AD structure in the advertising payload. Please note that 00350 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used 00351 * as an additional 31 bytes if the advertising payload proves to be too 00352 * small. 00353 * 00354 * @param[in] flags 00355 * The flags to be added. Please refer to 00356 * GapAdvertisingData::Flags for valid flags. Multiple 00357 * flags may be specified in combination. 00358 * 00359 * @note: This API is now *deprecated* and will be dropped in the future. 00360 * You should use the parallel API from Gap directly. A former call to 00361 * ble.accumulateAdvertisingPayload(flags) should be replaced with 00362 * ble.gap().accumulateAdvertisingPayload(flags). 00363 */ 00364 ble_error_t accumulateAdvertisingPayload(uint8_t flags) { 00365 return gap().accumulateAdvertisingPayload(flags); 00366 } 00367 00368 /** 00369 * Accumulate an AD structure in the advertising payload. Please note that 00370 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used 00371 * as an additional 31 bytes if the advertising payload proves to be too 00372 * small. 00373 * 00374 * @param[in] app 00375 * The appearance of the peripheral. 00376 * 00377 * @note: This API is now *deprecated* and will be dropped in the future. 00378 * You should use the parallel API from Gap directly. A former call to 00379 * ble.accumulateAdvertisingPayload(appearance) should be replaced with 00380 * ble.gap().accumulateAdvertisingPayload(appearance). 00381 */ 00382 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) { 00383 return gap().accumulateAdvertisingPayload(app); 00384 } 00385 00386 /** 00387 * Accumulate an AD structure in the advertising payload. Please note that 00388 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used 00389 * as an additional 31 bytes if the advertising payload proves to be too 00390 * small. 00391 * 00392 * @param[in] app 00393 * The max transmit power to be used by the controller. This 00394 * is only a hint. 00395 * 00396 * @note: This API is now *deprecated* and will be dropped in the future. 00397 * You should use the parallel API from Gap directly. A former call to 00398 * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with 00399 * ble.gap().accumulateAdvertisingPayloadTxPower(txPower). 00400 */ 00401 ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) { 00402 return gap().accumulateAdvertisingPayloadTxPower(power); 00403 } 00404 00405 /** 00406 * Accumulate a variable length byte-stream as an AD structure in the 00407 * advertising payload. Please note that the payload is limited to 31 bytes. 00408 * The SCAN_RESPONSE message may be used as an additional 31 bytes if the 00409 * advertising payload proves to be too small. 00410 * 00411 * @param type The type which describes the variable length data. 00412 * @param data data bytes. 00413 * @param len length of data. 00414 * 00415 * @note: This API is now *deprecated* and will be dropped in the future. 00416 * You should use the parallel API from Gap directly. A former call to 00417 * ble.accumulateAdvertisingPayload(...) should be replaced with 00418 * ble.gap().accumulateAdvertisingPayload(...). 00419 */ 00420 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) { 00421 return gap().accumulateAdvertisingPayload(type, data, len); 00422 } 00423 00424 /** 00425 * Setup a particular, user-constructed advertisement payload for the 00426 * underlying stack. It would be uncommon for this API to be used directly; 00427 * there are other APIs to build an advertisement payload (see above). 00428 * 00429 * @note: This API is now *deprecated* and will be dropped in the future. 00430 * You should use the parallel API from Gap directly. A former call to 00431 * ble.setAdvertisingData(...) should be replaced with 00432 * ble.gap().setAdvertisingPayload(...). 00433 */ 00434 ble_error_t setAdvertisingData(const GapAdvertisingData &advData) { 00435 return gap().setAdvertisingPayload(advData); 00436 } 00437 00438 /** 00439 * @return Read back advertising data. Useful for storing and 00440 * restoring payload. 00441 * 00442 * @note: This API is now *deprecated* and will be dropped in the future. 00443 * You should use the parallel API from Gap directly. A former call to 00444 * ble.getAdvertisingData(...) should be replaced with 00445 * ble.gap().getAdvertisingPayload()(...). 00446 */ 00447 const GapAdvertisingData &getAdvertisingData (void) const { 00448 return gap().getAdvertisingPayload(); 00449 } 00450 00451 /** 00452 * Reset any advertising payload prepared from prior calls to 00453 * accumulateAdvertisingPayload(). This automatically propagates the re- 00454 * initialized adv payload to the underlying stack. 00455 * 00456 * @note: This API is now *deprecated* and will be dropped in the future. 00457 * You should use the parallel API from Gap directly. A former call to 00458 * ble.clearAdvertisingPayload(...) should be replaced with 00459 * ble.gap().clearAdvertisingPayload(...). 00460 */ 00461 void clearAdvertisingPayload(void) { 00462 gap().clearAdvertisingPayload(); 00463 } 00464 00465 /** 00466 * This API is *deprecated* and resolves to a no-operation. It is left here 00467 * to allow older code to compile. Please avoid using this API in new code. 00468 * This API will be dropped in a future release. 00469 * 00470 * Formerly, it would be used to dynamically reset the accumulated advertising 00471 * payload and scanResponse; to do this, the application would clear and re- 00472 * accumulate a new advertising payload (and scanResponse) before using this 00473 * API. Updates to the underlying advertisement payload now happen 00474 * implicitly. 00475 */ 00476 ble_error_t setAdvertisingPayload(void) { 00477 return BLE_ERROR_NONE; 00478 } 00479 00480 /** 00481 * Accumulate a variable length byte-stream as an AD structure in the 00482 * scanResponse payload. 00483 * 00484 * @param[in] type The type which describes the variable length data. 00485 * @param[in] data data bytes. 00486 * @param[in] len length of data. 00487 * 00488 * @note: This API is now *deprecated* and will be dropped in the future. 00489 * You should use the parallel API from Gap directly. A former call to 00490 * ble.accumulateScanResponse(...) should be replaced with 00491 * ble.gap().accumulateScanResponse(...). 00492 */ 00493 ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) { 00494 return gap().accumulateScanResponse(type, data, len); 00495 } 00496 00497 /** 00498 * Reset any scan response prepared from prior calls to 00499 * accumulateScanResponse(). 00500 * 00501 * @note: This API is now *deprecated* and will be dropped in the future. 00502 * You should use the parallel API from Gap directly. A former call to 00503 * ble.clearScanResponse(...) should be replaced with 00504 * ble.gap().clearScanResponse(...). 00505 */ 00506 void clearScanResponse(void) { 00507 gap().clearScanResponse(); 00508 } 00509 00510 /** 00511 * Start advertising. 00512 * 00513 * @note: This API is now *deprecated* and will be dropped in the future. 00514 * You should use the parallel API from Gap directly. A former call to 00515 * ble.startAdvertising(...) should be replaced with 00516 * ble.gap().startAdvertising(...). 00517 */ 00518 ble_error_t startAdvertising(void) { 00519 return gap().startAdvertising(); 00520 } 00521 00522 /** 00523 * Stop advertising. 00524 * 00525 * @note: This API is now *deprecated* and will be dropped in the future. 00526 * You should use the parallel API from Gap directly. A former call to 00527 * ble.stopAdvertising(...) should be replaced with 00528 * ble.gap().stopAdvertising(...). 00529 */ 00530 ble_error_t stopAdvertising(void) { 00531 return gap().stopAdvertising(); 00532 } 00533 00534 /** 00535 * Setup parameters for GAP scanning--i.e. observer mode. 00536 * @param[in] interval 00537 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s]. 00538 * @param[in] window 00539 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s]. 00540 * @param[in] timeout 00541 * Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout. 00542 * @param[in] activeScanning 00543 * Set to True if active-scanning is required. This is used to fetch the 00544 * scan response from a peer if possible. 00545 * 00546 * The scanning window divided by the interval determines the duty cycle for 00547 * scanning. For example, if the interval is 100ms and the window is 10ms, 00548 * then the controller will scan for 10 percent of the time. It is possible 00549 * to have the interval and window set to the same value. In this case, 00550 * scanning is continuous, with a change of scanning frequency once every 00551 * interval. 00552 * 00553 * Once the scanning parameters have been configured, scanning can be 00554 * enabled by using startScan(). 00555 * 00556 * @Note: The scan interval and window are recommendations to the BLE stack. 00557 * 00558 * @note: This API is now *deprecated* and will be dropped in the future. 00559 * You should use the parallel API from Gap directly. A former call to 00560 * ble.setScanParams(...) should be replaced with 00561 * ble.gap().setScanParams(...). 00562 */ 00563 ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX, 00564 uint16_t window = GapScanningParams::SCAN_WINDOW_MAX, 00565 uint16_t timeout = 0, 00566 bool activeScanning = false) { 00567 return gap().setScanParams(interval, window, timeout, activeScanning); 00568 } 00569 00570 /** 00571 * Setup the scanInterval parameter for GAP scanning--i.e. observer mode. 00572 * @param[in] interval 00573 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s]. 00574 * 00575 * The scanning window divided by the interval determines the duty cycle for 00576 * scanning. For example, if the interval is 100ms and the window is 10ms, 00577 * then the controller will scan for 10 percent of the time. It is possible 00578 * to have the interval and window set to the same value. In this case, 00579 * scanning is continuous, with a change of scanning frequency once every 00580 * interval. 00581 * 00582 * Once the scanning parameters have been configured, scanning can be 00583 * enabled by using startScan(). 00584 * 00585 * @note: This API is now *deprecated* and will be dropped in the future. 00586 * You should use the parallel API from Gap directly. A former call to 00587 * ble.setScanInterval(interval) should be replaced with 00588 * ble.gap().setScanInterval(interval). 00589 */ 00590 ble_error_t setScanInterval(uint16_t interval) { 00591 return gap().setScanInterval(interval); 00592 } 00593 00594 /** 00595 * Setup the scanWindow parameter for GAP scanning--i.e. observer mode. 00596 * @param[in] window 00597 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s]. 00598 * 00599 * The scanning window divided by the interval determines the duty cycle for 00600 * scanning. For example, if the interval is 100ms and the window is 10ms, 00601 * then the controller will scan for 10 percent of the time. It is possible 00602 * to have the interval and window set to the same value. In this case, 00603 * scanning is continuous, with a change of scanning frequency once every 00604 * interval. 00605 * 00606 * Once the scanning parameters have been configured, scanning can be 00607 * enabled by using startScan(). 00608 * 00609 * @note: This API is now *deprecated* and will be dropped in the future. 00610 * You should use the parallel API from Gap directly. A former call to 00611 * ble.setScanWindow(window) should be replaced with 00612 * ble.gap().setScanWindow(window). 00613 */ 00614 ble_error_t setScanWindow(uint16_t window) { 00615 return gap().setScanWindow(window); 00616 } 00617 00618 /** 00619 * Setup parameters for GAP scanning--i.e. observer mode. 00620 * @param[in] timeout 00621 * Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout. 00622 * 00623 * The scanning window divided by the interval determines the duty cycle for 00624 * scanning. For example, if the interval is 100ms and the window is 10ms, 00625 * then the controller will scan for 10 percent of the time. It is possible 00626 * to have the interval and window set to the same value. In this case, 00627 * scanning is continuous, with a change of scanning frequency once every 00628 * interval. 00629 * 00630 * Once the scanning parameters have been configured, scanning can be 00631 * enabled by using startScan(). 00632 * 00633 * @Note: The scan interval and window are recommendations to the BLE stack. 00634 * 00635 * @note: This API is now *deprecated* and will be dropped in the future. 00636 * You should use the parallel API from Gap directly. A former call to 00637 * ble.setScanTimeout(...) should be replaced with 00638 * ble.gap().setScanTimeout(...). 00639 */ 00640 ble_error_t setScanTimeout(uint16_t timeout) { 00641 return gap().setScanTimeout(timeout); 00642 } 00643 00644 /** 00645 * Setup parameters for GAP scanning--i.e. observer mode. 00646 * @param[in] activeScanning 00647 * Set to True if active-scanning is required. This is used to fetch the 00648 * scan response from a peer if possible. 00649 * 00650 * Once the scanning parameters have been configured, scanning can be 00651 * enabled by using startScan(). 00652 * 00653 * @note: This API is now *deprecated* and will be dropped in the future. 00654 * You should use the parallel API from Gap directly. A former call to 00655 * ble.setActiveScan(...) should be replaced with 00656 * ble.gap().setActiveScanning(...). 00657 */ 00658 void setActiveScan(bool activeScanning) { 00659 gap().setActiveScanning(activeScanning); 00660 } 00661 00662 /** 00663 * Start scanning (Observer Procedure) based on the parameters currently in 00664 * effect. 00665 * 00666 * @param[in] callback 00667 * The application specific callback to be invoked upon 00668 * receiving every advertisement report. This can be passed in 00669 * as NULL, in which case scanning may not be enabled at all. 00670 * 00671 * @note: This API is now *deprecated* and will be dropped in the future. 00672 * You should use the parallel API from Gap directly. A former call to 00673 * ble.startScan(callback) should be replaced with 00674 * ble.gap().startScan(callback). 00675 */ 00676 ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params)) { 00677 return gap().startScan(callback); 00678 } 00679 00680 /** 00681 * Same as above, but this takes an (object, method) pair for a callback. 00682 * 00683 * @note: This API is now *deprecated* and will be dropped in the future. 00684 * You should use the parallel API from Gap directly. A former call to 00685 * ble.startScan(callback) should be replaced with 00686 * ble.gap().startScan(object, callback). 00687 */ 00688 template<typename T> 00689 ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params)); 00690 00691 /** 00692 * Stop scanning. The current scanning parameters remain in effect. 00693 * 00694 * @retval BLE_ERROR_NONE if successfully stopped scanning procedure. 00695 * 00696 * @note: This API is now *deprecated* and will be dropped in the future. 00697 * You should use the parallel API from Gap directly. A former call to 00698 * ble.stopScan() should be replaced with 00699 * ble.gap().stopScan(). 00700 */ 00701 ble_error_t stopScan(void) { 00702 return gap().stopScan(); 00703 } 00704 00705 /** 00706 * Create a connection (GAP Link Establishment). 00707 * @param peerAddr 00708 * 48-bit address, LSB format. 00709 * @param peerAddrType 00710 * Address type of the peer. 00711 * @param connectionParams 00712 * Connection parameters. 00713 * @param scanParams 00714 * Paramters to be used while scanning for the peer. 00715 * @return BLE_ERROR_NONE if connection establishment procedure is started 00716 * successfully. The onConnection callback (if set) will be invoked upon 00717 * a connection event. 00718 * 00719 * @note: This API is now *deprecated* and will be dropped in the future. 00720 * You should use the parallel API from Gap directly. A former call to 00721 * ble.connect(...) should be replaced with 00722 * ble.gap().connect(...). 00723 */ 00724 ble_error_t connect(const Gap::Address_t peerAddr, 00725 Gap::AddressType_t peerAddrType = Gap::ADDR_TYPE_RANDOM_STATIC, 00726 const Gap::ConnectionParams_t *connectionParams = NULL, 00727 const GapScanningParams *scanParams = NULL) { 00728 return gap().connect(peerAddr, peerAddrType, connectionParams, scanParams); 00729 } 00730 00731 /** 00732 * This call initiates the disconnection procedure, and its completion will 00733 * be communicated to the application with an invocation of the 00734 * onDisconnection callback. 00735 * 00736 * @param[in] connectionHandle 00737 * @param[in] reason 00738 * The reason for disconnection to be sent back to the peer. 00739 */ 00740 ble_error_t disconnect(Gap::Handle_t connectionHandle, Gap::DisconnectionReason_t reason) { 00741 return gap().disconnect(connectionHandle, reason); 00742 } 00743 00744 /** 00745 * This call initiates the disconnection procedure, and its completion will 00746 * be communicated to the application with an invocation of the 00747 * onDisconnection callback. 00748 * 00749 * @param reason 00750 * The reason for disconnection to be sent back to the peer. 00751 * 00752 * @note: This API is now *deprecated* and will be dropped in the future. 00753 * You should use the parallel API from Gap directly. A former call to 00754 * ble.disconnect(reason) should be replaced with 00755 * ble.gap().disconnect(reason). 00756 * 00757 * @note: this version of disconnect() doesn't take a connection handle. It 00758 * will work reliably only for stacks which are limited to a single 00759 * connection. This API should be considered *deprecated* in favour of the 00760 * alternative which takes a connection handle. It will be dropped in the future. 00761 */ 00762 ble_error_t disconnect(Gap::DisconnectionReason_t reason) { 00763 return gap().disconnect(reason); 00764 } 00765 00766 /** 00767 * Returns the current GAP state of the device using a bitmask which 00768 * describes whether the device is advertising and/or connected. 00769 * 00770 * @note: This API is now *deprecated* and will be dropped in the future. 00771 * You should use the parallel API from Gap directly. A former call to 00772 * ble.getGapState() should be replaced with 00773 * ble.gap().getState(). 00774 */ 00775 Gap::GapState_t getGapState(void) const { 00776 return gap().getState(); 00777 } 00778 00779 /** 00780 * Get the GAP peripheral preferred connection parameters. These are the 00781 * defaults that the peripheral would like to have in a connection. The 00782 * choice of the connection parameters is eventually up to the central. 00783 * 00784 * @param[out] params 00785 * The structure where the parameters will be stored. Memory 00786 * for this is owned by the caller. 00787 * 00788 * @return BLE_ERROR_NONE if the parameters were successfully filled into 00789 * the given structure pointed to by params. 00790 * 00791 * @note: This API is now *deprecated* and will be dropped in the future. 00792 * You should use the parallel API from Gap directly. A former call to 00793 * ble.getPreferredConnectionParams() should be replaced with 00794 * ble.gap().getPreferredConnectionParams(). 00795 */ 00796 ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params) { 00797 return gap().getPreferredConnectionParams(params); 00798 } 00799 00800 /** 00801 * Set the GAP peripheral preferred connection parameters. These are the 00802 * defaults that the peripheral would like to have in a connection. The 00803 * choice of the connection parameters is eventually up to the central. 00804 * 00805 * @param[in] params 00806 * The structure containing the desired parameters. 00807 * 00808 * @note: This API is now *deprecated* and will be dropped in the future. 00809 * You should use the parallel API from Gap directly. A former call to 00810 * ble.setPreferredConnectionParams() should be replaced with 00811 * ble.gap().setPreferredConnectionParams(). 00812 */ 00813 ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params) { 00814 return gap().setPreferredConnectionParams(params); 00815 } 00816 00817 /** 00818 * Update connection parameters while in the peripheral role. 00819 * @details In the peripheral role, this will send the corresponding L2CAP request to the connected peer and wait for 00820 * the central to perform the procedure. 00821 * @param[in] handle 00822 * Connection Handle 00823 * @param[in] params 00824 * Pointer to desired connection parameters. If NULL is provided on a peripheral role, 00825 * the parameters in the PPCP characteristic of the GAP service will be used instead. 00826 * 00827 * @note: This API is now *deprecated* and will be dropped in the future. 00828 * You should use the parallel API from Gap directly. A former call to 00829 * ble.updateConnectionParams() should be replaced with 00830 * ble.gap().updateConnectionParams(). 00831 */ 00832 ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) { 00833 return gap().updateConnectionParams(handle, params); 00834 } 00835 00836 /** 00837 * Set the device name characteristic in the GAP service. 00838 * @param[in] deviceName 00839 * The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string. 00840 * 00841 * @note: This API is now *deprecated* and will be dropped in the future. 00842 * You should use the parallel API from Gap directly. A former call to 00843 * ble.setDeviceName() should be replaced with 00844 * ble.gap().setDeviceName(). 00845 */ 00846 ble_error_t setDeviceName(const uint8_t *deviceName) { 00847 return gap().setDeviceName(deviceName); 00848 } 00849 00850 /** 00851 * Get the value of the device name characteristic in the GAP service. 00852 * @param[out] deviceName 00853 * Pointer to an empty buffer where the UTF-8 *non NULL- 00854 * terminated* string will be placed. Set this 00855 * value to NULL in order to obtain the deviceName-length 00856 * from the 'length' parameter. 00857 * 00858 * @param[in/out] lengthP 00859 * (on input) Length of the buffer pointed to by deviceName; 00860 * (on output) the complete device name length (without the 00861 * null terminator). 00862 * 00863 * @note If the device name is longer than the size of the supplied buffer, 00864 * length will return the complete device name length, and not the 00865 * number of bytes actually returned in deviceName. The application may 00866 * use this information to retry with a suitable buffer size. 00867 * 00868 * @note: This API is now *deprecated* and will be dropped in the future. 00869 * You should use the parallel API from Gap directly. A former call to 00870 * ble.getDeviceName() should be replaced with 00871 * ble.gap().getDeviceName(). 00872 */ 00873 ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) { 00874 return gap().getDeviceName(deviceName, lengthP); 00875 } 00876 00877 /** 00878 * Set the appearance characteristic in the GAP service. 00879 * @param[in] appearance 00880 * The new value for the device-appearance. 00881 * 00882 * @note: This API is now *deprecated* and will be dropped in the future. 00883 * You should use the parallel API from Gap directly. A former call to 00884 * ble.setAppearance() should be replaced with 00885 * ble.gap().setAppearance(). 00886 */ 00887 ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) { 00888 return gap().setAppearance(appearance); 00889 } 00890 00891 /** 00892 * Get the appearance characteristic in the GAP service. 00893 * @param[out] appearance 00894 * The new value for the device-appearance. 00895 * 00896 * @note: This API is now *deprecated* and will be dropped in the future. 00897 * You should use the parallel API from Gap directly. A former call to 00898 * ble.getAppearance() should be replaced with 00899 * ble.gap().getAppearance(). 00900 */ 00901 ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) { 00902 return gap().getAppearance(appearanceP); 00903 } 00904 00905 /** 00906 * Set the radio's transmit power. 00907 * @param[in] txPower Radio transmit power in dBm. 00908 * 00909 * @note: This API is now *deprecated* and will be dropped in the future. 00910 * You should use the parallel API from Gap directly. A former call to 00911 * ble.setTxPower() should be replaced with 00912 * ble.gap().setTxPower(). 00913 */ 00914 ble_error_t setTxPower(int8_t txPower) { 00915 return gap().setTxPower(txPower); 00916 } 00917 00918 /** 00919 * Query the underlying stack for permitted arguments for setTxPower(). 00920 * 00921 * @param[out] valueArrayPP 00922 * Out parameter to receive the immutable array of Tx values. 00923 * @param[out] countP 00924 * Out parameter to receive the array's size. 00925 * 00926 * @note: This API is now *deprecated* and will be dropped in the future. 00927 * You should use the parallel API from Gap directly. A former call to 00928 * ble.getPermittedTxPowerValues() should be replaced with 00929 * ble.gap().getPermittedTxPowerValues(). 00930 */ 00931 void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) { 00932 gap().getPermittedTxPowerValues(valueArrayPP, countP); 00933 } 00934 00935 /** 00936 * Add a service declaration to the local server ATT table. Also add the 00937 * characteristics contained within. 00938 * 00939 * @note: This API is now *deprecated* and will be dropped in the future. 00940 * You should use the parallel API from GattServer directly. A former call 00941 * to ble.addService() should be replaced with 00942 * ble.gattServer().addService(). 00943 */ 00944 ble_error_t addService(GattService &service) { 00945 return gattServer().addService(service); 00946 } 00947 00948 /** 00949 * Read the value of a characteristic from the local GattServer 00950 * @param[in] attributeHandle 00951 * Attribute handle for the value attribute of the characteristic. 00952 * @param[out] buffer 00953 * A buffer to hold the value being read. 00954 * @param[in/out] lengthP 00955 * Length of the buffer being supplied. If the attribute 00956 * value is longer than the size of the supplied buffer, 00957 * this variable will hold upon return the total attribute value length 00958 * (excluding offset). The application may use this 00959 * information to allocate a suitable buffer size. 00960 * 00961 * @return BLE_ERROR_NONE if a value was read successfully into the buffer. 00962 * 00963 * @note: This API is now *deprecated* and will be dropped in the future. 00964 * You should use the parallel API from GattServer directly. A former call 00965 * to ble.readCharacteristicValue() should be replaced with 00966 * ble.gattServer().read(). 00967 */ 00968 ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) { 00969 return gattServer().read(attributeHandle, buffer, lengthP); 00970 } 00971 00972 /** 00973 * Read the value of a characteristic from the local GattServer 00974 * @param[in] connectionHandle 00975 * Connection Handle. 00976 * @param[in] attributeHandle 00977 * Attribute handle for the value attribute of the characteristic. 00978 * @param[out] buffer 00979 * A buffer to hold the value being read. 00980 * @param[in/out] lengthP 00981 * Length of the buffer being supplied. If the attribute 00982 * value is longer than the size of the supplied buffer, 00983 * this variable will hold upon return the total attribute value length 00984 * (excluding offset). The application may use this 00985 * information to allocate a suitable buffer size. 00986 * 00987 * @return BLE_ERROR_NONE if a value was read successfully into the buffer. 00988 * 00989 * @note This API is a version of above with an additional connection handle 00990 * parameter to allow fetches for connection-specific multivalued 00991 * attributes (such as the CCCDs). 00992 * 00993 * @note: This API is now *deprecated* and will be dropped in the future. 00994 * You should use the parallel API from GattServer directly. A former call 00995 * to ble.readCharacteristicValue() should be replaced with 00996 * ble.gattServer().read(). 00997 */ 00998 ble_error_t readCharacteristicValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) { 00999 return gattServer().read(connectionHandle, attributeHandle, buffer, lengthP); 01000 } 01001 01002 /** 01003 * Update the value of a characteristic on the local GattServer. 01004 * 01005 * @param[in] attributeHandle 01006 * Handle for the value attribute of the Characteristic. 01007 * @param[in] value 01008 * A pointer to a buffer holding the new value 01009 * @param[in] size 01010 * Size of the new value (in bytes). 01011 * @param[in] localOnly 01012 * Should this update be kept on the local 01013 * GattServer regardless of the state of the 01014 * notify/indicate flag in the CCCD for this 01015 * Characteristic? If set to true, no notification 01016 * or indication is generated. 01017 * 01018 * @return BLE_ERROR_NONE if we have successfully set the value of the attribute. 01019 * 01020 * @note: This API is now *deprecated* and will be dropped in the future. 01021 * You should use the parallel API from GattServer directly. A former call 01022 * to ble.updateCharacteristicValue() should be replaced with 01023 * ble.gattServer().write(). 01024 */ 01025 ble_error_t updateCharacteristicValue(GattAttribute::Handle_t attributeHandle, 01026 const uint8_t *value, 01027 uint16_t size, 01028 bool localOnly = false) { 01029 return gattServer().write(attributeHandle, value, size, localOnly); 01030 } 01031 01032 /** 01033 * Update the value of a characteristic on the local GattServer. A version 01034 * of the same as above with connection handle parameter to allow updates 01035 * for connection-specific multivalued attributes (such as the CCCDs). 01036 * 01037 * @param[in] connectionHandle 01038 * Connection Handle. 01039 * @param[in] attributeHandle 01040 * Handle for the value attribute of the Characteristic. 01041 * @param[in] value 01042 * A pointer to a buffer holding the new value 01043 * @param[in] size 01044 * Size of the new value (in bytes). 01045 * @param[in] localOnly 01046 * Should this update be kept on the local 01047 * GattServer regardless of the state of the 01048 * notify/indicate flag in the CCCD for this 01049 * Characteristic? If set to true, no notification 01050 * or indication is generated. 01051 * 01052 * @return BLE_ERROR_NONE if we have successfully set the value of the attribute. 01053 * 01054 * @note: This API is now *deprecated* and will be dropped in the future. 01055 * You should use the parallel API from GattServer directly. A former call 01056 * to ble.updateCharacteristicValue() should be replaced with 01057 * ble.gattServer().write(). 01058 */ 01059 ble_error_t updateCharacteristicValue(Gap::Handle_t connectionHandle, 01060 GattAttribute::Handle_t attributeHandle, 01061 const uint8_t *value, 01062 uint16_t size, 01063 bool localOnly = false) { 01064 return gattServer().write(connectionHandle, attributeHandle, value, size, localOnly); 01065 } 01066 01067 /** 01068 * Enable the BLE stack's Security Manager. The Security Manager implements 01069 * the actual cryptographic algorithms and protocol exchanges that allow two 01070 * devices to securely exchange data and privately detect each other. 01071 * Calling this API is a prerequisite for encryption and pairing (bonding). 01072 * 01073 * @param[in] enableBonding Allow for bonding. 01074 * @param[in] requireMITM Require protection for man-in-the-middle attacks. 01075 * @param[in] iocaps To specify IO capabilities of this peripheral, 01076 * such as availability of a display or keyboard to 01077 * support out-of-band exchanges of security data. 01078 * @param[in] passkey To specify a static passkey. 01079 * 01080 * @return BLE_ERROR_NONE on success. 01081 * 01082 * @note: This API is now *deprecated* and will be dropped in the future. 01083 * You should use the parallel API from SecurityManager directly. A former 01084 * call to ble.initializeSecurity(...) should be replaced with 01085 * ble.securityManager().init(...). 01086 */ 01087 ble_error_t initializeSecurity(bool enableBonding = true, 01088 bool requireMITM = true, 01089 SecurityManager::SecurityIOCapabilities_t iocaps = SecurityManager::IO_CAPS_NONE, 01090 const SecurityManager::Passkey_t passkey = NULL) { 01091 return securityManager().init(enableBonding, requireMITM, iocaps, passkey); 01092 } 01093 01094 /** 01095 * Get the security status of a connection. 01096 * 01097 * @param[in] connectionHandle Handle to identify the connection. 01098 * @param[out] securityStatusP security status. 01099 * 01100 * @return BLE_SUCCESS Or appropriate error code indicating reason for failure. 01101 * 01102 * @note: This API is now *deprecated* and will be dropped in the future. 01103 * You should use the parallel API from SecurityManager directly. A former 01104 * call to ble.getLinkSecurity(...) should be replaced with 01105 * ble.securityManager().getLinkSecurity(...). 01106 */ 01107 ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) { 01108 return securityManager().getLinkSecurity(connectionHandle, securityStatusP); 01109 } 01110 01111 /** 01112 * Delete all peer device context and all related bonding information from 01113 * the database within the security manager. 01114 * 01115 * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure. 01116 * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization and/or 01117 * application registration. 01118 * 01119 * @note: This API is now *deprecated* and will be dropped in the future. 01120 * You should use the parallel API from SecurityManager directly. A former 01121 * call to ble.purgeAllBondingState() should be replaced with 01122 * ble.securityManager().purgeAllBondingState(). 01123 */ 01124 ble_error_t purgeAllBondingState(void) { 01125 return securityManager().purgeAllBondingState(); 01126 } 01127 01128 /** 01129 * Setup a callback for timeout events. Refer to Gap::TimeoutSource_t for 01130 * possible event types. 01131 * 01132 * @note: This API is now *deprecated* and will be dropped in the future. 01133 * You should use the parallel API from Gap directly. A former call 01134 * to ble.onTimeout(callback) should be replaced with 01135 * ble.gap().onTimeout(callback). 01136 */ 01137 void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback) { 01138 gap().onTimeout(timeoutCallback); 01139 } 01140 01141 /** 01142 * Setup a callback for connection events. Refer to Gap::ConnectionEventCallback_t. 01143 * 01144 * @note: This API is now *deprecated* and will be dropped in the future. 01145 * You should use the parallel API from Gap directly. A former call 01146 * to ble.onConnection(callback) should be replaced with 01147 * ble.gap().onConnection(callback). 01148 */ 01149 void onConnection(Gap::ConnectionEventCallback_t connectionCallback) { 01150 gap().onConnection(connectionCallback); 01151 } 01152 01153 /** 01154 * Append to a chain of callbacks to be invoked upon GAP disconnection. 01155 * 01156 * @note: This API is now *deprecated* and will be dropped in the future. 01157 * You should use the parallel API from Gap directly. A former call 01158 * to ble.onDisconnection(callback) should be replaced with 01159 * ble.gap().onDisconnection(callback). 01160 */ 01161 void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback) { 01162 gap().onDisconnection(disconnectionCallback); 01163 } 01164 01165 template<typename T> 01166 void onDisconnection(T *tptr, void (T::*mptr)(const Gap::DisconnectionCallbackParams_t*)) { 01167 gap().onDisconnection(tptr, mptr); 01168 } 01169 01170 /** 01171 * Radio Notification is a feature that enables ACTIVE and INACTIVE 01172 * (nACTIVE) signals from the stack that notify the application when the 01173 * radio is in use. The signal is sent using software interrupt. 01174 * 01175 * The ACTIVE signal is sent before the Radio Event starts. The nACTIVE 01176 * signal is sent at the end of the Radio Event. These signals can be used 01177 * by the application programmer to synchronize application logic with radio 01178 * activity. For example, the ACTIVE signal can be used to shut off external 01179 * devices to manage peak current drawn during periods when the radio is on, 01180 * or to trigger sensor data collection for transmission in the Radio Event. 01181 * 01182 * @param callback 01183 * The application handler to be invoked in response to a radio 01184 * ACTIVE/INACTIVE event. 01185 * 01186 * @note: This API is now *deprecated* and will be dropped in the future. 01187 * You should use the parallel API from Gap directly. A former call 01188 * to ble.onRadioNotification(...) should be replaced with 01189 * ble.gap().onRadioNotification(...). 01190 */ 01191 void onRadioNotification(void (*callback)(bool)) { 01192 gap().onRadioNotification(callback); 01193 } 01194 01195 /** 01196 * Add a callback for the GATT event DATA_SENT (which is triggered when 01197 * updates are sent out by GATT in the form of notifications). 01198 * 01199 * @Note: it is possible to chain together multiple onDataSent callbacks 01200 * (potentially from different modules of an application) to receive updates 01201 * to characteristics. 01202 * 01203 * @Note: it is also possible to setup a callback into a member function of 01204 * some object. 01205 * 01206 * @note: This API is now *deprecated* and will be dropped in the future. 01207 * You should use the parallel API from GattServer directly. A former call 01208 * to ble.onDataSent(...) should be replaced with 01209 * ble.gattServer().onDataSent(...). 01210 */ 01211 void onDataSent(void (*callback)(unsigned count)) { 01212 gattServer().onDataSent(callback); 01213 } 01214 template <typename T> void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count)) { 01215 gattServer().onDataSent(objPtr, memberPtr); 01216 } 01217 01218 /** 01219 * Setup a callback for when an attribute has its value updated by or at the 01220 * connected peer. For a peripheral, this callback triggered when the local 01221 * GATT server has an attribute updated by a write command from the peer. 01222 * For a Central, this callback is triggered when a response is received for 01223 * a write request. 01224 * 01225 * @Note: it is possible to chain together multiple onDataWritten callbacks 01226 * (potentially from different modules of an application) to receive updates 01227 * to characteristics. Many services, such as DFU and UART add their own 01228 * onDataWritten callbacks behind the scenes to trap interesting events. 01229 * 01230 * @Note: it is also possible to setup a callback into a member function of 01231 * some object. 01232 * 01233 * @note: This API is now *deprecated* and will be dropped in the future. 01234 * You should use the parallel API from GattServer directly. A former call 01235 * to ble.onDataWritten(...) should be replaced with 01236 * ble.gattServer().onDataWritten(...). 01237 */ 01238 void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) { 01239 gattServer().onDataWritten(callback); 01240 } 01241 template <typename T> void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) { 01242 gattServer().onDataWritten(objPtr, memberPtr); 01243 } 01244 01245 /** 01246 * Setup a callback to be invoked on the peripheral when an attribute is 01247 * being read by a remote client. 01248 * 01249 * @Note: this functionality may not be available on all underlying stacks. 01250 * You could use GattCharacteristic::setReadAuthorizationCallback() as an 01251 * alternative. 01252 * 01253 * @Note: it is possible to chain together multiple onDataRead callbacks 01254 * (potentially from different modules of an application) to receive updates 01255 * to characteristics. Services may add their own onDataRead callbacks 01256 * behind the scenes to trap interesting events. 01257 * 01258 * @Note: it is also possible to setup a callback into a member function of 01259 * some object. 01260 * 01261 * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available; 01262 * else BLE_ERROR_NONE. 01263 * 01264 * @note: This API is now *deprecated* and will be dropped in the future. 01265 * You should use the parallel API from GattServer directly. A former call 01266 * to ble.onDataRead(...) should be replaced with 01267 * ble.gattServer().onDataRead(...). 01268 */ 01269 ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) { 01270 return gattServer().onDataRead(callback); 01271 } 01272 template <typename T> ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) { 01273 return gattServer().onDataRead(objPtr, memberPtr); 01274 } 01275 01276 /** 01277 * Setup a callback for when notifications/indications are enabled for a 01278 * characteristic on the local GattServer. 01279 * 01280 * @note: This API is now *deprecated* and will be dropped in the future. 01281 * You should use the parallel API from GattServer directly. A former call 01282 * to ble.onUpdatesEnabled(callback) should be replaced with 01283 * ble.gattServer().onUpdatesEnabled(callback). 01284 */ 01285 void onUpdatesEnabled(GattServer::EventCallback_t callback) { 01286 gattServer().onUpdatesEnabled(callback); 01287 } 01288 01289 /** 01290 * Setup a callback for when notifications/indications are disabled for a 01291 * characteristic on the local GattServer. 01292 * 01293 * @note: This API is now *deprecated* and will be dropped in the future. 01294 * You should use the parallel API from GattServer directly. A former call 01295 * to ble.onUpdatesEnabled(callback) should be replaced with 01296 * ble.gattServer().onUpdatesEnabled(callback). 01297 */ 01298 void onUpdatesDisabled(GattServer::EventCallback_t callback) { 01299 gattServer().onUpdatesDisabled(callback); 01300 } 01301 01302 /** 01303 * Setup a callback for when the GATT server receives a response for an 01304 * indication event sent previously. 01305 * 01306 * @note: This API is now *deprecated* and will be dropped in the future. 01307 * You should use the parallel API from GattServer directly. A former call 01308 * to ble.onConfirmationReceived(callback) should be replaced with 01309 * ble.gattServer().onConfirmationReceived(callback). 01310 */ 01311 void onConfirmationReceived(GattServer::EventCallback_t callback) { 01312 gattServer().onConfirmationReceived(callback); 01313 } 01314 01315 /** 01316 * Setup a callback for when the security setup procedure (key generation 01317 * and exchange) for a link has started. This will be skipped for bonded 01318 * devices. The callback is passed in parameters received from the peer's 01319 * security request: bool allowBonding, bool requireMITM, and 01320 * SecurityIOCapabilities_t. 01321 * 01322 * @note: This API is now *deprecated* and will be dropped in the future. 01323 * You should use the parallel API from SecurityManager directly. A former 01324 * call to ble.onSecuritySetupInitiated(callback) should be replaced with 01325 * ble.securityManager().onSecuritySetupInitiated(callback). 01326 */ 01327 void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) { 01328 securityManager().onSecuritySetupInitiated(callback); 01329 } 01330 01331 /** 01332 * Setup a callback for when the security setup procedure (key generation 01333 * and exchange) for a link has completed. This will be skipped for bonded 01334 * devices. The callback is passed in the success/failure status of the 01335 * security setup procedure. 01336 * 01337 * @note: This API is now *deprecated* and will be dropped in the future. 01338 * You should use the parallel API from SecurityManager directly. A former 01339 * call to ble.onSecuritySetupCompleted(callback) should be replaced with 01340 * ble.securityManager().onSecuritySetupCompleted(callback). 01341 */ 01342 void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) { 01343 securityManager().onSecuritySetupCompleted(callback); 01344 } 01345 01346 /** 01347 * Setup a callback for when a link with the peer is secured. For bonded 01348 * devices, subsequent reconnections with bonded peer will result only in 01349 * this callback when the link is secured and setup procedures will not 01350 * occur unless the bonding information is either lost or deleted on either 01351 * or both sides. The callback is passed in a SecurityManager::SecurityMode_t according 01352 * to the level of security in effect for the secured link. 01353 * 01354 * @note: This API is now *deprecated* and will be dropped in the future. 01355 * You should use the parallel API from SecurityManager directly. A former 01356 * call to ble.onLinkSecured(callback) should be replaced with 01357 * ble.securityManager().onLinkSecured(callback). 01358 */ 01359 void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) { 01360 securityManager().onLinkSecured(callback); 01361 } 01362 01363 /** 01364 * Setup a callback for successful bonding; i.e. that link-specific security 01365 * context is stored persistently for a peer device. 01366 * 01367 * @note: This API is now *deprecated* and will be dropped in the future. 01368 * You should use the parallel API from SecurityManager directly. A former 01369 * call to ble.onSecurityContextStored(callback) should be replaced with 01370 * ble.securityManager().onSecurityContextStored(callback). 01371 */ 01372 void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) { 01373 securityManager().onSecurityContextStored(callback); 01374 } 01375 01376 /** 01377 * Setup a callback for when the passkey needs to be displayed on a 01378 * peripheral with DISPLAY capability. This happens when security is 01379 * configured to prevent Man-In-The-Middle attacks, and a PIN (or passkey) 01380 * needs to be exchanged between the peers to authenticate the connection 01381 * attempt. 01382 * 01383 * @note: This API is now *deprecated* and will be dropped in the future. 01384 * You should use the parallel API from SecurityManager directly. A former 01385 * call to ble.onPasskeyDisplay(callback) should be replaced with 01386 * ble.securityManager().onPasskeyDisplay(callback). 01387 */ 01388 void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) { 01389 return securityManager().onPasskeyDisplay(callback); 01390 } 01391 01392 private: 01393 BLE(const BLE&); 01394 BLE &operator=(const BLE &); 01395 01396 private: 01397 BLEInstanceBase *transport; /* the device specific backend */ 01398 }; 01399 01400 typedef BLE BLEDevice; /* DEPRECATED. This type alias is retained for the sake of compatibility with older 01401 * code. Will be dropped at some point soon.*/ 01402 01403 #endif // ifndef __BLE_H__
Generated on Mon Jul 18 2022 21:56:46 by
1.7.2