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