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