From 55657c588b4a84b28d428b113e81571b4f4d540a Mon Sep 17 00:00:00 2001 From: Paul Szczepanek Date: Wed, 23 Jun 2021 13:27:15 +0100 Subject: [PATCH] clarify ble event docs with corssreferences --- connectivity/FEATURE_BLE/include/ble/Gap.h | 22 +++-- .../FEATURE_BLE/include/ble/GattClient.h | 2 + .../FEATURE_BLE/include/ble/GattServer.h | 22 ++++- .../FEATURE_BLE/include/ble/SecurityManager.h | 96 +++++++++++++++++-- 4 files changed, 122 insertions(+), 20 deletions(-) diff --git a/connectivity/FEATURE_BLE/include/ble/Gap.h b/connectivity/FEATURE_BLE/include/ble/Gap.h index a5477aa5a6..03c89bef1c 100644 --- a/connectivity/FEATURE_BLE/include/ble/Gap.h +++ b/connectivity/FEATURE_BLE/include/ble/Gap.h @@ -302,7 +302,7 @@ public: */ struct EventHandler { /** - * Called when an advertising device receive a scan response. + * Called when an advertising device receive a scan request. * * @param event Scan request event. * @@ -319,6 +319,8 @@ public: * * @param event Advertising start event. * + * @note Check event.getStatus() to see if advertising started successfully + * * @see startAdvertising() */ virtual void onAdvertisingStart(const AdvertisingStartEvent &event) @@ -333,7 +335,8 @@ public: * * @param event Advertising end event. * - * @see startAdvertising() + * @note Check event.getStatus() to see if advertising ended successfully + * * @see stopAdvertising() * @see onConnectionComplete() */ @@ -409,8 +412,9 @@ public: } /** - * Called when connection attempt ends or an advertising device has been - * connected. + * Called when connection attempt ends. Check event.getStatus() to see if connection + * was established. If this device is the peripheral and it as advertising this will + * end advertising which will also create the onAdvertisingEnd event. * * @see startAdvertising() * @see connect() @@ -431,8 +435,8 @@ public: * * @version 4.1+. * - * @note This event is not generated if connection parameters update - * is managed by the middleware. + * @note This event will only be produced if manageConnectionParametersUpdateRequest(true) + * was called. Otherwise the stack will handle the request and no event will be generated. * * @see manageConnectionParametersUpdateRequest() * @see acceptConnectionParametersUpdate() @@ -553,6 +557,8 @@ public: /** * Function invoked when the privacy subsystem has been enabled and is * ready to be used. + * + * @see enablePrivacy() */ virtual void onPrivacyEnabled() { @@ -1286,6 +1292,8 @@ public: * false to disable it. * * @return BLE_ERROR_NONE in case of success or an appropriate error code. + * + * @see EventHandler::onPrivacyEnabled() */ ble_error_t enablePrivacy(bool enable); @@ -1433,7 +1441,7 @@ public: */ ble_error_t reset(); - /** + /** * Register a Gap shutdown event handler. * * The handler is called when the Gap instance is about to shut down. diff --git a/connectivity/FEATURE_BLE/include/ble/GattClient.h b/connectivity/FEATURE_BLE/include/ble/GattClient.h index 216a085861..2e71cd9d7b 100644 --- a/connectivity/FEATURE_BLE/include/ble/GattClient.h +++ b/connectivity/FEATURE_BLE/include/ble/GattClient.h @@ -107,6 +107,8 @@ public: * * @param connectionHandle The handle of the connection that changed the size. * @param attMtuSize + * + * @see negotiateAttMtu() */ virtual void onAttMtuChange( ble::connection_handle_t connectionHandle, diff --git a/connectivity/FEATURE_BLE/include/ble/GattServer.h b/connectivity/FEATURE_BLE/include/ble/GattServer.h index 6b7335d8f3..4e457aaab9 100644 --- a/connectivity/FEATURE_BLE/include/ble/GattServer.h +++ b/connectivity/FEATURE_BLE/include/ble/GattServer.h @@ -112,6 +112,8 @@ public: * * @param connectionHandle The handle of the connection that changed the size. * @param attMtuSize + * + * @see negotiateAttMtu() */ virtual void onAttMtuChange( ble::connection_handle_t connectionHandle, @@ -162,14 +164,14 @@ public: /** * Function invoked when the GattServer instance is about - * to be shut down. This can result in a call to reset() or BLE::reset(). + * to be shut down. This can be the result of a call to reset() or BLE::reset(). */ virtual void onShutdown(const GattServer &server) { (void)server; } /** - * Function invoked when the client has subscribed to characteristic updates + * Function invoked when the client has subscribed to characteristic updates. * * @note params has a temporary scope and should be copied by the * application if needed later @@ -179,7 +181,7 @@ public: } /** - * Function invoked when the client has unsubscribed to characteristic updates + * Function invoked when the client has unsubscribed from characteristic updates. * * @note params has a temporary scope and should be copied by the * application if needed later @@ -303,9 +305,11 @@ public: * GattServer state. * * @note This function is meant to be overridden in the platform-specific - * subclass. Overides must call the parent function before any cleanup. + * subclass. Overrides must call the parent function before any cleanup. * * @return BLE_ERROR_NONE on success. + * + * @see EventHandler::onShutdown() */ ble_error_t reset(); @@ -401,6 +405,9 @@ public: * * @return BLE_ERROR_NONE if the attribute value has been successfully * updated. + * + * @see EventHandler::onDataSent(), this will only be triggered if there are + * client subscribed and the localOnly parameter is set to false. */ ble_error_t write( GattAttribute::Handle_t attributeHandle, @@ -429,6 +436,9 @@ public: * * @return BLE_ERROR_NONE if the attribute value has been successfully * updated. + * + * @see EventHandler::onDataSent(), this will only be triggered if there are + * client subscribed and the localOnly parameter is set to false. */ ble_error_t write( ble::connection_handle_t connectionHandle, @@ -448,6 +458,8 @@ public: * * @return BLE_ERROR_NONE if the connection and handle are found. False * otherwise. + * + * @see EventHandler::onDataSent() */ ble_error_t areUpdatesEnabled( const GattCharacteristic &characteristic, @@ -466,6 +478,8 @@ public: * * @return BLE_ERROR_NONE if the connection and handle are found. False * otherwise. + * + * @see EventHandler::onDataSent() */ ble_error_t areUpdatesEnabled( ble::connection_handle_t connectionHandle, diff --git a/connectivity/FEATURE_BLE/include/ble/SecurityManager.h b/connectivity/FEATURE_BLE/include/ble/SecurityManager.h index c32d0c9c40..02f759493d 100644 --- a/connectivity/FEATURE_BLE/include/ble/SecurityManager.h +++ b/connectivity/FEATURE_BLE/include/ble/SecurityManager.h @@ -249,10 +249,17 @@ public: #if BLE_ROLE_PERIPHERAL /** - * Request application to accept or reject pairing. Application should respond by - * calling the appropriate function: acceptPairingRequest or cancelPairingRequest + * Called when a pairing request is received. Application should respond by + * calling the appropriate function: acceptPairingRequest() or cancelPairingRequest(). + * This event will only trigger if setPairingRequestAuthorisation(true) was called. + * Otherwise the stack will handle the requests. * * @param[in] connectionHandle connection connectionHandle + * + * @see requestPairing() + * @see requestAuthentication() + * @see setLinkEncryption() + * @see setPairingRequestAuthorisation() */ virtual void pairingRequest(ble::connection_handle_t connectionHandle) { (void)connectionHandle; @@ -264,6 +271,8 @@ public: * * @param[in] connectionHandle connection connectionHandle * @param[in] result result of the pairing indicating success or reason for failure + * + * @see acceptPairingRequest() */ virtual void pairingResult(ble::connection_handle_t connectionHandle, SecurityCompletionStatus_t result) { (void)connectionHandle; @@ -277,6 +286,8 @@ public: * @param[in] connectionHandle Connection handle. * @param[in] peer_address Peer address that has been saved by the security database, NULL it not found. * @param[in] address_is_public Address type, true if public. Invalid if peer_address NULL. + * + * @see getPeerIdentity() */ virtual void peerIdentity(ble::connection_handle_t connectionHandle, const address_t *peer_address, @@ -294,6 +305,8 @@ public: * Deliver the requested whitelist to the application. * * @param[in] whitelist pointer to the whitelist filled with entries based on bonding information + * + * @see generateWhitelistFromBondTable() */ virtual void whitelistFromBondTable(::ble::whitelist_t* whitelist) { (void)whitelist; @@ -304,10 +317,14 @@ public: // /** - * Inform the device of the encryption state of a given link. + * Triggered by change of encryption state on a link. This change can be initiated + * locally or by the remote peer. * * @param[in] connectionHandle connection connectionHandle * @param[in] result encryption state of the link + * + * @see requestAuthentication() + * @see setLinkEncryption() */ virtual void linkEncryptionResult(ble::connection_handle_t connectionHandle, ble::link_encryption_t result) { (void)connectionHandle; @@ -319,10 +336,14 @@ public: // /** - * Display the given passkey on the local device. + * Triggered during pairing based on IO capabilities of devices. Display the given + * passkey on the local device for user verification. * * @param[in] connectionHandle connection connectionHandle * @param[in] passkey 6 digit passkey to be displayed + * + * @see init() + * @see setIoCapability() */ #if BLE_PASSKEY_DISPLAY_REVERSED_DIGITS_DEPRECATION MBED_DEPRECATED_SINCE("mbed-os-6.8.0", "This returns the passkey in reverse order. Please set the config option ble.ble-passkey-display-reversed-digits-deprecation in your mbed_app.json override section to false. This will then return the passkey in the correct order.") @@ -341,6 +362,10 @@ public: * by supplying the confirmation using the confirmationEntered function. * * @param[in] connectionHandle connection connectionHandle + * + * @see init() + * @see setIoCapability() + * @see confirmationEntered() */ virtual void confirmationRequest(ble::connection_handle_t connectionHandle) { (void)connectionHandle; @@ -352,6 +377,10 @@ public: * proceed by supplying the passkey through the passkeyEntered function. * * @param[in] connectionHandle connection connectionHandle + * + * @see init() + * @see setIoCapability() + * @see passkeyEntered() */ virtual void passkeyRequest(ble::connection_handle_t connectionHandle) { (void)connectionHandle; @@ -360,9 +389,13 @@ public: #if BLE_FEATURE_SECURE_CONNECTIONS /** * Notify the application that a key was pressed by the peer during passkey entry. + * This is only informative to provide feedback to the user. These events will only + * be triggered if you call setKeypressNotification() * * @param[in] connectionHandle connection connectionHandle * @param[in] keypress type of keypress event + * + * @see setKeypressNotification() */ virtual void keypressNotification(ble::connection_handle_t connectionHandle, ble::Keypress_t keypress) { (void)connectionHandle; @@ -371,16 +404,20 @@ public: #endif // BLE_FEATURE_SECURE_CONNECTIONS /** - * Indicate to the application it needs to return legacy pairing OOB to the stack. + * Indicate to the application it needs to return legacy pairing OOB to the stack + * using legacyPairingOobReceived(). * * @param[in] connectionHandle connection connectionHandle + * + * @see legacyPairingOobReceived() */ virtual void legacyPairingOobRequest(ble::connection_handle_t connectionHandle) { (void)connectionHandle; } /** - * Indicate that the application needs to send legacy pairing OOB data to the peer. + * Indicate that the application needs to send legacy pairing OOB data to the peer through + * another communication channel. * * @param[in] address address that will be used in the pairing * @param[in] temporaryKey temporary key to be used in legacy pairing @@ -398,6 +435,8 @@ public: * @param[in] random random number used to generate the confirmation * @param[in] confirm confirmation value to be use for authentication * in secure connections pairing + * + * @see generateOOB() */ virtual void oobGenerated(const ble::address_t *address, const ble::oob_lesc_value_t *random, @@ -418,6 +457,8 @@ public: * @param[in] connectionHandle connection connectionHandle * @param[in] csrk signing key, pointer only valid during call * @param[in] authenticated indicates if the signing key is authenticated + * + * @see getSigningKey() */ virtual void signingKey(ble::connection_handle_t connectionHandle, const ble::csrk_t *csrk, bool authenticated) { (void)connectionHandle; @@ -545,6 +586,8 @@ public: * * @param[in] connectionHandle Handle to identify the connection. * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see EventHandler::pairingResult() */ ble_error_t requestPairing(ble::connection_handle_t connectionHandle); #endif // BLE_ROLE_CENTRAL @@ -556,6 +599,8 @@ public: * * @param[in] connectionHandle Handle to identify the connection. * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see EventHandler::pairingRequest() */ ble_error_t acceptPairingRequest(ble::connection_handle_t connectionHandle); #endif // BLE_ROLE_PERIPHERAL @@ -566,6 +611,8 @@ public: * * @param[in] connectionHandle Handle to identify the connection. * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see EventHandler::pairingRequest() */ ble_error_t cancelPairingRequest(ble::connection_handle_t connectionHandle); @@ -578,6 +625,9 @@ public: * to continue with pairing by calling acceptPairingRequest * or cancelPairingRequest if the user wishes to reject it. * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * + * @see EventHandler::pairingRequest() */ ble_error_t setPairingRequestAuthorisation(bool required = true); @@ -586,6 +636,8 @@ public: * * @param[in] connectionHandle Handle to identify the connection. * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see EventHandler::peerIdentity() */ ble_error_t getPeerIdentity(ble::connection_handle_t connectionHandle); @@ -595,7 +647,7 @@ public: #if BLE_FEATURE_SECURE_CONNECTIONS /** - * Allow of disallow the use of legacy pairing in case the application only wants + * Allow or disallow the use of legacy pairing in case the application only wants * to force the use of Secure Connections. If legacy pairing is disallowed and either * side doesn't support Secure Connections the pairing will fail. * @@ -627,21 +679,29 @@ public: /** * Set the passkey that is displayed on the local device instead of using - * a randomly generated one + * a randomly generated one. This will be used during pairing * * @param[in] passkey ASCII string of 6 digits * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see EventHandler::passkeyRequest() - this will be called on the peer which will have + * to use passkeyEntered() to send this passkey back to us. */ ble_error_t setDisplayPasskey(const Passkey_t passkey); /** * Set the security mode on a connection. Useful for elevating the security mode * once certain conditions are met, e.g., a particular service is found. + * This call is a request for the stack to take appropriate action and may result + * in (re)pairing or encryption. Wait for events in your registered EventHandler. * * @param[in] connectionHandle Handle to identify the connection. * @param[in] securityMode Requested security mode. * * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see EventHandler::linkEncryptionResult() + * @see EventHandler::pairingResult() */ ble_error_t setLinkSecurity(ble::connection_handle_t connectionHandle, SecurityMode_t securityMode); @@ -699,6 +759,8 @@ public: * @param[in] connectionHandle Handle to identify the connection. * @param[in] encryption encryption state requested * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see EventHandler::linkEncryptionResult() */ ble_error_t setLinkEncryption(ble::connection_handle_t connectionHandle, ble::link_encryption_t encryption); @@ -735,6 +797,9 @@ public: * * @param[in] connectionHandle Handle to identify the connection. * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see EventHandler::linkEncryptionResult() + * @see EventHandler::pairingResult() */ ble_error_t requestAuthentication(ble::connection_handle_t connectionHandle); @@ -756,6 +821,8 @@ public: * address will be returned along with the rest of the OOB data when generation * is complete. Using an invalid address is illegal. * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see EventHandler::oobGenerated() */ ble_error_t generateOOB(const ble::address_t *address); @@ -791,6 +858,8 @@ public: * @param[in] connectionHandle Handle to identify the connection. * @param[in] confirmation True value indicates the passkey displayed matches. * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see EventHandler::confirmationRequest() */ ble_error_t confirmationEntered(ble::connection_handle_t connectionHandle, bool confirmation); #endif // BLE_FEATURE_SECURE_CONNECTIONS @@ -801,6 +870,8 @@ public: * @param[in] connectionHandle Handle to identify the connection. * @param[in] passkey ASCII string of digits entered by the user. * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see EventHandler::passkeyRequest() */ ble_error_t passkeyEntered(ble::connection_handle_t connectionHandle, Passkey_t passkey); @@ -812,6 +883,8 @@ public: * @param[in] connectionHandle Handle to identify the connection. * @param[in] keypress Type of keypress event. * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see EventHandler::keypressNotification() - this will be trigger on the peer */ ble_error_t sendKeypressNotification(ble::connection_handle_t connectionHandle, ble::Keypress_t keypress); #endif // BLE_FEATURE_SECURE_CONNECTIONS @@ -822,12 +895,15 @@ public: * @param[in] address address of the peer device this data comes from * @param[in] tk pointer to out of band data received containing the temporary key. * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see legacyPairingOobRequest */ ble_error_t legacyPairingOobReceived(const ble::address_t *address, const ble::oob_tk_t *tk); #if BLE_FEATURE_SECURE_CONNECTIONS /** - * Supply the stack with the OOB data for secure connections. + * Supply the stack with the OOB data for secure connections. This data is generated on the peer + * and is received through another communication channel. * * @param[in] address address of the peer device this data comes from * @param[in] random random number used to generate the confirmation @@ -853,6 +929,8 @@ public: * (provide MITM protection). * * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason. + * + * @see EventHandler::signingKey() */ ble_error_t getSigningKey(ble::connection_handle_t connectionHandle, bool authenticated); #endif // BLE_FEATURE_SIGNING