Mistake on this page?
Report an issue in GitHub or email us
Gap.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2020 ARM Limited
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 
19 #ifndef BLE_GAP_GAP_H
20 #define BLE_GAP_GAP_H
21 
22 #include "CallChainOfFunctionPointersWithContext.h"
23 
24 #include <algorithm>
25 
26 #include "drivers/LowPowerTimeout.h"
27 #include "drivers/LowPowerTicker.h"
28 #include "platform/mbed_error.h"
29 
30 #include "ble/common/ble/BLERoles.h"
31 #include "ble/common/ble/BLETypes.h"
32 #include "ble/common/ble/gap/AdvertisingDataBuilder.h"
33 #include "ble/common/ble/gap/AdvertisingDataParser.h"
34 #include "ble/common/ble/gap/AdvertisingDataSimpleBuilder.h"
35 #include "ble/common/ble/gap/AdvertisingDataTypes.h"
36 #include "ble/common/ble/gap/AdvertisingParameters.h"
37 #include "ble/common/ble/gap/ConnectionParameters.h"
38 #include "ble/common/ble/gap/Events.h"
39 #include "ble/common/ble/gap/ScanParameters.h"
40 #include "ble/common/ble/gap/Types.h"
41 
42 namespace ble {
43 class PalGenericAccessService;
44 
45 /**
46  * @addtogroup ble
47  * @{
48  * @addtogroup gap
49  * @{
50  */
51 
52 /**
53  * Define device discovery, connection and link management procedures.
54  *
55  * - Device discovery: A device can advertise to nearby peers its existence,
56  * identity and capabilities. Similarly, a device can scan its environment to
57  * find advertising peers. The information acquired during the scan helps to
58  * identify peers and understand their use. A scanner may acquire more information
59  * about an advertising peer by sending a scan request. If the peer accepts scan
60  * requests, it may reply with additional information about its state.
61  *
62  * - Connection: A bluetooth device can establish a connection to a connectable
63  * advertising peer. Once the connection is established, both devices can
64  * communicate using the GATT protocol. The GATT protocol allows connected
65  * devices to expose a set of states that the other peer can discover, read and write.
66  *
67  * - Link Management: Connected devices may drop the connection and may adjust
68  * connection parameters according to the power envelop needed for their
69  * application.
70  *
71  * @par Accessing gap
72  *
73  * Instance of a Gap class for a given BLE device should be accessed using
74  * BLE::gap(). The reference returned remains valid until the BLE instance
75  * shut down (see BLE::shutdown()).
76  *
77  * @code
78  * // assuming ble_device has been initialized
79  * BLE& ble_device;
80  *
81  * ble::Gap& gap = ble_device.gap();
82  * @endcode
83  *
84  * @par Advertising
85  *
86  * Advertising consists of broadcasting at a regular interval a small amount of
87  * data containing valuable information about the device. These packets may be
88  * scanned by peer devices listening on BLE advertising channels.
89  *
90  * Scanners may also request additional information from a device advertising by
91  * sending a scan request. If the broadcaster accepts scan requests, it can reply
92  * with a scan response packet containing additional information.
93  *
94  * Advertising parameters are updated using setAdvertisingParams(). The main
95  * advertising payload is updated using setAdvertisingPayload(), and the scan response
96  * is updated using setAdvertisingScanResponse(). If the advertising is already
97  * updated, the data will take effect from the next advertising event.
98  *
99  * To create a valid advertising payload and scan response, you may use
100  * AdvertisingDataBuilder. You must first allocate memory and create an mbed::Span and
101  * pass that into the AdvertisingDataBuilder, which will only be able to add as much
102  * data as fits in the provided buffer. The builder accepts any size of the buffer,
103  * but for the created data to be usable, it must be smaller than the maximum data
104  * length returned from getMaxAdvertisingDataLength().
105  *
106  * Another option is to use AdvertisingDataSimpleBuilder, which allocates memory
107  * on the stack and offers a fluent interface at the expense of a reduced set of
108  * APIs and error management options.
109  *
110  * @note Prior to Bluetooth 5, advertising and scanning payload size were limited
111  * to LEGACY_ADVERTISING_MAX_SIZE. It changed with Bluetooth 5, and now the maximum
112  * size of data that can be advertised depends on the controller. If you wish
113  * to be compatible with older devices, you may wish to advertise with the
114  * LEGACY_ADVERTISING_HANDLE. This uses payloads no larger than LEGACY_ADVERTISING_MAX_SIZE
115  * with that advertising set.
116  *
117  * @par Extended advertising
118  *
119  * Extended advertising allows for a wider choice of options than legacy advertising.
120  * You can send bigger payloads and use different PHYs. This allows for bigger throughput
121  * or longer range.
122  *
123  * Extended advertising may be split across many packets and takes place on both the
124  * regular advertising channels and the rest of the 37 channels normally used by
125  * connected devices.
126  *
127  * The 3 channels used in legacy advertising are called primary advertisement channels.
128  * The remaining 37 channels are used for secondary advertising. Unlike sending data
129  * during a connection, this allows the device to broadcast data to multiple devices.
130  *
131  * The advertising starts on the primary channels (which you may select) and continues
132  * on the secondary channels as indicated in the packet sent on the primary channel.
133  * This way, the advertising can send large payloads without saturating the advertising
134  * channels. Primary channels are limited to 1M and coded PHYs, but secondary channels
135  * may use the increased throughput 2M PHY.
136  *
137  * @par Periodic advertising
138  *
139  * Similarly, you can use periodic advertising to transfer regular data to multiple
140  * devices.
141  *
142  * The advertiser uses primary channels to advertise the information needed to
143  * listen to the periodic advertisements on secondary channels. This sync information
144  * will be used by the scanner who can now optimize for power consumption and only
145  * listen for the periodic advertisements at specified times.
146  *
147  * Like extended advertising, periodic advertising offers extra PHY options of 2M
148  * and coded. The payload may be updated at any time and will be updated on the next
149  * advertisement event when the periodic advertising is active.
150  *
151  * @par Advertising sets
152  *
153  * Advertisers may advertise multiple payloads at the same time. The configuration
154  * and identification of these is done through advertising sets. Use a handle
155  * obtained from createAvertisingSet() for advertising operations. After ending
156  * all advertising operations, remove the handle from the system using
157  * destroyAdvertisingHandle().
158  *
159  * Extended advertising and periodic advertising is an optional feature, and not all
160  * devices support it. Some will only be able to see the now-called legacy advertising.
161  *
162  * Legacy advertising is available through a special handle, LEGACY_ADVERTISING_HANDLE.
163  * This handle is always available, doesn't need to be created and can't be
164  * destroyed.
165  *
166  * There is a limited number of advertising sets available because they require support
167  * from the controller. Their availability is dynamic and may be queried at any time
168  * using getMaxAdvertisingSetNumber(). Advertising sets take up resources even if
169  * they are not actively advertising right now, so it's important to destroy the set
170  * when you're done with it (or reuse it in the next advertisement).
171  *
172  * Periodic advertising and extended advertising share the same set but not the same
173  * data. Extended advertising carries out periodic advertising synchronization
174  * information. Therefore, to let other devices be aware that your device
175  * exposes periodic advertising, you should start extended advertising of the set.
176  * Subsequently, you may disable extended advertising, and the periodic advertising
177  * will continue. If you start periodic advertising while extended advertising is
178  * inactive, periodic advertising won't start until you start extended advertising
179  * at a later time.
180  *
181  * @par Privacy
182  *
183  * Privacy is a feature that allows a device to avoid being tracked by other
184  * (untrusted) devices. The device achieves it by periodically generating a
185  * new random address. The random address may be a resolvable random address,
186  * enabling trusted devices to recognize it as belonging to the same
187  * device. These trusted devices receive an Identity Resolution Key (IRK)
188  * during pairing. This is handled by the SecurityManager and relies on the
189  * other device accepting and storing the IRK.
190  *
191  * You need to enable privacy by calling enablePrivacy() after having
192  * initialized the SecurityManager because privacy requires SecurityManager
193  * to handle IRKs. The behavior of privacy enabled devices is set by
194  * using setCentralPrivacyConfiguration(), which specifies what the device
195  * should be with devices using random addresses. Random addresses
196  * generated by privacy enabled devices can be of two types: resolvable
197  * (by devices who have the IRK) and unresolvable. Unresolvable addresses
198  * can't be used for connecting and connectable advertising. Therefore, a
199  * resolvable one will be used for these regardless of the privacy
200  * configuration.
201  *
202  * @par Scanning
203  *
204  * Scanning consists of listening for peer advertising packets. From a scan, a
205  * device can identify devices available in its environment.
206  *
207  * If the device scans actively, then it will send scan request to scannable
208  * advertisers and collect their scan responses.
209  *
210  * Scanning is done by creating ScanParameters and applying them with
211  * setScanParameters(). One configured, you may call startScan().
212  *
213  * When a scanning device receives an advertising packet, it will call
214  * onAdvertisingReport() in the registered event handler. A whitelist may be used
215  * to limit the advertising reports by setting the correct policy in the scan
216  * parameters.
217  *
218  * @par Connection event handling
219  *
220  * A peer may connect device advertising connectable packets. The advertising
221  * procedure ends as soon as the device is connected. If an advertising timeout
222  * has been set in the advertising parameters then onAdvertisingEnd will be called
223  * in the registered eventHandler when it runs out.
224  *
225  * A device accepting a connection request from a peer is named a peripheral,
226  * and the device initiating the connection is named a central.
227  *
228  * Connection is initiated by central devices. A call to connect() will result in
229  * the device scanning on any PHYs set in ConectionParamters passed in.
230  *
231  * Peripheral and central receive a connection event when the connection is
232  * effective. If successful will result in a call to onConnectionComplete in the
233  * EventHandler registered with the Gap.
234  *
235  * It the connection attempt fails it will result in onConnectionComplete called
236  * on the central device with the event carrying the error flag.
237  *
238  * @par Changing the PHYsical transport of a connection
239  *
240  * Once a connection has been established, it is possible to change the physical
241  * transport used between the local and the distant device. Changing the transport
242  * can either increase the bandwidth or increase the communication range.
243  * An increased bandwidth equals a better power consumption but also a loss in
244  * sensibility and therefore a degraded range.
245  *
246  * Symmetrically an increased range means a lowered bandwidth and a degraded power
247  * consumption.
248  *
249  * Applications can change the PHY used by calling the function setPhy. Once the
250  * update has been made the result is forwarded to the application by calling the
251  * function onPhyUpdateComplete of the event handler registered.
252  *
253  * @par disconnection
254  *
255  * The application code initiates a disconnection when it calls the
256  * disconnect(Handle_t, DisconnectionReason_t) function.
257  *
258  * Disconnection may also be initiated by the remote peer or the local
259  * controller/stack. To catch all disconnection events, application code may
260  * set up an handler taking care of disconnection events by calling
261  * onDisconnection().
262  *
263  * @par Modulation Schemes
264  *
265  * When supported by the host and controller you can select different modulation
266  * schemes (@see BLUETOOTH SPECIFICATION Version 5.0 | Vol 1, Part A - 1.2):
267  * - LE 1M PHY
268  * - LE 2M PHY
269  * - LE coded PHY
270  *
271  * You may set preferred PHYs (separately for RX and TX) using setPreferredPhys().
272  * You may also set the currently used PHYs on a selected connection using setPhy().
273  * Both of these settings are only advisory and the controller is allowed to make
274  * its own decision on the best PHY to use based on your request, the peer's
275  * supported features and the connection's physical conditions.
276  *
277  * You may query the currently used PHY using readPhy() which will return the
278  * result through a call to the registered event handler. You may register the
279  * handler with setEventHandler(). The events inform about the currently used
280  * PHY and of any changes to PHYs which may be triggered autonomously by the
281  * controller or by the peer.
282  */
283 #if !defined(DOXYGEN_ONLY)
284 namespace interface {
285 #endif // !defined(DOXYGEN_ONLY)
286 class Gap {
287 public:
288  /**
289  * Gap shutdown event handler.
290  *
291  * @see Gap::onShutdown().
292  */
294 
295  /**
296  * Callchain of gap shutdown event handler.
297  *
298  * @see Gap::onShutdown().
299  */
302 
303 public:
304  /**
305  * Definition of the general handler of Gap related events.
306  */
307  struct EventHandler {
308  /**
309  * Called when an advertising device receive a scan response.
310  *
311  * @param event Scan request event.
312  *
313  * @version: 5+.
314  *
315  * @see AdvertisingParameters::setScanRequestNotification().
316  */
317  virtual void onScanRequestReceived(const ScanRequestEvent &event)
318  {
319  }
320 
321  /**
322  * Called when advertising ends.
323  *
324  * Advertising ends when the process timeout or if it is stopped by the
325  * application or if the local device accepts a connection request.
326  *
327  * @param event Advertising end event.
328  *
329  * @see startAdvertising()
330  * @see stopAdvertising()
331  * @see onConnectionComplete()
332  */
333  virtual void onAdvertisingEnd(const AdvertisingEndEvent &event)
334  {
335  }
336 
337  /**
338  * Called when a scanner receives an advertising or a scan response packet.
339  *
340  * @param event Advertising report.
341  *
342  * @see startScan()
343  */
344  virtual void onAdvertisingReport(const AdvertisingReportEvent &event)
345  {
346  }
347 
348  /**
349  * Called when scan times out.
350  *
351  * @param event Associated event.
352  *
353  * @see startScan()
354  */
355  virtual void onScanTimeout(const ScanTimeoutEvent &event)
356  {
357  }
358 
359  /**
360  * Called when first advertising packet in periodic advertising is received.
361  *
362  * @param event Periodic advertising sync event.
363  *
364  * @version: 5+.
365  *
366  * @see createSync()
367  */
370  )
371  {
372  }
373 
374  /**
375  * Called when a periodic advertising packet is received.
376  *
377  * @param event Periodic advertisement event.
378  *
379  * @version: 5+.
380  *
381  * @see createSync()
382  */
384  const PeriodicAdvertisingReportEvent &event
385  )
386  {
387  }
388 
389  /**
390  * Called when a periodic advertising sync has been lost.
391  *
392  * @param event Details of the event.
393  *
394  * @version: 5+.
395  *
396  * @see createSync()
397  */
399  const PeriodicAdvertisingSyncLoss &event
400  )
401  {
402  }
403 
404  /**
405  * Called when connection attempt ends or an advertising device has been
406  * connected.
407  *
408  * @see startAdvertising()
409  * @see connect()
410  *
411  * @param event Connection event.
412  */
414  {
415  }
416 
417  /**
418  * Called when the peer request connection parameters updates.
419  *
420  * Application must accept the update with acceptConnectionParametersUpdate()
421  * or reject it with rejectConnectionParametersUpdate().
422  *
423  * @param event The connection parameters requested by the peer.
424  *
425  * @version 4.1+.
426  *
427  * @note This event is not generated if connection parameters update
428  * is managed by the middleware.
429  *
430  * @see manageConnectionParametersUpdateRequest()
431  * @see acceptConnectionParametersUpdate()
432  * @see rejectConnectionParametersUpdate()
433  */
436  )
437  {
438  }
439 
440  /**
441  * Called when connection parameters have been updated.
442  *
443  * @param event The new connection parameters.
444  *
445  * @see updateConnectionParameters()
446  * @see acceptConnectionParametersUpdate()
447  */
450  )
451  {
452  }
453 
454  /**
455  * Called when a connection has been disconnected.
456  *
457  * @param event Details of the event.
458  *
459  * @see disconnect()
460  */
462  {
463  }
464 
465  /**
466  * Function invoked when the current transmitter and receiver PHY have
467  * been read for a given connection.
468  *
469  * @param status Status of the operation: BLE_ERROR_NONE in case of
470  * success or an appropriate error code.
471  *
472  * @param connectionHandle: The handle of the connection for which the
473  * PHYs have been read.
474  *
475  * @param txPhy PHY used by the transmitter.
476  *
477  * @param rxPhy PHY used by the receiver.
478  *
479  * @see readPhy().
480  *
481  * @version: 5+.
482  */
483  virtual void onReadPhy(
484  ble_error_t status,
485  connection_handle_t connectionHandle,
486  phy_t txPhy,
487  phy_t rxPhy
488  )
489  {
490  }
491 
492  /**
493  * Function invoked when the update process of the PHY has been completed.
494  *
495  * The process can be initiated by a call to the function setPhy, the
496  * local bluetooth subsystem or the peer.
497  *
498  * @param status Status of the operation: BLE_ERROR_NONE in case of
499  * success or an appropriate error code.
500  *
501  * @param connectionHandle: The handle of the connection on which the
502  * operation was made.
503  *
504  * @param txPhy PHY used by the transmitter.
505  *
506  * @param rxPhy PHY used by the receiver.
507  *
508  * @note Success doesn't mean the PHY has been updated it means both
509  * ends have negotiated the best PHY according to their configuration and
510  * capabilities. The PHY currently used are present in the txPhy and
511  * rxPhy parameters.
512  *
513  * @see setPhy()
514  *
515  * @version: 5+.
516  */
517  virtual void onPhyUpdateComplete(
518  ble_error_t status,
519  connection_handle_t connectionHandle,
520  phy_t txPhy,
521  phy_t rxPhy
522  )
523  {
524  }
525 
526  /**
527  * Function invoked when the connections changes the maximum number of octets
528  * that can be sent or received by the controller in a single packet. A single
529  * L2CAP packet can be fragmented across many such packets.
530  *
531  * @note This only triggers if controller supports data length extension and
532  * negotiated data length is longer than the default 23.
533  *
534  * @param connectionHandle The handle of the connection that changed the size.
535  * @param txSize Number of octets we can send on this connection in a single packet.
536  * @param rxSize Number of octets we can receive on this connection in a single packet.
537  */
538  virtual void onDataLengthChange(
539  connection_handle_t connectionHandle,
540  uint16_t txSize,
541  uint16_t rxSize
542  )
543  {
544  }
545  protected:
546  /**
547  * Prevent polymorphic deletion and avoid unnecessary virtual destructor
548  * as the Gap class will never delete the instance it contains.
549  */
551  {
552  }
553  };
554 
555  /**
556  * Preferred connection parameter display in Generic Access Service.
557  */
558  typedef struct {
559  /**
560  * Minimum interval between two connection events allowed for a
561  * connection.
562  *
563  * It shall be less than or equal to maxConnectionInterval. This value,
564  * in units of 1.25ms, is included in the range [0x0006 : 0x0C80].
565  */
567 
568  /**
569  * Maximum interval between two connection events allowed for a
570  * connection.
571  *
572  * It shall be greater than or equal to minConnectionInterval. This
573  * value is in unit of 1.25ms and is in the range [0x0006 : 0x0C80].
574  */
576 
577  /**
578  * Number of connection events the slave can drop if it has nothing to
579  * communicate to the master.
580  *
581  * This value shall be in the range [0x0000 : 0x01F3].
582  */
583  uint16_t slaveLatency;
584 
585  /**
586  * Link supervision timeout for the connection.
587  *
588  * Time after which the connection is considered lost if the device
589  * didn't receive a packet from its peer.
590  *
591  * It is larger than:
592  * (1 + slaveLatency) * maxConnectionInterval * 2
593  *
594  * This value is in the range [0x000A : 0x0C80] and is in unit of
595  * 10 ms.
596  *
597  * @note maxConnectionInterval is in ms in the formulae above.
598  */
601 
602  /**
603  * Assign the event handler implementation that will be used by the gap
604  * module to signal events back to the application.
605  *
606  * @param handler Application implementation of an EventHandler.
607  */
608  void setEventHandler(EventHandler *handler);
609 
610  /** Check controller support for a specific feature.
611  *
612  * @param feature Feature to check.
613  * @return True if feature is supported.
614  */
615  bool isFeatureSupported(controller_supported_features_t feature);
616 
617  /* advertising */
618 #if BLE_ROLE_BROADCASTER
619  /** Return currently available number of supported advertising sets.
620  * This may change at runtime.
621  *
622  * @note Devices that do not support Bluetooth 5 still offers one advertising
623  * set that has the handle LEGACY_ADVERTISING_HANDLE.
624  *
625  * @return Number of advertising sets that may be created at the same time.
626  */
627  uint8_t getMaxAdvertisingSetNumber();
628 
629  /** Return maximum advertising data length supported.
630  *
631  * @return Maximum advertising data length supported.
632  */
633  uint16_t getMaxAdvertisingDataLength();
634 
635  /** Return maximum advertising data length supported for connectable advertising.
636  *
637  * @return Maximum advertising data length supported for connectable advertising.
638  */
639  uint16_t getMaxConnectableAdvertisingDataLength();
640 
641  /** Return maximum advertising data length you may set if advertising set is active.
642  *
643  * @return Maximum advertising data length you may set if advertising set is active.
644  */
645  uint16_t getMaxActiveSetAdvertisingDataLength();
646 
647 #if BLE_FEATURE_EXTENDED_ADVERTISING
648  /** Create an advertising set and apply the passed in parameters. The handle returned
649  * by this function must be used for all other calls that accept an advertising handle.
650  * When done with advertising, remove from the system using destroyAdvertisingSet().
651  *
652  * @note The exception is the LEGACY_ADVERTISING_HANDLE which may be used at any time.
653  *
654  * @param[out] handle Advertising handle returned, valid only if function returned success.
655  * @param parameters Advertising parameters for the newly created set.
656  * @return BLE_ERROR_NONE on success.
657  *
658  * @version 5+
659  */
660  ble_error_t createAdvertisingSet(
661  advertising_handle_t *handle,
662  const AdvertisingParameters &parameters
663  );
664 
665  /** Remove the advertising set (resets its set parameters). The advertising set must not
666  * be active.
667  *
668  * @note LEGACY_ADVERTISING_HANDLE may not be destroyed.
669  *
670  * @param handle Advertising set handle.
671  * @return BLE_ERROR_NONE on success.
672  *
673  * @version 5+
674  */
675  ble_error_t destroyAdvertisingSet(advertising_handle_t handle);
676 #endif // BLE_FEATURE_EXTENDED_ADVERTISING
677 
678  /** Set advertising parameters of an existing set.
679  *
680  * @param handle Advertising set handle.
681  * @param params New advertising parameters.
682  * @return BLE_ERROR_NONE on success.
683  */
684  ble_error_t setAdvertisingParameters(
685  advertising_handle_t handle,
686  const AdvertisingParameters &params
687  );
688 
689  /** Set new advertising payload for a given advertising set.
690  *
691  * @param handle Advertising set handle.
692  * @param payload Advertising payload.
693  *
694  * @note If advertising set is active you may only set payload of length equal or less
695  * than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must
696  * stop the advertising set, set the payload and restart the set.
697  *
698  * @return BLE_ERROR_NONE on success.
699  *
700  * @see ble::AdvertisingDataBuilder to build a payload.
701  */
702  ble_error_t setAdvertisingPayload(
703  advertising_handle_t handle,
705  );
706 
707  /** Set new advertising scan response for a given advertising set. This will be sent to
708  * device who perform active scanning.
709  *
710  * @param handle Advertising set handle.
711  * @param response Advertising scan response.
712  *
713  * @note If advertising set is active you may only set payload of length equal or less
714  * than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must
715  * stop the advertising set, set the payload and restart the set.
716  *
717  * @return BLE_ERROR_NONE on success.
718  *
719  * @see ble::AdvertisingDataBuilder to build a payload.
720  */
721  ble_error_t setAdvertisingScanResponse(
722  advertising_handle_t handle,
724  );
725 
726  /** Start advertising using the given advertising set.
727  *
728  * @param handle Advertising set handle.
729  * @param maxDuration Max duration for advertising (in units of 10ms) - 0 means no limit.
730  * @param maxEvents Max number of events produced during advertising - 0 means no limit.
731  * @return BLE_ERROR_NONE on success.
732  *
733  * @see EventHandler::onScanRequestReceived when a scan request is received.
734  * @see EventHandler::onAdvertisingEnd when the advertising ends.
735  * @see EventHandler::onConnectionComplete when the device gets connected
736  * by a peer.
737  */
738  ble_error_t startAdvertising(
739  advertising_handle_t handle,
740  adv_duration_t maxDuration = adv_duration_t::forever(),
741  uint8_t maxEvents = 0
742  );
743 
744  /** Stop advertising given advertising set. This is separate from periodic advertising
745  * which will not be affected.
746  *
747  * @param handle Advertising set handle.
748  * @return BLE_ERROR_NONE on success.
749  */
750  ble_error_t stopAdvertising(advertising_handle_t handle);
751 
752  /** Check if advertising is active for a given advertising set.
753  *
754  * @param handle Advertising set handle.
755  * @return True if advertising is active on this set.
756  */
757  bool isAdvertisingActive(advertising_handle_t handle);
758 #endif // BLE_ROLE_BROADCASTER
759 
760 #if BLE_ROLE_BROADCASTER
761 #if BLE_FEATURE_PERIODIC_ADVERTISING
762  /** Set periodic advertising parameters for a given advertising set.
763  *
764  * @param handle Advertising set handle.
765  * @param periodicAdvertisingIntervalMin Minimum interval for periodic advertising.
766  * @param periodicAdvertisingIntervalMax Maximum interval for periodic advertising.
767  * @param advertiseTxPower Include transmission power in the advertisements.
768  * @return BLE_ERROR_NONE on success.
769  *
770  * @version 5+
771  */
772  ble_error_t setPeriodicAdvertisingParameters(
773  advertising_handle_t handle,
774  periodic_interval_t periodicAdvertisingIntervalMin,
775  periodic_interval_t periodicAdvertisingIntervalMax,
776  bool advertiseTxPower = true
777  );
778 
779  /** Set new periodic advertising payload for a given advertising set.
780  *
781  * @param handle Advertising set handle.
782  * @param payload Advertising payload.
783  * @return BLE_ERROR_NONE on success.
784  *
785  * @note If advertising set is active you may only set payload of length equal or less
786  * than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must
787  * stop the advertising set, set the payload and restart the set. Stopping the set will
788  * cause peers to lose sync on the periodic set.
789  *
790  * @see ble::AdvertisingDataBuilder to build a payload.
791  *
792  * @version 5+
793  */
794  ble_error_t setPeriodicAdvertisingPayload(
795  advertising_handle_t handle,
797  );
798 
799  /** Start periodic advertising for a given set. Periodic advertising will not start until
800  * normal advertising is running but will continue to run after normal advertising has stopped.
801  *
802  * @param handle Advertising set handle.
803  * @return BLE_ERROR_NONE on success.
804  *
805  * @version 5+
806  */
807  ble_error_t startPeriodicAdvertising(advertising_handle_t handle);
808 
809  /** Stop periodic advertising for a given set.
810  *
811  * @param handle Advertising set handle.
812  * @return BLE_ERROR_NONE on success.
813  *
814  * @version 5+
815  */
816  ble_error_t stopPeriodicAdvertising(advertising_handle_t handle);
817 
818  /** Check if periodic advertising is active for a given advertising set.
819  *
820  * @param handle Advertising set handle.
821  * @return True if periodic advertising is active on this set.
822  *
823  * @version 5+
824  */
825  bool isPeriodicAdvertisingActive(advertising_handle_t handle);
826 #endif // BLE_ROLE_BROADCASTER
827 #endif // BLE_FEATURE_PERIODIC_ADVERTISING
828 
829  /* scanning */
830 #if BLE_ROLE_OBSERVER
831  /** Set new scan parameters.
832  *
833  * @param params Scan parameters, @see GapScanParameters for details.
834  * @return BLE_ERROR_NONE on success.
835  */
836  ble_error_t setScanParameters(const ScanParameters &params);
837 
838  /** Start scanning.
839  *
840  * @param duration How long to scan for. Special value 0 means scan forever.
841  * @param filtering Filtering policy.
842  * @param period How long to scan for in single period. If the period is 0 and duration
843  * is nonzero the scan will last for single duration.
844  *
845  * @note When the duration and period parameters are non-zero scanning will last for
846  * the duration within the period. After the scan period has expired a new scan period
847  * will begin and scanning. This will repeat until stopScan() is called.
848  *
849  * @return BLE_ERROR_NONE on success.
850  *
851  * @see EventHandler::onAdvertisingReport to collect advertising reports.
852  * @see EventHandler::onScanTimeout when scanning timeout.
853  */
854  ble_error_t startScan(
855  scan_duration_t duration = scan_duration_t::forever(),
856  duplicates_filter_t filtering = duplicates_filter_t::DISABLE,
857  scan_period_t period = scan_period_t(0)
858  );
859 
860  /**
861  * Stop the ongoing scanning procedure.
862  *
863  * The current scanning parameters remain in effect.
864  *
865  * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
866  */
867  ble_error_t stopScan();
868 #endif // BLE_ROLE_OBSERVER
869 
870 #if BLE_ROLE_OBSERVER
871 #if BLE_FEATURE_PERIODIC_ADVERTISING
872  /** Synchronize with periodic advertising from an advertiser and begin receiving periodic
873  * advertising packets.
874  *
875  * @param peerAddressType Peer address type.
876  * @param peerAddress Peer address.
877  * @param sid Advertiser set identifier.
878  * @param maxPacketSkip Number of consecutive periodic advertising packets that the receiver
879  * may skip after successfully receiving a periodic advertising packet.
880  * @param timeout Maximum permitted time between successful receptions. If this time is
881  * exceeded, synchronisation is lost.
882  * @return BLE_ERROR_NONE on success.
883  *
884  * @see EventHandler::onPeriodicAdvertisingSyncEstablished when the sync is
885  * effective.
886  * @see EventHandler::onPeriodicAdvertisingReport when data are issued by the
887  * peer.
888  * @see EventHandler::onPeriodicAdvertisingSyncLoss when the sync has been
889  * loss.
890  *
891  * @version 5+
892  */
893  ble_error_t createSync(
894  peer_address_type_t peerAddressType,
895  const address_t &peerAddress,
896  uint8_t sid,
897  slave_latency_t maxPacketSkip,
898  sync_timeout_t timeout
899  );
900 
901  /** Synchronize with periodic advertising from an advertiser and begin receiving periodic
902  * advertising packets. Use periodic advertising sync list to determine who to sync with.
903  *
904  * @param maxPacketSkip Number of consecutive periodic advertising packets that the receiver
905  * may skip after successfully receiving a periodic advertising packet.
906  * @param timeout Maximum permitted time between successful receives.
907  * If this time is exceeded, synchronisation is lost.
908  * @return BLE_ERROR_NONE on success.
909  *
910  * @see EventHandler::onPeriodicAdvertisingSyncEstablished when the sync is
911  * effective.
912  * @see EventHandler::onPeriodicAdvertisingReport when data are issued by the
913  * peer.
914  * @see EventHandler::onPeriodicAdvertisingSyncLoss when the sync has been
915  * loss.
916  *
917  * @version 5+
918  */
919  ble_error_t createSync(
920  slave_latency_t maxPacketSkip,
921  sync_timeout_t timeout
922  );
923 
924  /** Cancel sync attempt.
925  *
926  * @return BLE_ERROR_NONE on success.
927  */
928  ble_error_t cancelCreateSync();
929 
930  /** Stop reception of the periodic advertising identified by the handle.
931  *
932  * @param handle Periodic advertising synchronisation handle.
933  * @return BLE_ERROR_NONE on success.
934  */
935  ble_error_t terminateSync(periodic_sync_handle_t handle);
936 
937  /** Add device to the periodic advertiser list. Cannot be called when sync is ongoing.
938  *
939  * @param peerAddressType Peer address type.
940  * @param peerAddress Peer address.
941  * @param sid Advertiser set identifier.
942  * @return BLE_ERROR_NONE on success.
943  */
944  ble_error_t addDeviceToPeriodicAdvertiserList(
945  peer_address_type_t peerAddressType,
946  const address_t &peerAddress,
947  advertising_sid_t sid
948  );
949 
950  /** Remove device from the periodic advertiser list. Cannot be called when sync is ongoing.
951  *
952  * @param peerAddressType Peer address type.
953  * @param peerAddress Peer address.
954  * @param sid Advertiser set identifier.
955  * @return BLE_ERROR_NONE on success.
956  */
957  ble_error_t removeDeviceFromPeriodicAdvertiserList(
958  peer_address_type_t peerAddressType,
959  const address_t &peerAddress,
960  advertising_sid_t sid
961  );
962 
963  /** Remove all devices from periodic advertiser list.
964  *
965  * @return BLE_ERROR_NONE on success.
966  */
967  ble_error_t clearPeriodicAdvertiserList();
968 
969  /** Get number of devices that can be added to the periodic advertiser list.
970  * @return Number of devices that can be added to the periodic advertiser list.
971  */
972  uint8_t getMaxPeriodicAdvertiserListSize();
973 #endif // BLE_ROLE_OBSERVER
974 #endif // BLE_FEATURE_PERIODIC_ADVERTISING
975 
976 #if BLE_ROLE_CENTRAL
977  /**
978  * Initiate a connection to a peer.
979  *
980  * Once the connection is established an onConnectionComplete in the event handler
981  * will be called.
982  *
983  * @param peerAddressType
984  * @param peerAddress
985  * @param connectionParams
986  *
987  * @return BLE_ERROR_NONE if connection establishment procedure is started
988  * successfully. The connectionCallChain (if set) is invoked upon
989  * a connection event.
990  *
991  * @see EventHandler::onConnectionComplete will be called whether the
992  * connection process succeed or fail.
993  * @see EventHandler::onDisconnectionComplete is called when the connection
994  * ends.
995  */
996  ble_error_t connect(
997  peer_address_type_t peerAddressType,
998  const address_t &peerAddress,
999  const ConnectionParameters &connectionParams
1000  );
1001 
1002  /** Cancel the connection attempt. This is not guaranteed to succeed. As a result
1003  * onConnectionComplete in the event handler will be called. Check the success parameter
1004  * to see if the connection was created.
1005  * @depreacted This version has a defective API. You must provide the address of the peer.
1006  * Please use the cancelConnect that takes peer address as parameters.
1007  * This call will attempt to cancel the most recently requested connection.
1008  *
1009  * @return BLE_ERROR_NONE if the connection attempt has been requested to be cancelled.
1010  * Returns BLE_ERROR_OPERATION_NOT_PERMITTED if no ongoing connection for last used address found.
1011  */
1012  MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "Defective API. Please use the cancelConnect that takes peer address as parameters.")
1013  ble_error_t cancelConnect();
1014 
1015  /** Cancel the connection attempt. This is not guaranteed to succeed. As a result
1016  * onConnectionComplete in the event handler will be called. Check the success parameter
1017  * to see if the connection was created.
1018  *
1019  * @param peerAddressType Address type you want to cancel connection process for.
1020  * @param peerAddress Address you want to cancel connection process for.
1021  *
1022  * @return BLE_ERROR_NONE if the connection attempt has been requested to be cancelled.
1023  * Returns BLE_ERROR_OPERATION_NOT_PERMITTED if no ongoing connection for address found.
1024  */
1025  ble_error_t cancelConnect(
1026  peer_address_type_t peerAddressType,
1027  const address_t &peerAddress
1028  );
1029 #endif // BLE_ROLE_CENTRAL
1030 
1031 #if BLE_FEATURE_CONNECTABLE
1032  /**
1033  * Update connection parameters of an existing connection.
1034  *
1035  * In the central role, this initiates a Link Layer connection parameter
1036  * update procedure. In the peripheral role, this sends the corresponding
1037  * L2CAP request and waits for the central to accept or reject the requested
1038  * connection parameters.
1039  *
1040  * @param connectionHandle The handle of the connection to update.
1041  * @param minConnectionInterval The minimum connection interval requested.
1042  * @param maxConnectionInterval The maximum connection interval requested.
1043  * @param slaveLatency The slave latency requested.
1044  * @param supervision_timeout The supervision timeout requested.
1045  * @param minConnectionEventLength The minimum connection event length requested.
1046  * @param maxConnectionEventLength The maximum connection event length requested.
1047  *
1048  * @return BLE_ERROR_NONE if the request has been sent and false otherwise.
1049  *
1050  * @see EventHandler::onUpdateConnectionParametersRequest when a central
1051  * receives a request to update the connection parameters.
1052  * @see EventHandler::onConnectionParametersUpdateComplete when connection
1053  * parameters have been updated.
1054  *
1055  * @version 4.0+ for central
1056  * @version 4.1+ for peripheral
1057  */
1058  ble_error_t updateConnectionParameters(
1059  connection_handle_t connectionHandle,
1060  conn_interval_t minConnectionInterval,
1061  conn_interval_t maxConnectionInterval,
1062  slave_latency_t slaveLatency,
1063  supervision_timeout_t supervision_timeout,
1064  conn_event_length_t minConnectionEventLength = conn_event_length_t(0),
1065  conn_event_length_t maxConnectionEventLength = conn_event_length_t(0)
1066  );
1067 
1068  /**
1069  * Allows the application to accept or reject a connection parameters update
1070  * request.
1071  *
1072  * If this process is managed by the middleware; new connection parameters
1073  * from a slave are always accepted.
1074  *
1075  * @param userManageConnectionUpdateRequest true to let the application
1076  * manage the process and false to let the middleware manage it.
1077  *
1078  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1079  *
1080  * @version 4.1+
1081  *
1082  * @see EventHandler::onUpdateConnectionParametersRequest when a central
1083  * receives a request to update the connection parameters.
1084  *
1085  * @see acceptConnectionParametersUpdate to accept the request.
1086  * @see rejectConnectionParametersUpdate to reject the request.
1087  */
1088  ble_error_t manageConnectionParametersUpdateRequest(
1089  bool userManageConnectionUpdateRequest
1090  );
1091 
1092  /**
1093  * Accept update of the connection parameters.
1094  *
1095  * The central can adjust the new connection parameters.
1096  *
1097  * @param connectionHandle The handle of the connection that has initiated
1098  * the request.
1099  * @param minConnectionInterval The minimum connection interval to be applied.
1100  * @param maxConnectionInterval The maximum connection interval to be applied.
1101  * @param slaveLatency The slave latency to be applied.
1102  * @param supervision_timeout The supervision timeout to be applied.
1103  * @param minConnectionEventLength The minimum connection event length to be
1104  * applied.
1105  * @param maxConnectionEventLength The maximum connection event length to be
1106  * applied.
1107  *
1108  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1109  *
1110  * @version 4.1+
1111  *
1112  * @see manageConnectionParametersUpdateRequest To let the application
1113  * manage the process.
1114  *
1115  * @see EventHandler::onUpdateConnectionParametersRequest Called when a
1116  * request to update the connection parameters is received.
1117  *
1118  * @see EventHandler::onConnectionParametersUpdateComplete Called when the
1119  * new connection parameters are effective.
1120  */
1121  ble_error_t acceptConnectionParametersUpdate(
1122  connection_handle_t connectionHandle,
1123  conn_interval_t minConnectionInterval,
1124  conn_interval_t maxConnectionInterval,
1125  slave_latency_t slaveLatency,
1126  supervision_timeout_t supervision_timeout,
1127  conn_event_length_t minConnectionEventLength = conn_event_length_t(0),
1128  conn_event_length_t maxConnectionEventLength = conn_event_length_t(0)
1129  );
1130 
1131  /**
1132  * Reject a request to change the connection parameters.
1133  *
1134  * @param connectionHandle The handle of the connection that has initiated
1135  * the request.
1136  *
1137  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1138  *
1139  * @version 4.1+
1140  *
1141  * @see manageConnectionParametersUpdateRequest To let the application
1142  * manage the process.
1143  *
1144  * @see EventHandler::onUpdateConnectionParametersRequest Called when a
1145  * request to update the connection parameters is received.
1146  */
1147  ble_error_t rejectConnectionParametersUpdate(
1148  connection_handle_t connectionHandle
1149  );
1150 
1151  /**
1152  * Initiate a disconnection procedure.
1153  *
1154  * Once the disconnection procedure has completed a
1155  * DisconnectionCallbackParams_t, the event is emitted to handlers that
1156  * have been registered with onDisconnection().
1157  *
1158  * @param[in] reason Reason of the disconnection transmitted to the peer.
1159  * @param[in] connectionHandle Handle of the connection to end.
1160  *
1161  * @return BLE_ERROR_NONE if the disconnection procedure successfully
1162  * started.
1163  *
1164  * @see EventHandler::onDisconnectionComplete when the disconnection is
1165  * effective.
1166  */
1167  ble_error_t disconnect(
1168  connection_handle_t connectionHandle,
1169  local_disconnection_reason_t reason
1170  );
1171 #endif // BLE_FEATURE_CONNECTABLE
1172 #if BLE_FEATURE_PHY_MANAGEMENT
1173  /**
1174  * Read the PHY used by the transmitter and the receiver on a connection.
1175  *
1176  * Once the PHY has been read, it is reported back via the function onPhyRead
1177  * of the event handler registered by the application.
1178  *
1179  * @param connection Handle of the connection for which the PHY being used is
1180  * queried.
1181  *
1182  * @return BLE_ERROR_NONE if the read PHY procedure has been started or an
1183  * appropriate error code.
1184  *
1185  * @version 5+
1186  *
1187  * @see EventHandler::onReadPhy is called when the phy has been read.
1188  */
1189  ble_error_t readPhy(connection_handle_t connection);
1190 
1191  /**
1192  * Set the preferred PHYs to use in a connection.
1193  *
1194  * @param txPhys: Set of PHYs preferred for tx operations. If NULL then no
1195  * preferred PHYs are set and the default value of the subsystem is used.
1196  *
1197  * @param rxPhys: Set of PHYs preferred for rx operations. If NULL then no
1198  * preferred PHYs are set and the default value of the subsystem is used.
1199  *
1200  * @return BLE_ERROR_NONE if the preferences have been set or an appropriate
1201  * error code.
1202  *
1203  * @version 5+
1204  */
1205  ble_error_t setPreferredPhys(
1206  const phy_set_t *txPhys,
1207  const phy_set_t *rxPhys
1208  );
1209 
1210  /**
1211  * Update the PHY used by a connection.
1212  *
1213  * Once the update process has been completed, it is reported back to the
1214  * application via the function onPhyUpdateComplete of the event handler
1215  * registered by the application.
1216  *
1217  * @param connection Handle of the connection to update.
1218  *
1219  * @param txPhys Set of PHYs preferred for tx operations. If NULL then the
1220  * choice is up to the Bluetooth subsystem.
1221  *
1222  * @param rxPhys Set of PHYs preferred for rx operations. If NULL then the
1223  * choice is up to the Bluetooth subsystem.
1224  *
1225  * @param codedSymbol Number of symbols used to code a bit when le coded is
1226  * used. If the value is UNDEFINED then the choice is up to the Bluetooth
1227  * subsystem.
1228  *
1229  * @return BLE_ERROR_NONE if the update PHY procedure has been successfully
1230  * started or an error code.
1231  *
1232  * @see EventHandler::onPhyUpdateComplete is called when the phy used by the
1233  * connection has been updated.
1234  */
1235  ble_error_t setPhy(
1236  connection_handle_t connection,
1237  const phy_set_t *txPhys,
1238  const phy_set_t *rxPhys,
1239  coded_symbol_per_bit_t codedSymbol
1240  );
1241 #endif // BLE_FEATURE_PHY_MANAGEMENT
1242 
1243 #if BLE_FEATURE_PRIVACY
1244  /**
1245  * Enable or disable privacy mode of the local device.
1246  *
1247  * When privacy is enabled, the system use private addresses while it scans,
1248  * advertises or initiate a connection. The device private address is
1249  * renewed every 15 minutes.
1250  *
1251  * @par Configuration
1252  *
1253  * The privacy feature can be configured with the help of the functions
1254  * setPeripheralPrivacyConfiguration and setCentralPrivacyConfiguration
1255  * which respectively set the privacy configuration of the peripheral and
1256  * central role.
1257  *
1258  * @par Default configuration of peripheral role
1259  *
1260  * By default private resolvable addresses are used for all procedures;
1261  * including advertisement of nonconnectable packets. Connection request
1262  * from an unknown initiator with a private resolvable address triggers the
1263  * pairing procedure.
1264  *
1265  * @par Default configuration of central role
1266  *
1267  * By default private resolvable addresses are used for all procedures;
1268  * including active scanning. Addresses present in advertisement packet are
1269  * resolved and advertisement packets are forwarded to the application
1270  * even if the advertiser private address is unknown.
1271  *
1272  * @param[in] enable Should be set to true to enable the privacy mode and
1273  * false to disable it.
1274  *
1275  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1276  */
1277  ble_error_t enablePrivacy(bool enable);
1278 
1279 #if BLE_ROLE_BROADCASTER
1280  /**
1281  * Set the privacy configuration used by the peripheral role.
1282  *
1283  * @param[in] configuration The configuration to set.
1284  *
1285  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1286  */
1287  ble_error_t setPeripheralPrivacyConfiguration(
1288  const peripheral_privacy_configuration_t *configuration
1289  );
1290 
1291  /**
1292  * Get the privacy configuration used by the peripheral role.
1293  *
1294  * @param[out] configuration The variable filled with the current
1295  * configuration.
1296  *
1297  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1298  */
1299  ble_error_t getPeripheralPrivacyConfiguration(
1300  peripheral_privacy_configuration_t *configuration
1301  );
1302 #endif // BLE_ROLE_BROADCASTER
1303 
1304 #if BLE_ROLE_OBSERVER
1305  /**
1306  * Set the privacy configuration used by the central role.
1307  *
1308  * @param[in] configuration The configuration to set.
1309  *
1310  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1311  */
1312  ble_error_t setCentralPrivacyConfiguration(
1313  const central_privacy_configuration_t *configuration
1314  );
1315 
1316  /**
1317  * Get the privacy configuration used by the central role.
1318  *
1319  * @param[out] configuration The variable filled with the current
1320  * configuration.
1321  *
1322  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1323  */
1324  ble_error_t getCentralPrivacyConfiguration(
1325  central_privacy_configuration_t *configuration
1326  );
1327 #endif // BLE_ROLE_OBSERVER
1328 #endif // BLE_FEATURE_PRIVACY
1329 
1330 #if BLE_FEATURE_WHITELIST
1331  /**
1332  * Get the maximum size of the whitelist.
1333  *
1334  * @return Maximum size of the whitelist.
1335  */
1336  uint8_t getMaxWhitelistSize(void) const;
1337 
1338  /**
1339  * Get the Link Layer to use the internal whitelist when scanning,
1340  * advertising or initiating a connection depending on the filter policies.
1341  *
1342  * @param[in,out] whitelist Define the whitelist instance which is used
1343  * to store the whitelist requested. In input, the caller provisions memory.
1344  *
1345  * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
1346  * copied into the supplied reference.
1347  */
1348  ble_error_t getWhitelist(whitelist_t &whitelist) const;
1349 
1350  /**
1351  * Set the value of the whitelist to be used during GAP procedures.
1352  *
1353  * @param[in] whitelist A reference to a whitelist containing the addresses
1354  * to be copied to the internal whitelist.
1355  *
1356  * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
1357  * populated with the addresses in the given whitelist.
1358  *
1359  * @note The whitelist must not contain non-resolvable addresses. This
1360  * results in a @ref BLE_ERROR_INVALID_PARAM because the remote peer might
1361  * change its private address at any time, and it is not possible to resolve
1362  * it.
1363  *
1364  * @note If the input whitelist is larger than @ref getMaxWhitelistSize(),
1365  * then @ref BLE_ERROR_PARAM_OUT_OF_RANGE is returned.
1366  */
1367  ble_error_t setWhitelist(const whitelist_t &whitelist);
1368 
1369 #endif // BLE_FEATURE_WHITELIST
1370 
1371  /**
1372  * Fetch the current address and its type.
1373  *
1374  * @param[out] typeP Type of the current address set.
1375  * @param[out] address Value of the current address.
1376  *
1377  * @note If privacy is enabled the device address may be unavailable to
1378  * application code.
1379  *
1380  * @return BLE_ERROR_NONE on success.
1381  */
1382  ble_error_t getAddress(
1383  own_address_type_t &typeP,
1384  address_t &address
1385  );
1386 
1387  /**
1388  * Return the type of a random address.
1389  *
1390  * @param[in] address The random address to retrieve the type from. The
1391  * address must be ordered in little endian.
1392  *
1393  * @param[out] addressType Type of the address to fill.
1394  *
1395  * @return BLE_ERROR_NONE in case of success or BLE_ERROR_INVALID_PARAM if
1396  * the address in input was not identifiable as a random address.
1397  */
1398  static ble_error_t getRandomAddressType(
1399  const ble::address_t address,
1400  ble::random_address_type_t *addressType
1401  );
1402 
1403  /**
1404  * Reset the Gap instance.
1405  *
1406  * Reset process starts by notifying all registered shutdown event handlers
1407  * that the Gap instance is about to be shut down. Then, it clears all Gap state
1408  * of the associated object and then cleans the state present in the vendor
1409  * implementation.
1410  *
1411  * This function is meant to be overridden in the platform-specific
1412  * subclass. Nevertheless, the subclass only resets its
1413  * state and not the data held in Gap members. This is achieved by a
1414  * call to Gap::reset() from the subclass' reset() implementation.
1415  *
1416  * @return BLE_ERROR_NONE on success.
1417  *
1418  * @note Currently, a call to reset() does not reset the advertising and
1419  * scan parameters to default values.
1420  */
1421  ble_error_t reset(void);
1422 
1423  /**
1424  * Register a Gap shutdown event handler.
1425  *
1426  * The handler is called when the Gap instance is about to shut down.
1427  * It is usually issued after a call to BLE::shutdown().
1428  *
1429  * @param[in] callback Shutdown event handler to register.
1430  *
1431  * @note To unregister a shutdown event handler, use
1432  * onShutdown().detach(callback).
1433  */
1434  void onShutdown(const GapShutdownCallback_t &callback);
1435 
1436  /**
1437  * Register a Gap shutdown event handler.
1438  *
1439  * @param[in] objPtr Instance used to invoke @p memberPtr.
1440  * @param[in] memberPtr Shutdown event handler to register.
1441  */
1442  template<typename T>
1443  void onShutdown(T *objPtr, void (T::*memberPtr)(const Gap *));
1444 
1445  /**
1446  * Access the callchain of shutdown event handler.
1447  *
1448  * @note To register callbacks, use onShutdown().add(callback).
1449  *
1450  * @note To unregister callbacks, use onShutdown().detach(callback).
1451  *
1452  * @return A reference to the shutdown event callback chain.
1453  */
1454  GapShutdownCallbackChain_t &onShutdown();
1455 
1456 #if !defined(DOXYGEN_ONLY)
1457  /*
1458  * API reserved for the controller driver to set the random static address.
1459  * Setting a new random static address while the controller is operating is
1460  * forbidden by the Bluetooth specification.
1461  */
1462  ble_error_t setRandomStaticAddress(const ble::address_t& address);
1463 #endif // !defined(DOXYGEN_ONLY)
1464 };
1465 
1466 /**
1467  * @}
1468  * @}
1469  */
1470 
1471 #if !defined(DOXYGEN_ONLY)
1472 } // namespace interface
1473 #endif // !defined(DOXYGEN_ONLY)
1474 } // namespace ble
1475 
1476 /* This includes the concrete class implementation, to provide a an alternative API implementation
1477  * disable ble-api-implementation and place your header in a path with the same structure */
1478 #include "ble/internal/GapImpl.h"
1479 
1480 /** @deprecated Use the namespaced ble::Gap instead of the global Gap. */
1481 using ble::Gap;
1482 
1483 #endif // BLE_GAP_GAP_H
Event generated when a connection initiation ends (successfully or not).
Definition: Events.h:186
Event produced when advertising ends.
Definition: Events.h:527
virtual void onScanRequestReceived(const ScanRequestEvent &event)
Called when an advertising device receive a scan response.
Definition: Gap.h:317
Define device discovery, connection and link management procedures.
Definition: Gap.h:286
Event received when connection parameters have been updated.
Definition: Events.h:751
Event generated when periodic advertising sync is lost.
Definition: Events.h:489
uintptr_t connection_handle_t
Opaque reference to a connection.
Definition: BLETypes.h:89
virtual void onReadPhy(ble_error_t status, connection_handle_t connectionHandle, phy_t txPhy, phy_t rxPhy)
Function invoked when the current transmitter and receiver PHY have been read for a given connection...
Definition: Gap.h:483
Event generated when an advertising packet is seen during passive scanning or a scan response is rece...
Definition: Events.h:40
virtual void onUpdateConnectionParametersRequest(const UpdateConnectionParametersRequestEvent &event)
Called when the peer request connection parameters updates.
Definition: Gap.h:434
Type that describes a random device address type.
Definition: BLETypes.h:500
Type describing the number of symbols per bit in le coded PHY.
Definition: BLETypes.h:814
virtual void onConnectionComplete(const ConnectionCompleteEvent &event)
Called when connection attempt ends or an advertising device has been connected.
Definition: Gap.h:413
virtual void onDataLengthChange(connection_handle_t connectionHandle, uint16_t txSize, uint16_t rxSize)
Function invoked when the connections changes the maximum number of octets that can be sent or receiv...
Definition: Gap.h:538
Representation of a whitelist of addresses.
Definition: BLETypes.h:844
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=nullptr) noexcept
Create a callback class with type inferred from the arguments.
Definition: Callback.h:678
Parameters defining the scan process.
MAC address data type.
Definition: BLETypes.h:479
Type that describes a bluetooth PHY(sical) transport.
Definition: BLETypes.h:634
~EventHandler()
Prevent polymorphic deletion and avoid unnecessary virtual destructor as the Gap class will never del...
Definition: Gap.h:550
uint16_t maxConnectionInterval
Maximum interval between two connection events allowed for a connection.
Definition: Gap.h:575
Parameters defining the connection initiation process.
virtual void onAdvertisingEnd(const AdvertisingEndEvent &event)
Called when advertising ends.
Definition: Gap.h:333
CallChainOfFunctionPointersWithContext< const Gap * > GapShutdownCallbackChain_t
Callchain of gap shutdown event handler.
Definition: Gap.h:301
virtual void onScanTimeout(const ScanTimeoutEvent &event)
Called when scan times out.
Definition: Gap.h:355
virtual void onConnectionParametersUpdateComplete(const ConnectionParametersUpdateCompleteEvent &event)
Called when connection parameters have been updated.
Definition: Gap.h:448
uint16_t slaveLatency
Number of connection events the slave can drop if it has nothing to communicate to the master...
Definition: Gap.h:583
Event generated when you first receive a periodic advertisement.
Definition: Events.h:317
Preferred connection parameter display in Generic Access Service.
Definition: Gap.h:558
FunctionPointerWithContext< const Gap * > GapShutdownCallback_t
Gap shutdown event handler.
Definition: Gap.h:293
uint16_t connectionSupervisionTimeout
Link supervision timeout for the connection.
Definition: Gap.h:599
Type that describes a peer device address type.
Definition: BLETypes.h:586
Event generated when scan times out.
Definition: Events.h:520
Event produced when a disconnection is complete.
Definition: Events.h:639
uint16_t minConnectionInterval
Minimum interval between two connection events allowed for a connection.
Definition: Gap.h:566
Type that describe a set of PHY(sical) transports.
Definition: BLETypes.h:699
Parameters defining the advertising process.
Definition of the general handler of Gap related events.
Definition: Gap.h:307
virtual void onDisconnectionComplete(const DisconnectionCompleteEvent &event)
Called when a connection has been disconnected.
Definition: Gap.h:461
Event generated when periodic advertising packet is received.
Definition: Events.h:418
Event received when a peer wants to change the connection parameters.
Definition: Events.h:678
virtual void onPeriodicAdvertisingSyncLoss(const PeriodicAdvertisingSyncLoss &event)
Called when a periodic advertising sync has been lost.
Definition: Gap.h:398
virtual void onPeriodicAdvertisingReport(const PeriodicAdvertisingReportEvent &event)
Called when a periodic advertising packet is received.
Definition: Gap.h:383
virtual void onAdvertisingReport(const AdvertisingReportEvent &event)
Called when a scanner receives an advertising or a scan response packet.
Definition: Gap.h:344
virtual void onPhyUpdateComplete(ble_error_t status, connection_handle_t connectionHandle, phy_t txPhy, phy_t rxPhy)
Function invoked when the update process of the PHY has been completed.
Definition: Gap.h:517
Entry namespace for all BLE API definitions.
Features supported by the controller.
Definition: BLETypes.h:54
Event produced when a peer requests a scan response from the advertiser.
Definition: Events.h:588
virtual void onPeriodicAdvertisingSyncEstablished(const PeriodicAdvertisingSyncEstablishedEvent &event)
Called when first advertising packet in periodic advertising is received.
Definition: Gap.h:368
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
ble_error_t
Error codes for the BLE API.
Definition: blecommon.h:149
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.