ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

BLE: Clarify ble event docs with crossreferences
pull/14560/head^2
Martin Kojtal 2021-07-01 17:17:49 +02:00 committed by GitHub
parent d0c446875b 1ba5b25ad9
commit d83494f54b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 125 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
connectivity/FEATURE_BLE/include/ble/Gap.h
View File

@ -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 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
* is managed by the middleware.
* @note This event will only be produced if manageConnectionParametersUpdateRequest() was called
* 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.

2
connectivity/FEATURE_BLE/include/ble/GattClient.h
View File

@ -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,

22
connectivity/FEATURE_BLE/include/ble/GattServer.h
View File

@ -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,

98
connectivity/FEATURE_BLE/include/ble/SecurityManager.h
View File

@ -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() 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