Skip to content

Commit 282740a

Browse files
pan-pan-
committed
BLE: Improve GapAdvertisingParams.h documentation.
1 parent ae7a5ee commit 282740a

File tree

1 file changed

+144
-60
lines changed

1 file changed

+144
-60
lines changed

‎features/FEATURE_BLE/ble/GapAdvertisingParams.h

Lines changed: 144 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -14,48 +14,99 @@
1414
* limitations under the License.
1515
*/
1616

17-
#ifndef __GAP_ADVERTISING_PARAMS_H__
18-
#define __GAP_ADVERTISING_PARAMS_H__
17+
#ifndef MBED_GAP_ADVERTISING_PARAMS_H__
18+
#define MBED_GAP_ADVERTISING_PARAMS_H__
1919

2020
/**
21-
* This class provides a wrapper for the core advertising parameters,
22-
* including the advertising type (Connectable Undirected,
23-
* Non Connectable Undirected and so on), as well as the advertising and
24-
* timeout intervals.
21+
* @addtogroup ble
22+
* @{
23+
* @addtogroup gap
24+
* @{
25+
*/
26+
27+
/**
28+
* Parameters defining the advertising process.
29+
*
30+
* Advertising parameters are a triplet of three value:
31+
* - The Advertising mode which is modeled after AdvertisingType_t. It defines
32+
* if the device is connectable, scanable, ... This value can be set at
33+
* construction time, updated with setAdvertisingType() and queried by
34+
* getAdvertisingType().
35+
* - Time interval between advertisement. It can be set at construction time,
36+
* updated by setInterval() and obtained from getInterval().
37+
* - Duration of the advertising process. As others it can be set at
38+
* construction time, modified by setTimeout() retrieved by getTimeout().
2539
*/
2640
class GapAdvertisingParams {
2741
public:
42+
2843
/**
2944
* Minimum Advertising interval for connectable undirected and connectable
30-
* directed events in 625us units - 20ms.
45+
* directed events in 625us units.
46+
*
47+
* @note Equal to 20 ms.
3148
*/
32-
static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN = 0x0020;
49+
static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN = 0x0020;
50+
3351
/**
3452
* Minimum Advertising interval for scannable and non-connectable
35-
* undirected events in 625us units - 100ms.
53+
* undirected events in 625us units.
54+
*
55+
* @note Equal to 100ms.
3656
*/
3757
static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN_NONCON = 0x00A0;
58+
3859
/**
39-
* Maximum Advertising interval in 625us units - 10.24s.
60+
* Maximum Advertising interval in 625us units.
61+
*
62+
* @note Equal to 10.24s.
4063
*/
41-
static const unsigned GAP_ADV_PARAMS_INTERVAL_MAX = 0x4000;
64+
static const unsigned GAP_ADV_PARAMS_INTERVAL_MAX = 0x4000;
65+
4266
/**
43-
* Maximum advertising timeout seconds.
67+
* Maximum advertising timeout allowed; in seconds.
4468
*/
45-
static const unsigned GAP_ADV_PARAMS_TIMEOUT_MAX = 0x3FFF;
69+
static const unsigned GAP_ADV_PARAMS_TIMEOUT_MAX = 0x3FFF;
4670

4771
/**
48-
* Encapsulates the peripheral advertising modes, which determine how
49-
* the device appears to other central devices in hearing range.
72+
* Encapsulates the peripheral advertising modes.
73+
*
74+
* It determine how the device appears to other scanner and peripheral
75+
* devices in the scanning range.
5076
*/
5177
enum AdvertisingType_t {
52-
ADV_CONNECTABLE_UNDIRECTED, /**< Vol 3, Part C, Section 9.3.4 and Vol 6, Part B, Section 2.3.1.1. */
53-
ADV_CONNECTABLE_DIRECTED, /**< Vol 3, Part C, Section 9.3.3 and Vol 6, Part B, Section 2.3.1.2. */
54-
ADV_SCANNABLE_UNDIRECTED, /**< Include support for Scan Response payloads, see Vol 6, Part B, Section 2.3.1.4. */
55-
ADV_NON_CONNECTABLE_UNDIRECTED /**< Vol 3, Part C, Section 9.3.2 and Vol 6, Part B, Section 2.3.1.3. */
78+
/**
79+
* Device is connectable, scannable and doesn't expect connection from a
80+
* specific peer.
81+
*
82+
* @see Vol 3, Part C, Section 9.3.4 and Vol 6, Part B, Section 2.3.1.1.
83+
*/
84+
ADV_CONNECTABLE_UNDIRECTED,
85+
86+
/**
87+
* Device is connectable and expect connection from a specific peer.
88+
*
89+
* @see Vol 3, Part C, Section 9.3.3 and Vol 6, Part B, Section 2.3.1.2.
90+
*/
91+
ADV_CONNECTABLE_DIRECTED,
92+
93+
/**
94+
* Device is scannable but not connectable.
95+
*
96+
* @see Vol 6, Part B, Section 2.3.1.4.
97+
*/
98+
ADV_SCANNABLE_UNDIRECTED,
99+
100+
/**
101+
* Device is not connectable and not scannable.
102+
*
103+
* @see Vol 3, Part C, Section 9.3.2 and Vol 6, Part B, Section 2.3.1.3.
104+
*/
105+
ADV_NON_CONNECTABLE_UNDIRECTED
56106
};
107+
57108
/**
58-
* Type alias for GapAdvertisingParams::AdvertisingType_t.
109+
* Alias for GapAdvertisingParams::AdvertisingType_t.
59110
*
60111
* @deprecated This type alias will be dropped in future releases.
61112
*/
@@ -65,18 +116,23 @@ class GapAdvertisingParams {
65116
/**
66117
* Construct an instance of GapAdvertisingParams.
67118
*
68-
* @param[in] advType
69-
* Type of advertising. Default is
70-
* GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED.
71-
* @param[in] interval
72-
* Advertising interval in units of 0.625ms. Default is
73-
* GapAdvertisingParams::GAP_ADV_PARAMS_INTERVAL_MIN_NONCON.
74-
* @param[in] timeout
75-
* Advertising timeout. Default is 0.
76-
*/
77-
GapAdvertisingParams(AdvertisingType_t advType = ADV_CONNECTABLE_UNDIRECTED,
78-
uint16_t interval = GAP_ADV_PARAMS_INTERVAL_MIN_NONCON,
79-
uint16_t timeout = 0) : _advType(advType), _interval(interval), _timeout(timeout) {
119+
* @param[in] advType Type of advertising.
120+
* @param[in] interval Time interval between two advertisement in units of
121+
* 0.625ms.
122+
* @param[in] timeout Duration in seconds of the advertising process. A
123+
* value of 0 indicate that there is no timeout of the advertising process.
124+
*
125+
* @note If value in input are out of range they will be normalized.
126+
*/
127+
GapAdvertisingParams(
128+
AdvertisingType_t advType = ADV_CONNECTABLE_UNDIRECTED,
129+
uint16_t interval = GAP_ADV_PARAMS_INTERVAL_MIN_NONCON,
130+
uint16_t timeout = 0
131+
) :
132+
_advType(advType),
133+
_interval(interval),
134+
_timeout(timeout)
135+
{
80136
/* Interval checks. */
81137
if (_advType == ADV_CONNECTABLE_DIRECTED) {
82138
/* Interval must be 0 in directed connectable mode. */
@@ -108,27 +164,32 @@ class GapAdvertisingParams {
108164
}
109165
}
110166

111-
static const uint16_t UNIT_0_625_MS = 625; /**< Number of microseconds in 0.625 milliseconds. */
167+
/**
168+
* Number of microseconds in 0.625 milliseconds.
169+
*/
170+
static const uint16_t UNIT_0_625_MS = 625;
171+
112172
/**
113173
* Convert milliseconds to units of 0.625ms.
114174
*
115-
* @param[in] durationInMillis
116-
* The number of milliseconds to convert.
175+
* @param[in] durationInMillis Number of milliseconds to convert.
117176
*
118177
* @return The value of @p durationInMillis in units of 0.625ms.
119178
*/
120-
static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis) {
179+
static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis)
180+
{
121181
return (durationInMillis * 1000) / UNIT_0_625_MS;
122182
}
183+
123184
/**
124185
* Convert units of 0.625ms to milliseconds.
125186
*
126-
* @param[in] gapUnits
127-
* The number of units of 0.625ms to convert.
187+
* @param[in] gapUnits The number of units of 0.625ms to convert.
128188
*
129189
* @return The value of @p gapUnits in milliseconds.
130190
*/
131-
static uint16_t ADVERTISEMENT_DURATION_UNITS_TO_MS(uint16_t gapUnits) {
191+
static uint16_t ADVERTISEMENT_DURATION_UNITS_TO_MS(uint16_t gapUnits)
192+
{
132193
return (gapUnits * UNIT_0_625_MS) / 1000;
133194
}
134195

@@ -137,7 +198,8 @@ class GapAdvertisingParams {
137198
*
138199
* @return The advertising type.
139200
*/
140-
AdvertisingType_t getAdvertisingType(void) const {
201+
AdvertisingType_t getAdvertisingType(void) const
202+
{
141203
return _advType;
142204
}
143205

@@ -146,16 +208,19 @@ class GapAdvertisingParams {
146208
*
147209
* @return The advertisement interval (in milliseconds).
148210
*/
149-
uint16_t getInterval(void) const {
211+
uint16_t getInterval(void) const
212+
{
150213
return ADVERTISEMENT_DURATION_UNITS_TO_MS(_interval);
151214
}
152215

153216
/**
154217
* Get the advertisement interval in units of 0.625ms.
155218
*
156-
* @return The advertisement interval in advertisement duration units (0.625ms units).
219+
* @return The advertisement interval in advertisement duration units
220+
* (0.625ms units).
157221
*/
158-
uint16_t getIntervalInADVUnits(void) const {
222+
uint16_t getIntervalInADVUnits(void) const
223+
{
159224
return _interval;
160225
}
161226

@@ -164,44 +229,63 @@ class GapAdvertisingParams {
164229
*
165230
* @return The advertising timeout (in seconds).
166231
*/
167-
uint16_t getTimeout(void) const {
232+
uint16_t getTimeout(void) const
233+
{
168234
return _timeout;
169235
}
170236

171237
/**
172-
* Set the advertising type.
238+
* Update the advertising type.
173239
*
174-
* @param[in] newAdvType
175-
* The new advertising type.
240+
* @param[in] newAdvType The new advertising type.
176241
*/
177-
void setAdvertisingType(AdvertisingType_t newAdvType) {
242+
void setAdvertisingType(AdvertisingType_t newAdvType)
243+
{
178244
_advType = newAdvType;
179245
}
180246

181247
/**
182-
* Set the advertising interval in milliseconds.
248+
* Update the advertising interval in milliseconds.
183249
*
184-
* @param[in] newInterval
185-
* The new advertising interval in milliseconds.
250+
* @param[in] newInterval The new advertising interval in milliseconds.
186251
*/
187-
void setInterval(uint16_t newInterval) {
252+
void setInterval(uint16_t newInterval)
253+
{
188254
_interval = MSEC_TO_ADVERTISEMENT_DURATION_UNITS(newInterval);
189255
}
190256

191257
/**
192-
* Set the advertising timeout.
258+
* Update the advertising timeout.
193259
*
194-
* @param[in] newTimeout
195-
* The new advertising timeout (in seconds).
260+
* @param[in] newTimeout The new advertising timeout (in seconds).
261+
*
262+
* @note 0 is a special value meaning the advertising process never ends.
196263
*/
197-
void setTimeout(uint16_t newTimeout) {
264+
void setTimeout(uint16_t newTimeout)
265+
{
198266
_timeout = newTimeout;
199267
}
200268

201269
private:
202-
AdvertisingType_t _advType; /**< The advertising type. */
203-
uint16_t _interval; /**< The advertising interval in ADV duration units (i.e. 0.625ms). */
204-
uint16_t _timeout; /**< The advertising timeout in seconds. */
270+
/**
271+
* The advertising type.
272+
*/
273+
AdvertisingType_t _advType;
274+
275+
/**
276+
* The advertising interval in ADV duration units (i.e. 0.625ms).
277+
*/
278+
uint16_t _interval;
279+
280+
/**
281+
* The advertising timeout in seconds.
282+
*/
283+
uint16_t _timeout;
205284
};
206285

207-
#endif /* ifndef __GAP_ADVERTISING_PARAMS_H__ */
286+
/**
287+
* @}
288+
* @}
289+
*/
290+
291+
#endif /* ifndef MBED_GAP_ADVERTISING_PARAMS_H__ */

0 commit comments

Comments
 (0)