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