Merge pull request #14820 from paul-szczepanek-arm/events-doc

BLE: Clarify ble event docs with crossreferences

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
+         * Called when connection attempt ends. Check event.getStatus() to see if connection
-         * connected.
+         * was established. If this device is the peripheral and it was advertising this will
+         * end the advertising set 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
+         * @note This event will only be produced if manageConnectionParametersUpdateRequest() was called
-         * is managed by the middleware.
+         * with true. 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()
         {
@@ -1087,6 +1093,7 @@ public:
      * @see EventHandler::onUpdateConnectionParametersRequest when a central
      * receives a request to update the connection parameters.
      *
+     * @see onUpdateConnectionParametersRequest
      * @see acceptConnectionParametersUpdate to accept the request.
      * @see rejectConnectionParametersUpdate to reject the request.
      */
@@ -1286,6 +1293,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 +1442,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.

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,

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,

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
+         * Called when a pairing request is received. Application should respond by
-         * calling the appropriate function: acceptPairingRequest or cancelPairingRequest
+         * calling the appropriate function: acceptPairingRequest() or cancelPairingRequest().
+         * This event will only trigger if setPairingRequestAuthorisation() was called with true.
+         * 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,9 @@ public:
          *
          * @param[in] connectionHandle connection connectionHandle
          * @param[in] result result of the pairing indicating success or reason for failure
+         *
+         * @see acceptPairingRequest()
+         * @see requestPairing()
          */
         virtual void pairingResult(ble::connection_handle_t connectionHandle, SecurityCompletionStatus_t result) {
             (void)connectionHandle;
@@ -277,6 +287,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 +306,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 +318,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 +337,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 +363,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 +378,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 +390,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 +405,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 +436,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 +458,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 +587,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 +600,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 +612,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 +626,10 @@ 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()
+     * @see EventHandler::acceptPairingRequest()
+     * @see EventHandler::cancelPairingRequest()
      */
     ble_error_t setPairingRequestAuthorisation(bool required = true);
 
@@ -586,6 +638,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 +649,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 +681,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 +761,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 +799,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 +823,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 +860,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 +872,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 +885,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 +897,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 +931,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