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 starts.
319  *
320  * @param event Advertising start event.
321  *
322  * @see startAdvertising()
323  */
324  virtual void onAdvertisingStart(const AdvertisingStartEvent &event)
325  {
326  }
327 
328  /**
329  * Called when advertising ends.
330  *
331  * Advertising ends when the process timeout or if it is stopped by the
332  * application or if the local device accepts a connection request.
333  *
334  * @param event Advertising end event.
335  *
336  * @see startAdvertising()
337  * @see stopAdvertising()
338  * @see onConnectionComplete()
339  */
340  virtual void onAdvertisingEnd(const AdvertisingEndEvent &event)
341  {
342  }
343 
344  /**
345  * Called when a scanner receives an advertising or a scan response packet.
346  *
347  * @param event Advertising report.
348  *
349  * @see startScan()
350  */
351  virtual void onAdvertisingReport(const AdvertisingReportEvent &event)
352  {
353  }
354 
355  /**
356  * Called when scan times out.
357  *
358  * @param event Associated event.
359  *
360  * @see startScan()
361  */
362  virtual void onScanTimeout(const ScanTimeoutEvent &event)
363  {
364  }
365 
366  /**
367  * Called when first advertising packet in periodic advertising is received.
368  *
369  * @param event Periodic advertising sync event.
370  *
371  * @version: 5+.
372  *
373  * @see createSync()
374  */
377  )
378  {
379  }
380 
381  /**
382  * Called when a periodic advertising packet is received.
383  *
384  * @param event Periodic advertisement event.
385  *
386  * @version: 5+.
387  *
388  * @see createSync()
389  */
391  const PeriodicAdvertisingReportEvent &event
392  )
393  {
394  }
395 
396  /**
397  * Called when a periodic advertising sync has been lost.
398  *
399  * @param event Details of the event.
400  *
401  * @version: 5+.
402  *
403  * @see createSync()
404  */
406  const PeriodicAdvertisingSyncLoss &event
407  )
408  {
409  }
410 
411  /**
412  * Called when connection attempt ends or an advertising device has been
413  * connected.
414  *
415  * @see startAdvertising()
416  * @see connect()
417  *
418  * @param event Connection event.
419  */
421  {
422  }
423 
424  /**
425  * Called when the peer request connection parameters updates.
426  *
427  * Application must accept the update with acceptConnectionParametersUpdate()
428  * or reject it with rejectConnectionParametersUpdate().
429  *
430  * @param event The connection parameters requested by the peer.
431  *
432  * @version 4.1+.
433  *
434  * @note This event is not generated if connection parameters update
435  * is managed by the middleware.
436  *
437  * @see manageConnectionParametersUpdateRequest()
438  * @see acceptConnectionParametersUpdate()
439  * @see rejectConnectionParametersUpdate()
440  */
443  )
444  {
445  }
446 
447  /**
448  * Called when connection parameters have been updated.
449  *
450  * @param event The new connection parameters.
451  *
452  * @see updateConnectionParameters()
453  * @see acceptConnectionParametersUpdate()
454  */
457  )
458  {
459  }
460 
461  /**
462  * Called when a connection has been disconnected.
463  *
464  * @param event Details of the event.
465  *
466  * @see disconnect()
467  */
469  {
470  }
471 
472  /**
473  * Function invoked when the current transmitter and receiver PHY have
474  * been read for a given connection.
475  *
476  * @param status Status of the operation: BLE_ERROR_NONE in case of
477  * success or an appropriate error code.
478  *
479  * @param connectionHandle: The handle of the connection for which the
480  * PHYs have been read.
481  *
482  * @param txPhy PHY used by the transmitter.
483  *
484  * @param rxPhy PHY used by the receiver.
485  *
486  * @see readPhy().
487  *
488  * @version: 5+.
489  */
490  virtual void onReadPhy(
491  ble_error_t status,
492  connection_handle_t connectionHandle,
493  phy_t txPhy,
494  phy_t rxPhy
495  )
496  {
497  }
498 
499  /**
500  * Function invoked when the update process of the PHY has been completed.
501  *
502  * The process can be initiated by a call to the function setPhy, the
503  * local bluetooth subsystem or the peer.
504  *
505  * @param status Status of the operation: BLE_ERROR_NONE in case of
506  * success or an appropriate error code.
507  *
508  * @param connectionHandle: The handle of the connection on which the
509  * operation was made.
510  *
511  * @param txPhy PHY used by the transmitter.
512  *
513  * @param rxPhy PHY used by the receiver.
514  *
515  * @note Success doesn't mean the PHY has been updated it means both
516  * ends have negotiated the best PHY according to their configuration and
517  * capabilities. The PHY currently used are present in the txPhy and
518  * rxPhy parameters.
519  *
520  * @see setPhy()
521  *
522  * @version: 5+.
523  */
524  virtual void onPhyUpdateComplete(
525  ble_error_t status,
526  connection_handle_t connectionHandle,
527  phy_t txPhy,
528  phy_t rxPhy
529  )
530  {
531  }
532 
533  /**
534  * Function invoked when the connections changes the maximum number of octets
535  * that can be sent or received by the controller in a single packet. A single
536  * L2CAP packet can be fragmented across many such packets.
537  *
538  * @note This only triggers if controller supports data length extension and
539  * negotiated data length is longer than the default 23.
540  *
541  * @param connectionHandle The handle of the connection that changed the size.
542  * @param txSize Number of octets we can send on this connection in a single packet.
543  * @param rxSize Number of octets we can receive on this connection in a single packet.
544  */
545  virtual void onDataLengthChange(
546  connection_handle_t connectionHandle,
547  uint16_t txSize,
548  uint16_t rxSize
549  )
550  {
551  }
552 
553  /**
554  * Function invoked when the privacy subsystem has been enabled and is
555  * ready to be used.
556  */
557  virtual void onPrivacyEnabled()
558  {
559  }
560  protected:
561  /**
562  * Prevent polymorphic deletion and avoid unnecessary virtual destructor
563  * as the Gap class will never delete the instance it contains.
564  */
565  ~EventHandler() = default;
566  };
567 
568  /**
569  * Preferred connection parameter display in Generic Access Service.
570  */
571  typedef struct {
572  /**
573  * Minimum interval between two connection events allowed for a
574  * connection.
575  *
576  * It shall be less than or equal to maxConnectionInterval. This value,
577  * in units of 1.25ms, is included in the range [0x0006 : 0x0C80].
578  */
580 
581  /**
582  * Maximum interval between two connection events allowed for a
583  * connection.
584  *
585  * It shall be greater than or equal to minConnectionInterval. This
586  * value is in unit of 1.25ms and is in the range [0x0006 : 0x0C80].
587  */
589 
590  /**
591  * Number of connection events the slave can drop if it has nothing to
592  * communicate to the master.
593  *
594  * This value shall be in the range [0x0000 : 0x01F3].
595  */
596  uint16_t slaveLatency;
597 
598  /**
599  * Link supervision timeout for the connection.
600  *
601  * Time after which the connection is considered lost if the device
602  * didn't receive a packet from its peer.
603  *
604  * It is larger than:
605  * (1 + slaveLatency) * maxConnectionInterval * 2
606  *
607  * This value is in the range [0x000A : 0x0C80] and is in unit of
608  * 10 ms.
609  *
610  * @note maxConnectionInterval is in ms in the formulae above.
611  */
614 
615  /**
616  * Assign the event handler implementation that will be used by the gap
617  * module to signal events back to the application.
618  *
619  * @param handler Application implementation of an EventHandler.
620  *
621  * @note Multiple discrete EventHandler instances may be used by adding them
622  * to a ChainableGapEventHandler and then setting the chain as the primary
623  * Gap EventHandler using this function.
624  *
625  * @see ChainableGapEventHandler
626  */
627  void setEventHandler(EventHandler *handler);
628 
629  /** Check controller support for a specific feature.
630  *
631  * @param feature Feature to check.
632  * @return True if feature is supported.
633  */
634  bool isFeatureSupported(controller_supported_features_t feature);
635 
636  /* advertising */
637 #if BLE_ROLE_BROADCASTER
638  /** Return currently available number of supported advertising sets.
639  * This may change at runtime.
640  *
641  * @note Devices that do not support Bluetooth 5 still offers one advertising
642  * set that has the handle LEGACY_ADVERTISING_HANDLE.
643  *
644  * @return Number of advertising sets that may be created at the same time.
645  */
646  uint8_t getMaxAdvertisingSetNumber();
647 
648  /** Return maximum advertising data length supported.
649  *
650  * @return Maximum advertising data length supported.
651  */
652  uint16_t getMaxAdvertisingDataLength();
653 
654  /** Return maximum advertising data length supported for connectable advertising.
655  *
656  * @return Maximum advertising data length supported for connectable advertising.
657  */
658  uint16_t getMaxConnectableAdvertisingDataLength();
659 
660  /** Return maximum advertising data length you may set if advertising set is active.
661  *
662  * @return Maximum advertising data length you may set if advertising set is active.
663  */
664  uint16_t getMaxActiveSetAdvertisingDataLength();
665 
666 #if BLE_FEATURE_EXTENDED_ADVERTISING
667  /** Create an advertising set and apply the passed in parameters. The handle returned
668  * by this function must be used for all other calls that accept an advertising handle.
669  * When done with advertising, remove from the system using destroyAdvertisingSet().
670  *
671  * @note The exception is the LEGACY_ADVERTISING_HANDLE which may be used at any time.
672  *
673  * @param[out] handle Advertising handle returned, valid only if function returned success.
674  * @param parameters Advertising parameters for the newly created set.
675  * @return BLE_ERROR_NONE on success.
676  *
677  * @version 5+
678  */
679  ble_error_t createAdvertisingSet(
680  advertising_handle_t *handle,
681  const AdvertisingParameters &parameters
682  );
683 
684  /** Remove the advertising set (resets its set parameters). The advertising set must not
685  * be active.
686  *
687  * @note LEGACY_ADVERTISING_HANDLE may not be destroyed.
688  *
689  * @param handle Advertising set handle.
690  * @return BLE_ERROR_NONE on success.
691  *
692  * @version 5+
693  */
694  ble_error_t destroyAdvertisingSet(advertising_handle_t handle);
695 #endif // BLE_FEATURE_EXTENDED_ADVERTISING
696 
697  /** Set advertising parameters of an existing set.
698  *
699  * @param handle Advertising set handle.
700  * @param params New advertising parameters.
701  * @return BLE_ERROR_NONE on success.
702  */
703  ble_error_t setAdvertisingParameters(
704  advertising_handle_t handle,
705  const AdvertisingParameters &params
706  );
707 
708  /** Set new advertising payload for a given advertising set.
709  *
710  * @param handle Advertising set handle.
711  * @param payload Advertising payload.
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 setAdvertisingPayload(
722  advertising_handle_t handle,
724  );
725 
726  /** Set new advertising scan response for a given advertising set. This will be sent to
727  * device who perform active scanning.
728  *
729  * @param handle Advertising set handle.
730  * @param response Advertising scan response.
731  *
732  * @note If advertising set is active you may only set payload of length equal or less
733  * than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must
734  * stop the advertising set, set the payload and restart the set.
735  *
736  * @return BLE_ERROR_NONE on success.
737  *
738  * @see ble::AdvertisingDataBuilder to build a payload.
739  */
740  ble_error_t setAdvertisingScanResponse(
741  advertising_handle_t handle,
743  );
744 
745  /** Start advertising using the given advertising set.
746  *
747  * @param handle Advertising set handle.
748  * @param maxDuration Max duration for advertising (in units of 10ms) - 0 means no limit.
749  * @param maxEvents Max number of events produced during advertising - 0 means no limit.
750  * @return BLE_ERROR_NONE on success.
751  *
752  * @see EventHandler::onAdvertisingStart when the advertising starts.
753  * @see EventHandler::onScanRequestReceived when a scan request is received.
754  * @see EventHandler::onAdvertisingEnd when the advertising ends.
755  * @see EventHandler::onConnectionComplete when the device gets connected
756  * by a peer.
757  */
758  ble_error_t startAdvertising(
759  advertising_handle_t handle,
760  adv_duration_t maxDuration = adv_duration_t::forever(),
761  uint8_t maxEvents = 0
762  );
763 
764  /** Stop advertising given advertising set. This is separate from periodic advertising
765  * which will not be affected.
766  *
767  * @param handle Advertising set handle.
768  * @return BLE_ERROR_NONE on success.
769  */
770  ble_error_t stopAdvertising(advertising_handle_t handle);
771 
772  /** Check if advertising is active for a given advertising set.
773  *
774  * @param handle Advertising set handle.
775  * @return True if advertising is active on this set.
776  */
777  bool isAdvertisingActive(advertising_handle_t handle);
778 #endif // BLE_ROLE_BROADCASTER
779 
780 #if BLE_ROLE_BROADCASTER
781 #if BLE_FEATURE_PERIODIC_ADVERTISING
782  /** Set periodic advertising parameters for a given advertising set.
783  *
784  * @param handle Advertising set handle.
785  * @param periodicAdvertisingIntervalMin Minimum interval for periodic advertising.
786  * @param periodicAdvertisingIntervalMax Maximum interval for periodic advertising.
787  * @param advertiseTxPower Include transmission power in the advertisements.
788  * @return BLE_ERROR_NONE on success.
789  *
790  * @version 5+
791  */
792  ble_error_t setPeriodicAdvertisingParameters(
793  advertising_handle_t handle,
794  periodic_interval_t periodicAdvertisingIntervalMin,
795  periodic_interval_t periodicAdvertisingIntervalMax,
796  bool advertiseTxPower = true
797  );
798 
799  /** Set new periodic advertising payload for a given advertising set.
800  *
801  * @param handle Advertising set handle.
802  * @param payload Advertising payload.
803  * @return BLE_ERROR_NONE on success.
804  *
805  * @note If advertising set is active you may only set payload of length equal or less
806  * than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must
807  * stop the advertising set, set the payload and restart the set. Stopping the set will
808  * cause peers to lose sync on the periodic set.
809  *
810  * @see ble::AdvertisingDataBuilder to build a payload.
811  *
812  * @version 5+
813  */
814  ble_error_t setPeriodicAdvertisingPayload(
815  advertising_handle_t handle,
817  );
818 
819  /** Start periodic advertising for a given set. Periodic advertising will not start until
820  * normal advertising is running but will continue to run after normal advertising has stopped.
821  *
822  * @param handle Advertising set handle.
823  * @return BLE_ERROR_NONE on success.
824  *
825  * @version 5+
826  */
827  ble_error_t startPeriodicAdvertising(advertising_handle_t handle);
828 
829  /** Stop periodic advertising for a given set.
830  *
831  * @param handle Advertising set handle.
832  * @return BLE_ERROR_NONE on success.
833  *
834  * @version 5+
835  */
836  ble_error_t stopPeriodicAdvertising(advertising_handle_t handle);
837 
838  /** Check if periodic advertising is active for a given advertising set.
839  *
840  * @param handle Advertising set handle.
841  * @return True if periodic advertising is active on this set.
842  *
843  * @version 5+
844  */
845  bool isPeriodicAdvertisingActive(advertising_handle_t handle);
846 #endif // BLE_ROLE_BROADCASTER
847 #endif // BLE_FEATURE_PERIODIC_ADVERTISING
848 
849  /* scanning */
850 #if BLE_ROLE_OBSERVER
851  /** Set new scan parameters.
852  *
853  * @param params Scan parameters, @see GapScanParameters for details.
854  * @return BLE_ERROR_NONE on success.
855  */
856  ble_error_t setScanParameters(const ScanParameters &params);
857 
858  /** Start scanning.
859  *
860  * @param duration How long to scan for. Special value 0 means scan forever.
861  * @param filtering Filtering policy.
862  * @param period How long to scan for in single period. If the period is 0 and duration
863  * is nonzero the scan will last for single duration.
864  *
865  * @note When the duration and period parameters are non-zero scanning will last for
866  * the duration within the period. After the scan period has expired a new scan period
867  * will begin and scanning. This will repeat until stopScan() is called.
868  *
869  * @return BLE_ERROR_NONE on success.
870  *
871  * @see EventHandler::onAdvertisingReport to collect advertising reports.
872  * @see EventHandler::onScanTimeout when scanning timeout.
873  */
874  ble_error_t startScan(
875  scan_duration_t duration = scan_duration_t::forever(),
876  duplicates_filter_t filtering = duplicates_filter_t::DISABLE,
877  scan_period_t period = scan_period_t(0)
878  );
879 
880  /**
881  * Stop the ongoing scanning procedure.
882  *
883  * The current scanning parameters remain in effect.
884  *
885  * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
886  */
887  ble_error_t stopScan();
888 #endif // BLE_ROLE_OBSERVER
889 
890 #if BLE_ROLE_OBSERVER
891 #if BLE_FEATURE_PERIODIC_ADVERTISING
892  /** Synchronize with periodic advertising from an advertiser and begin receiving periodic
893  * advertising packets.
894  *
895  * @param peerAddressType Peer address type.
896  * @param peerAddress Peer address.
897  * @param sid Advertiser set identifier.
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 receptions. If this time is
901  * 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  peer_address_type_t peerAddressType,
915  const address_t &peerAddress,
916  uint8_t sid,
917  slave_latency_t maxPacketSkip,
918  sync_timeout_t timeout
919  );
920 
921  /** Synchronize with periodic advertising from an advertiser and begin receiving periodic
922  * advertising packets. Use periodic advertising sync list to determine who to sync with.
923  *
924  * @param maxPacketSkip Number of consecutive periodic advertising packets that the receiver
925  * may skip after successfully receiving a periodic advertising packet.
926  * @param timeout Maximum permitted time between successful receives.
927  * If this time is exceeded, synchronisation is lost.
928  * @return BLE_ERROR_NONE on success.
929  *
930  * @see EventHandler::onPeriodicAdvertisingSyncEstablished when the sync is
931  * effective.
932  * @see EventHandler::onPeriodicAdvertisingReport when data are issued by the
933  * peer.
934  * @see EventHandler::onPeriodicAdvertisingSyncLoss when the sync has been
935  * loss.
936  *
937  * @version 5+
938  */
939  ble_error_t createSync(
940  slave_latency_t maxPacketSkip,
941  sync_timeout_t timeout
942  );
943 
944  /** Cancel sync attempt.
945  *
946  * @return BLE_ERROR_NONE on success.
947  */
948  ble_error_t cancelCreateSync();
949 
950  /** Stop reception of the periodic advertising identified by the handle.
951  *
952  * @param handle Periodic advertising synchronisation handle.
953  * @return BLE_ERROR_NONE on success.
954  */
955  ble_error_t terminateSync(periodic_sync_handle_t handle);
956 
957  /** Add device to the periodic advertiser list. Cannot be called when sync is ongoing.
958  *
959  * @param peerAddressType Peer address type.
960  * @param peerAddress Peer address.
961  * @param sid Advertiser set identifier.
962  * @return BLE_ERROR_NONE on success.
963  */
964  ble_error_t addDeviceToPeriodicAdvertiserList(
965  peer_address_type_t peerAddressType,
966  const address_t &peerAddress,
967  advertising_sid_t sid
968  );
969 
970  /** Remove device from the periodic advertiser list. Cannot be called when sync is ongoing.
971  *
972  * @param peerAddressType Peer address type.
973  * @param peerAddress Peer address.
974  * @param sid Advertiser set identifier.
975  * @return BLE_ERROR_NONE on success.
976  */
977  ble_error_t removeDeviceFromPeriodicAdvertiserList(
978  peer_address_type_t peerAddressType,
979  const address_t &peerAddress,
980  advertising_sid_t sid
981  );
982 
983  /** Remove all devices from periodic advertiser list.
984  *
985  * @return BLE_ERROR_NONE on success.
986  */
987  ble_error_t clearPeriodicAdvertiserList();
988 
989  /** Get number of devices that can be added to the periodic advertiser list.
990  * @return Number of devices that can be added to the periodic advertiser list.
991  */
992  uint8_t getMaxPeriodicAdvertiserListSize();
993 #endif // BLE_ROLE_OBSERVER
994 #endif // BLE_FEATURE_PERIODIC_ADVERTISING
995 
996 #if BLE_ROLE_CENTRAL
997  /**
998  * Initiate a connection to a peer.
999  *
1000  * Once the connection is established an onConnectionComplete in the event handler
1001  * will be called.
1002  *
1003  * @param peerAddressType
1004  * @param peerAddress
1005  * @param connectionParams
1006  *
1007  * @return BLE_ERROR_NONE if connection establishment procedure is started
1008  * successfully. The connectionCallChain (if set) is invoked upon
1009  * a connection event.
1010  *
1011  * @see EventHandler::onConnectionComplete will be called whether the
1012  * connection process succeed or fail.
1013  * @see EventHandler::onDisconnectionComplete is called when the connection
1014  * ends.
1015  */
1016  ble_error_t connect(
1017  peer_address_type_t peerAddressType,
1018  const address_t &peerAddress,
1019  const ConnectionParameters &connectionParams
1020  );
1021 
1022  /** Cancel the connection attempt. This is not guaranteed to succeed. As a result
1023  * onConnectionComplete in the event handler will be called. Check the success parameter
1024  * to see if the connection was created.
1025  *
1026  * @return BLE_ERROR_NONE if the connection attempt has been requested to be cancelled.
1027  * Returns BLE_ERROR_OPERATION_NOT_PERMITTED if no ongoing connection for last used address found.
1028  */
1029  ble_error_t cancelConnect();
1030 #endif // BLE_ROLE_CENTRAL
1031 
1032 #if BLE_FEATURE_CONNECTABLE
1033  /**
1034  * Update connection parameters of an existing connection.
1035  *
1036  * In the central role, this initiates a Link Layer connection parameter
1037  * update procedure. In the peripheral role, this sends the corresponding
1038  * L2CAP request and waits for the central to accept or reject the requested
1039  * connection parameters.
1040  *
1041  * @param connectionHandle The handle of the connection to update.
1042  * @param minConnectionInterval The minimum connection interval requested.
1043  * @param maxConnectionInterval The maximum connection interval requested.
1044  * @param slaveLatency The slave latency requested.
1045  * @param supervision_timeout The supervision timeout requested.
1046  * @param minConnectionEventLength The minimum connection event length requested.
1047  * @param maxConnectionEventLength The maximum connection event length requested.
1048  *
1049  * @return BLE_ERROR_NONE if the request has been sent and false otherwise.
1050  *
1051  * @see EventHandler::onUpdateConnectionParametersRequest when a central
1052  * receives a request to update the connection parameters.
1053  * @see EventHandler::onConnectionParametersUpdateComplete when connection
1054  * parameters have been updated.
1055  *
1056  * @version 4.0+ for central
1057  * @version 4.1+ for peripheral
1058  */
1059  ble_error_t updateConnectionParameters(
1060  connection_handle_t connectionHandle,
1061  conn_interval_t minConnectionInterval,
1062  conn_interval_t maxConnectionInterval,
1063  slave_latency_t slaveLatency,
1064  supervision_timeout_t supervision_timeout,
1065  conn_event_length_t minConnectionEventLength = conn_event_length_t(0),
1066  conn_event_length_t maxConnectionEventLength = conn_event_length_t(0)
1067  );
1068 
1069  /**
1070  * Allows the application to accept or reject a connection parameters update
1071  * request.
1072  *
1073  * If this process is managed by the middleware; new connection parameters
1074  * from a slave are always accepted.
1075  *
1076  * @param userManageConnectionUpdateRequest true to let the application
1077  * manage the process and false to let the middleware manage it.
1078  *
1079  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1080  *
1081  * @version 4.1+
1082  *
1083  * @see EventHandler::onUpdateConnectionParametersRequest when a central
1084  * receives a request to update the connection parameters.
1085  *
1086  * @see acceptConnectionParametersUpdate to accept the request.
1087  * @see rejectConnectionParametersUpdate to reject the request.
1088  */
1089  ble_error_t manageConnectionParametersUpdateRequest(
1090  bool userManageConnectionUpdateRequest
1091  );
1092 
1093  /**
1094  * Accept update of the connection parameters.
1095  *
1096  * The central can adjust the new connection parameters.
1097  *
1098  * @param connectionHandle The handle of the connection that has initiated
1099  * the request.
1100  * @param minConnectionInterval The minimum connection interval to be applied.
1101  * @param maxConnectionInterval The maximum connection interval to be applied.
1102  * @param slaveLatency The slave latency to be applied.
1103  * @param supervision_timeout The supervision timeout to be applied.
1104  * @param minConnectionEventLength The minimum connection event length to be
1105  * applied.
1106  * @param maxConnectionEventLength The maximum connection event length to be
1107  * applied.
1108  *
1109  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1110  *
1111  * @version 4.1+
1112  *
1113  * @see manageConnectionParametersUpdateRequest To let the application
1114  * manage the process.
1115  *
1116  * @see EventHandler::onUpdateConnectionParametersRequest Called when a
1117  * request to update the connection parameters is received.
1118  *
1119  * @see EventHandler::onConnectionParametersUpdateComplete Called when the
1120  * new connection parameters are effective.
1121  */
1122  ble_error_t acceptConnectionParametersUpdate(
1123  connection_handle_t connectionHandle,
1124  conn_interval_t minConnectionInterval,
1125  conn_interval_t maxConnectionInterval,
1126  slave_latency_t slaveLatency,
1127  supervision_timeout_t supervision_timeout,
1128  conn_event_length_t minConnectionEventLength = conn_event_length_t(0),
1129  conn_event_length_t maxConnectionEventLength = conn_event_length_t(0)
1130  );
1131 
1132  /**
1133  * Reject a request to change the connection parameters.
1134  *
1135  * @param connectionHandle The handle of the connection that has initiated
1136  * the request.
1137  *
1138  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1139  *
1140  * @version 4.1+
1141  *
1142  * @see manageConnectionParametersUpdateRequest To let the application
1143  * manage the process.
1144  *
1145  * @see EventHandler::onUpdateConnectionParametersRequest Called when a
1146  * request to update the connection parameters is received.
1147  */
1148  ble_error_t rejectConnectionParametersUpdate(
1149  connection_handle_t connectionHandle
1150  );
1151 
1152  /**
1153  * Initiate a disconnection procedure.
1154  *
1155  * Once the disconnection procedure has completed a
1156  * DisconnectionCallbackParams_t, the event is emitted to handlers that
1157  * have been registered with onDisconnection().
1158  *
1159  * @param[in] reason Reason of the disconnection transmitted to the peer.
1160  * @param[in] connectionHandle Handle of the connection to end.
1161  *
1162  * @return BLE_ERROR_NONE if the disconnection procedure successfully
1163  * started.
1164  *
1165  * @see EventHandler::onDisconnectionComplete when the disconnection is
1166  * effective.
1167  */
1168  ble_error_t disconnect(
1169  connection_handle_t connectionHandle,
1170  local_disconnection_reason_t reason
1171  );
1172 #endif // BLE_FEATURE_CONNECTABLE
1173 #if BLE_FEATURE_PHY_MANAGEMENT
1174  /**
1175  * Read the PHY used by the transmitter and the receiver on a connection.
1176  *
1177  * Once the PHY has been read, it is reported back via the function onPhyRead
1178  * of the event handler registered by the application.
1179  *
1180  * @param connection Handle of the connection for which the PHY being used is
1181  * queried.
1182  *
1183  * @return BLE_ERROR_NONE if the read PHY procedure has been started or an
1184  * appropriate error code.
1185  *
1186  * @version 5+
1187  *
1188  * @see EventHandler::onReadPhy is called when the phy has been read.
1189  */
1190  ble_error_t readPhy(connection_handle_t connection);
1191 
1192  /**
1193  * Set the preferred PHYs to use in a connection.
1194  *
1195  * @param txPhys: Set of PHYs preferred for tx operations. If NULL then no
1196  * preferred PHYs are set and the default value of the subsystem is used.
1197  *
1198  * @param rxPhys: Set of PHYs preferred for rx operations. If NULL then no
1199  * preferred PHYs are set and the default value of the subsystem is used.
1200  *
1201  * @return BLE_ERROR_NONE if the preferences have been set or an appropriate
1202  * error code.
1203  *
1204  * @version 5+
1205  */
1206  ble_error_t setPreferredPhys(
1207  const phy_set_t *txPhys,
1208  const phy_set_t *rxPhys
1209  );
1210 
1211  /**
1212  * Update the PHY used by a connection.
1213  *
1214  * Once the update process has been completed, it is reported back to the
1215  * application via the function onPhyUpdateComplete of the event handler
1216  * registered by the application.
1217  *
1218  * @param connection Handle of the connection to update.
1219  *
1220  * @param txPhys Set of PHYs preferred for tx operations. If NULL then the
1221  * choice is up to the Bluetooth subsystem.
1222  *
1223  * @param rxPhys Set of PHYs preferred for rx operations. If NULL then the
1224  * choice is up to the Bluetooth subsystem.
1225  *
1226  * @param codedSymbol Number of symbols used to code a bit when le coded is
1227  * used. If the value is UNDEFINED then the choice is up to the Bluetooth
1228  * subsystem.
1229  *
1230  * @return BLE_ERROR_NONE if the update PHY procedure has been successfully
1231  * started or an error code.
1232  *
1233  * @see EventHandler::onPhyUpdateComplete is called when the phy used by the
1234  * connection has been updated.
1235  */
1236  ble_error_t setPhy(
1237  connection_handle_t connection,
1238  const phy_set_t *txPhys,
1239  const phy_set_t *rxPhys,
1240  coded_symbol_per_bit_t codedSymbol
1241  );
1242 #endif // BLE_FEATURE_PHY_MANAGEMENT
1243 
1244 #if BLE_FEATURE_PRIVACY
1245  /**
1246  * Enable or disable privacy mode of the local device.
1247  *
1248  * When privacy is enabled, the system use private addresses while it scans,
1249  * advertises or initiate a connection. The device private address is
1250  * renewed every 15 minutes.
1251  *
1252  * @par Configuration
1253  *
1254  * The privacy feature can be configured with the help of the functions
1255  * setPeripheralPrivacyConfiguration and setCentralPrivacyConfiguration
1256  * which respectively set the privacy configuration of the peripheral and
1257  * central role.
1258  *
1259  * @par Default configuration of peripheral role
1260  *
1261  * By default private resolvable addresses are used for all procedures;
1262  * including advertisement of nonconnectable packets. Connection request
1263  * from an unknown initiator with a private resolvable address triggers the
1264  * pairing procedure.
1265  *
1266  * @par Default configuration of central role
1267  *
1268  * By default private resolvable addresses are used for all procedures;
1269  * including active scanning. Addresses present in advertisement packet are
1270  * resolved and advertisement packets are forwarded to the application
1271  * even if the advertiser private address is unknown.
1272  *
1273  * @par Initialization of the privacy subsystem
1274  *
1275  * When privacy is enabled, the system generates new resolvable and non
1276  * resolvable private addresses. Scan, Advertising and Connecting to a peer
1277  * won't be available until the generation process completes. When addresses
1278  * have been generated, the application is notified that privacy
1279  * initialisation as completed with a call to EventHandler::onPrivacyEnabled .
1280  *
1281  * @param[in] enable Should be set to true to enable the privacy mode and
1282  * false to disable it.
1283  *
1284  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1285  */
1286  ble_error_t enablePrivacy(bool enable);
1287 
1288 #if BLE_ROLE_BROADCASTER
1289  /**
1290  * Set the privacy configuration used by the peripheral role.
1291  *
1292  * @param[in] configuration The configuration to set.
1293  *
1294  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1295  */
1296  ble_error_t setPeripheralPrivacyConfiguration(
1297  const peripheral_privacy_configuration_t *configuration
1298  );
1299 
1300  /**
1301  * Get the privacy configuration used by the peripheral role.
1302  *
1303  * @param[out] configuration The variable filled with the current
1304  * configuration.
1305  *
1306  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1307  */
1308  ble_error_t getPeripheralPrivacyConfiguration(
1309  peripheral_privacy_configuration_t *configuration
1310  );
1311 #endif // BLE_ROLE_BROADCASTER
1312 
1313 #if BLE_ROLE_OBSERVER
1314  /**
1315  * Set the privacy configuration used by the central role.
1316  *
1317  * @param[in] configuration The configuration to set.
1318  *
1319  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1320  */
1321  ble_error_t setCentralPrivacyConfiguration(
1322  const central_privacy_configuration_t *configuration
1323  );
1324 
1325  /**
1326  * Get the privacy configuration used by the central role.
1327  *
1328  * @param[out] configuration The variable filled with the current
1329  * configuration.
1330  *
1331  * @return BLE_ERROR_NONE in case of success or an appropriate error code.
1332  */
1333  ble_error_t getCentralPrivacyConfiguration(
1334  central_privacy_configuration_t *configuration
1335  );
1336 #endif // BLE_ROLE_OBSERVER
1337 #endif // BLE_FEATURE_PRIVACY
1338 
1339 #if BLE_FEATURE_WHITELIST
1340  /**
1341  * Get the maximum size of the whitelist.
1342  *
1343  * @return Maximum size of the whitelist.
1344  */
1345  uint8_t getMaxWhitelistSize() const;
1346 
1347  /**
1348  * Get the Link Layer to use the internal whitelist when scanning,
1349  * advertising or initiating a connection depending on the filter policies.
1350  *
1351  * @param[in,out] whitelist Define the whitelist instance which is used
1352  * to store the whitelist requested. In input, the caller provisions memory.
1353  *
1354  * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
1355  * copied into the supplied reference.
1356  */
1357  ble_error_t getWhitelist(whitelist_t &whitelist) const;
1358 
1359  /**
1360  * Set the value of the whitelist to be used during GAP procedures.
1361  *
1362  * @param[in] whitelist A reference to a whitelist containing the addresses
1363  * to be copied to the internal whitelist.
1364  *
1365  * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
1366  * populated with the addresses in the given whitelist.
1367  *
1368  * @note The whitelist must not contain non-resolvable addresses. This
1369  * results in a @ref BLE_ERROR_INVALID_PARAM because the remote peer might
1370  * change its private address at any time, and it is not possible to resolve
1371  * it.
1372  *
1373  * @note If the input whitelist is larger than @ref getMaxWhitelistSize(),
1374  * then @ref BLE_ERROR_PARAM_OUT_OF_RANGE is returned.
1375  */
1376  ble_error_t setWhitelist(const whitelist_t &whitelist);
1377 
1378 #endif // BLE_FEATURE_WHITELIST
1379 
1380  /**
1381  * Fetch the current address and its type.
1382  *
1383  * @param[out] typeP Type of the current address set.
1384  * @param[out] address Value of the current address.
1385  *
1386  * @note If privacy is enabled the device address may be unavailable to
1387  * application code.
1388  *
1389  * @return BLE_ERROR_NONE on success.
1390  */
1391  ble_error_t getAddress(
1392  own_address_type_t &typeP,
1393  address_t &address
1394  );
1395 
1396  /**
1397  * Return the type of a random address.
1398  *
1399  * @param[in] address The random address to retrieve the type from. The
1400  * address must be ordered in little endian.
1401  *
1402  * @param[out] addressType Type of the address to fill.
1403  *
1404  * @return BLE_ERROR_NONE in case of success or BLE_ERROR_INVALID_PARAM if
1405  * the address in input was not identifiable as a random address.
1406  */
1407  static ble_error_t getRandomAddressType(
1408  ble::address_t address,
1409  ble::random_address_type_t *addressType
1410  );
1411 
1412  /**
1413  * Reset the Gap instance.
1414  *
1415  * Reset process starts by notifying all registered shutdown event handlers
1416  * that the Gap instance is about to be shut down. Then, it clears all Gap state
1417  * of the associated object and then cleans the state present in the vendor
1418  * implementation.
1419  *
1420  * This function is meant to be overridden in the platform-specific
1421  * subclass. Nevertheless, the subclass only resets its
1422  * state and not the data held in Gap members. This is achieved by a
1423  * call to Gap::reset() from the subclass' reset() implementation.
1424  *
1425  * @return BLE_ERROR_NONE on success.
1426  *
1427  * @note Currently, a call to reset() does not reset the advertising and
1428  * scan parameters to default values.
1429  */
1430  ble_error_t reset();
1431 
1432  /**
1433  * Register a Gap shutdown event handler.
1434  *
1435  * The handler is called when the Gap instance is about to shut down.
1436  * It is usually issued after a call to BLE::shutdown().
1437  *
1438  * @param[in] callback Shutdown event handler to register.
1439  *
1440  * @note To unregister a shutdown event handler, use
1441  * onShutdown().detach(callback).
1442  */
1443  void onShutdown(const GapShutdownCallback_t &callback);
1444 
1445  /**
1446  * Register a Gap shutdown event handler.
1447  *
1448  * @param[in] objPtr Instance used to invoke @p memberPtr.
1449  * @param[in] memberPtr Shutdown event handler to register.
1450  */
1451  template<typename T>
1452  void onShutdown(T *objPtr, void (T::*memberPtr)(const Gap *)) {
1453  onShutdown(GapShutdownCallback_t(objPtr, memberPtr));
1454  }
1455 
1456  /**
1457  * Access the callchain of shutdown event handler.
1458  *
1459  * @note To register callbacks, use onShutdown().add(callback).
1460  *
1461  * @note To unregister callbacks, use onShutdown().detach(callback).
1462  *
1463  * @return A reference to the shutdown event callback chain.
1464  */
1465  GapShutdownCallbackChain_t &onShutdown();
1466 
1467 #if !defined(DOXYGEN_ONLY)
1468  /*
1469  * Constructor from the private implementation.
1470  */
1471  Gap(impl::Gap* impl) : impl(impl) {}
1472 
1473  /*
1474  * Restrict copy and move.
1475  */
1476  Gap(const Gap&) = delete;
1477  Gap& operator=(const Gap&) = delete;
1478 
1479  /*
1480  * API reserved for the controller driver to set the random static address.
1481  * Setting a new random static address while the controller is operating is
1482  * forbidden by the Bluetooth specification.
1483  */
1484  ble_error_t setRandomStaticAddress(const ble::address_t& address);
1485 
1486  ble::address_t getRandomStaticAddress();
1487 #endif // !defined(DOXYGEN_ONLY)
1488 
1489 private:
1490  impl::Gap* impl;
1491 };
1492 
1493 /**
1494  * @}
1495  * @}
1496  */
1497 
1498 } // namespace ble
1499 
1500 /** @deprecated Use the namespaced ble::Gap instead of the global Gap. */
1501 using ble::Gap;
1502 
1503 #endif // BLE_GAP_GAP_H
Event generated when a connection initiation ends (successfully or not).
Definition: Events.h:211
Function like object adapter over freestanding and member functions.
Event produced when advertising ends.
Definition: Events.h:615
virtual void onPrivacyEnabled()
Function invoked when the privacy subsystem has been enabled and is ready to be used.
Definition: Gap.h:557
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:862
Event generated when periodic advertising sync is lost.
Definition: Events.h:545
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:490
Event produced when advertising start.
Definition: Events.h:583
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:441
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:420
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:545
Representation of a whitelist of addresses.
virtual void onAdvertisingStart(const AdvertisingStartEvent &event)
Called when advertising starts.
Definition: Gap.h:324
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:588
Parameters defining the connection initiation process.
virtual void onAdvertisingEnd(const AdvertisingEndEvent &event)
Called when advertising ends.
Definition: Gap.h:340
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:362
virtual void onConnectionParametersUpdateComplete(const ConnectionParametersUpdateCompleteEvent &event)
Called when connection parameters have been updated.
Definition: Gap.h:455
uint16_t slaveLatency
Number of connection events the slave can drop if it has nothing to communicate to the master...
Definition: Gap.h:596
Event generated when you first receive a periodic advertisement.
Definition: Events.h:373
Preferred connection parameter display in Generic Access Service.
Definition: Gap.h:571
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:612
Type that describes a peer device address type.
Event generated when scan times out.
Definition: Events.h:576
Event produced when a disconnection is complete.
Definition: Events.h:750
uint16_t minConnectionInterval
Minimum interval between two connection events allowed for a connection.
Definition: Gap.h:579
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:468
Function like object hosting a list of FunctionPointerWithContext.
Event generated when periodic advertising packet is received.
Definition: Events.h:474
void onShutdown(T *objPtr, void(T::*memberPtr)(const Gap *))
Register a Gap shutdown event handler.
Definition: Gap.h:1452
Event received when a peer wants to change the connection parameters.
Definition: Events.h:789
virtual void onPeriodicAdvertisingSyncLoss(const PeriodicAdvertisingSyncLoss &event)
Called when a periodic advertising sync has been lost.
Definition: Gap.h:405
virtual void onPeriodicAdvertisingReport(const PeriodicAdvertisingReportEvent &event)
Called when a periodic advertising packet is received.
Definition: Gap.h:390
virtual void onAdvertisingReport(const AdvertisingReportEvent &event)
Called when a scanner receives an advertising or a scan response packet.
Definition: Gap.h:351
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:524
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:699
virtual void onPeriodicAdvertisingSyncEstablished(const PeriodicAdvertisingSyncEstablishedEvent &event)
Called when first advertising packet in periodic advertising is received.
Definition: Gap.h:375
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.