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