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