Qi Yao
/
LinkNode---test123
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
LinkNode-Test
by 
Qi Yao
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(Gap::AddressType_t type, const Gap::Address_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(Gap::AddressType_t *typeP, Gap::Address_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 Gap::Address_t peerAddr, 00756 Gap::AddressType_t peerAddrType = Gap::ADDR_TYPE_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 Tue Jul 12 2022 16:00:19 by
1.7.2