From 430777e20b1f8061fcbb51c50c755b6e158ff71a Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Fri, 23 Nov 2018 11:23:56 +0000 Subject: [PATCH] BLE: Update documentation of Gap::Events. --- features/FEATURE_BLE/ble/gap/Events.h | 94 ++++++++++++++++++++++++--- 1 file changed, 85 insertions(+), 9 deletions(-) diff --git a/features/FEATURE_BLE/ble/gap/Events.h b/features/FEATURE_BLE/ble/gap/Events.h index 2b7a8cfbc2..45205c6aa7 100644 --- a/features/FEATURE_BLE/ble/gap/Events.h +++ b/features/FEATURE_BLE/ble/gap/Events.h @@ -23,8 +23,11 @@ namespace ble { -/** Event generated when an advertising packet is seen during passive scanning - * or a scan response is received during active scanning. +/** + * Event generated when an advertising packet is seen during passive scanning + * or a scan response is received during active scanning. + * + * @see ble::Gap::EventHandler::onPeriodicAdvertisingReport() */ struct AdvertisingReportEvent { /** Create a advertising report event. @@ -156,7 +159,10 @@ private: mbed::Span advertisingData; }; -/** Event generated when a connection initiation end (successfully or not). +/** + * Event generated when a connection initiation end (successfully or not). + * + * @see ble::Gap::EventHandler::onConnectionComplete(). */ struct ConnectionCompleteEvent { /** Create a connection complete event. @@ -278,7 +284,10 @@ private: uint16_t masterClockAccuracy; }; -/** Event generated when we first receive a periodic advertisement. +/** + * Event generated when we first receive a periodic advertisement. + * + * @see ble::Gap::EventHandler::onPeriodicAdvertisingSyncEstablished(). */ struct PeriodicAdvertisingSyncEstablishedEvent { /** Create advertising sync event. @@ -370,7 +379,10 @@ private: clock_accuracy_t peerClockAccuracy; }; -/** Event generated when periodic advertising packet is received. +/** + * Event generated when periodic advertising packet is received. + * + * @see ble::Gap::EventHandler::onPeriodicAdvertisingReport(). */ struct PeriodicAdvertisingReportEvent { /** Create periodic advertising report event. @@ -432,7 +444,10 @@ private: mbed::Span payload; }; -/** Event generated when periodic advertising sync is lost. +/** + * Event generated when periodic advertising sync is lost. + * + * @see ble::Gap::EventHandler::onPeriodicAdvertisingSyncLoss(). */ struct PeriodicAdvertisingSyncLoss { /** Create periodic advertising sync loss event. @@ -454,11 +469,17 @@ private: periodic_sync_handle_t syncHandle; }; -/** Event generated when scan times out. +/** + * Event generated when scan times out. + * + * @see ble::Gap::EventHandler::onScanTimeout(). */ struct ScanTimeoutEvent { }; -/** Event produced when advertising ends. +/** + * Event produced when advertising ends. + * + * @see ble::Gap::EventHandler::onAdvertisingEnd(). */ struct AdvertisingEndEvent_t { /** Create advertising end event. @@ -510,7 +531,10 @@ private: bool connected; }; -/** Event produced when a peer requests a scan response from the advertiser. +/** + * Event produced when a peer requests a scan response from the advertiser. + * + * @see ble::Gap::EventHandler::onScanRequestReceived(). */ struct ScanRequestEvent_t { /** Create scan request event. @@ -552,17 +576,28 @@ private: const address_t &peerAddress; }; +/** + * Event produced when a disconnection is complete. + * + * @see ble::Gap::EventHandler::onDisconnectionComplete(). + */ struct DisconnectionEvent { DisconnectionEvent( connection_handle_t connectionHandle, const disconnection_reason_t &reason ) : connectionHandle(connectionHandle), reason(reason) { } + /** + * Get the handle of the connection that has expired. + */ connection_handle_t getConnectionHandle() const { return connectionHandle; } + /** + * Get the reason of the disconnection. + */ const disconnection_reason_t &getReason() const { return reason; @@ -573,6 +608,11 @@ private: ble::disconnection_reason_t reason; }; +/** + * Event received when a peer wants to change the connection parameters. + * + * @see ble::Gap::EventHandler::onUpdateConnectionParametersRequest(). + */ struct UpdateConnectionParametersRequestEvent { UpdateConnectionParametersRequestEvent( connection_handle_t connectionHandle, @@ -588,26 +628,41 @@ struct UpdateConnectionParametersRequestEvent { supervisionTimeout(supervision_timeout) { } + /** + * Get the connection handle. + */ connection_handle_t getConnectionHandle() const { return connectionHandle; } + /** + * Get the minimum connection interval requested. + */ const conn_interval_t &getMinConnectionInterval() const { return minConnectionInterval; } + /** + * Get the maximum connection interval requested. + */ const conn_interval_t &getMaxConnectionInterval() const { return maxConnectionInterval; } + /** + * Get the slave latency requested. + */ const slave_latency_t &getSlaveLatency() const { return slaveLatency; } + /** + * Get the supervision timeout requested. + */ const supervision_timeout_t &getSupervisionTimeout() const { return supervisionTimeout; @@ -621,6 +676,11 @@ private: ble::supervision_timeout_t supervisionTimeout; }; +/** + * Event received when connection parameters have been updated. + * + * @see ble::Gap::EventHandler::onConnectionParametersUpdateComplete(). + */ struct ConnectionParametersUpdateCompleteEvent { ConnectionParametersUpdateCompleteEvent( ble_error_t status, @@ -636,26 +696,42 @@ struct ConnectionParametersUpdateCompleteEvent { supervisionTimeout(supervisionTimeout) { } + /** + * Get The status of the operation. It is equal to BLE_ERROR_NONE in case of + * success. + */ ble_error_t getStatus() const { return status; } + /** + * Get the handle of the connection that has been updated. + */ connection_handle_t getConnectionHandle() const { return connectionHandle; } + /** + * Get the new connection interval. + */ const conn_interval_t &getConnectionInterval() const { return connectionInterval; } + /** + * Get the new slave latency. + */ const slave_latency_t &getSlaveLatency() const { return slaveLatency; } + /** + * Get the new supervision timeout. + */ const supervision_timeout_t &getSupervisionTimeout() const { return supervisionTimeout;