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