Gap.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef MBED_BLE_GAP_H__
00018 #define MBED_BLE_GAP_H__
00019 
00020 #include "BLETypes.h"
00021 #include "BLEProtocol.h"
00022 #include "GapAdvertisingData.h"
00023 #include "GapAdvertisingParams.h"
00024 #include "GapScanningParams.h"
00025 #include "GapEvents.h"
00026 #include "CallChainOfFunctionPointersWithContext.h"
00027 #include "FunctionPointerWithContext.h "
00028 #include "platform/mbed_toolchain.h"
00029 
00030 /* Forward declarations for classes that are only used for pointers or
00031    references. */
00032 class GapAdvertisingParams;
00033 class GapScanningParams;
00034 class GapAdvertisingData;
00035 
00036 /**
00037  * @addtogroup ble
00038  * @{
00039  * @addtogroup gap
00040  * @{
00041  */
00042 
00043 /**
00044  * Define device discovery, connection and link management procedures.
00045  *
00046  * - Device discovery: A device can advertise nearby peers of its existence,
00047  * identity and capabilities. Similarly, a device can scan its environment to
00048  * find advertising peers. The information acquired during the scan helps to
00049  * identify peers and understand their use. A scanner may acquire more information
00050  * about an advertising peer by sending a scan request. If the peer accepts scan
00051  * requests, it may reply with additional information about its state.
00052  *
00053  * - Connection: A bluetooth device can establish a connection to a connectable
00054  * advertising peer. Once the connection is established, both devices can
00055  * communicate using the GATT protocol. The GATT protocol allows connected
00056  * devices to expose a set of states that the other peer can discover, read and write.
00057  *
00058  * - Link Management: Connected devices may drop the connection and may adjust
00059  * connection parameters according to the power envelop needed for their
00060  * application.
00061  *
00062  * @par Accessing gap
00063  *
00064  * Instance of a Gap class for a given BLE device should be accessed using
00065  * BLE::gap(). The reference returned remains valid until the BLE instance
00066  * shut down (see BLE::shutdown()).
00067  *
00068  * @code
00069  * // assuming ble_device has been initialized
00070  * BLE& ble_device;
00071  *
00072  * Gap& gap = ble_device.gap();
00073  * @endcode
00074  *
00075  * @par Advertising
00076  *
00077  * Advertising consists of broadcasting at a regular interval a small amount of
00078  * data containing valuable informations about the device. These packets may be
00079  * scanned by peer devices listening on BLE advertising channels.
00080  *
00081  * Scanners may also request additional information from a device advertising by
00082  * sending a scan request. If the broadcaster accepts scan requests, it can reply
00083  * with a scan response packet containing additional information.
00084  *
00085  * @code
00086  * // assuming gap has been initialized
00087  * Gap& gap;
00088  *
00089  * // construct the packet to advertise
00090  * GapAdvertisingData advertising_data;
00091  *
00092  * // Add advertiser flags
00093  * advertising_data.addFlags(
00094  *    GapAdvertisingData::LE_GENERAL_DISCOVERABLE |
00095  *    GapAdvertisingData::BREDR_NOT_SUPPORTED
00096  * );
00097  *
00098  * // Add the name of the device to the advertising data
00099  * static const uint8_t device_name[] = "HRM";
00100  * advertising_data.addData(
00101  *     GapAdvertisingData::COMPLETE_LOCAL_NAME,
00102  *     device_name,
00103  *     sizeof(device_name)
00104  * );
00105  *
00106  * // set the advertising data in the gap instance, they will be used when
00107  * // advertising starts.
00108  * gap.setAdvertisingPayload(advertising_data);
00109  *
00110  * // Configure the advertising procedure
00111  * GapAdvertisingParams advertising_params(
00112  *     GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED, // type of advertising
00113  *     GapAdvertisingParams::MSEC_TO_ADVERTISEMENT_DURATION_UNITS(1000), // interval
00114  *     0 // The advertising procedure will not timeout
00115  * );
00116  *
00117  * gap.setAdvertisingParams(advertising_params);
00118  *
00119  * // start the advertising procedure, the device will advertise its flag and the
00120  * // name "HRM". Other peers will also be allowed to connect to it.
00121  * gap.startAdvertising();
00122  * @endcode
00123  *
00124  * @par Privacy
00125  *
00126  * Privacy is a feature that allows a device to avoid being tracked by other
00127  * (untrusted) devices. The device achieves it by periodically generating a
00128  * new random address. The random address may be a resolvable random address,
00129  * enabling trusted devices to recognise it as belonging to the same
00130  * device. These trusted devices receive an Identity Resolution Key (IRK)
00131  * during pairing. This is handled by the SecurityManager and relies on the
00132  * other device accepting and storing the IRK.
00133  *
00134  * Privacy needs to be enabled by calling enablePrivacy() after having
00135  * initialised the SecurityManager since privacy requires SecurityManager
00136  * to handle IRKs. The behaviour of privacy enabled devices is set by
00137  * using setCentralPrivacyConfiguration() which specifies what the device
00138  * should be with devices using random addresses. Random addresses
00139  * generated by privacy enabled device can be of two types: resolvable
00140  * (by devices who have the IRK) and unresolvable. Unresolvable addresses
00141  * can't be used for connecting and connectable advertising therefore a
00142  * resolvable one will be used for these regardless of the privacy
00143  * configuration.
00144  *
00145  * @par Scanning
00146  *
00147  * Scanning consist of listening for peer advertising packets. From a scan, a
00148  * device can identify devices available in its environment.
00149  *
00150  * If the device scans actively, then it will send scan request to scannable
00151  * advertisers and collect their scan response.
00152  *
00153  * @code
00154  * // assuming gap has been initialized
00155  * Gap& gap;
00156  *
00157  * // Handle advertising packet by dumping their content
00158  * void handle_advertising_packet(const AdvertisementCallbackParams_t* packet)
00159  * {
00160  *    printf("Packet received: \r\n");
00161  *    printf("  - peer address: %02X:%02X:%02X:%02X:%02X:%02X\r\n",
00162  *           packet->peerAddr[5], packet->peerAddr[4], packet->peerAddr[3],
00163  *           packet->peerAddr[2], packet->peerAddr[1], packet->peerAddr[0]);
00164  *    printf("  - rssi: %d", packet->rssi);
00165  *    printf("  - scan response: %s\r\n", packet->isScanresponse ? "true" : "false");
00166  *    printf("  - advertising type: %d\r\n", packet->type);
00167  *    printf("  - advertising type: %d\r\n", packet->type);
00168  *    printf("  - Advertising data: \r\n");
00169  *
00170  *    // parse advertising data, it is a succession of AD structures where
00171  *    // the first byte is the size of the AD structure, the second byte the
00172  *    // type of the data and remaining bytes are the value.
00173  *
00174  *    for (size_t i = 0; i < packet->advertisingDataLen; i += packet->advertisingData[i]) {
00175  *        printf("    - type: 0X%02X, data: ", packet->advertisingData[i + 1]);
00176  *        for (size_t j = 0; j < packet->advertisingData[i] - 2; ++j) {
00177  *            printf("0X%02X ", packet->advertisingData[i + 2 + j]);
00178  *        }
00179  *        printf("\r\n");
00180  *    }
00181  * }
00182  *
00183  * // set the scan parameters
00184  * gap.setScanParams(
00185  *      100, // interval between two scan window in ms
00186  *      50,  // scan window: period during which the device listen for advertising packets.
00187  *      0,   // the scan process never ends
00188  *      true // the device sends scan request to scannable peers.
00189  * );
00190  *
00191  * // start the scan procedure
00192  * gap.startScan(handle_advertising_packet);
00193  * @endcode
00194  *
00195  * @par Connection event handling
00196  *
00197  * A peer may connect device advertising connectable packets. The
00198  * advertising procedure ends as soon as the device is connected.
00199  *
00200  * A device accepting a connection request from a peer is named a peripheral,
00201  * and the device initiating the connection is named a central.
00202  *
00203  * Peripheral and central receive a connection event when the connection is
00204  * effective.
00205  *
00206  * @code
00207  * Gap& gap;
00208  *
00209  * // handle connection event
00210  * void when_connected(const ConnectionCallbackParams_t *connection_event) {
00211  *    // If this callback is entered, then the connection to a peer is effective.
00212  * }
00213  *
00214  * // register connection event handler, which will be invoked whether the device
00215  * // acts as a central or a peripheral
00216  * gap.onConnection(when_connected);
00217  * @endcode
00218  *
00219  * @par Connection initiation
00220  *
00221  * Connection is initiated central devices.
00222  *
00223  * @code
00224  * // assuming gap has been initialized
00225  * Gap& gap;
00226  *
00227  * // Handle the connection event
00228  * void handle_connection(const ConnectionCallbackParams_t* connection_event)
00229  * {
00230  *    // event handling
00231  * }
00232  *
00233  * // Handle advertising packet: connect to the first connectable device
00234  * void handle_advertising_packet(const AdvertisementCallbackParams_t* packet)
00235  * {
00236  *    if (packet->type != GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED) {
00237  *       return;
00238  *    }
00239  *
00240  *    // register connection event handler
00241  *    gap.onConnection(handle_connection);
00242  *
00243  *    Gap::ConnectionParams_t connection_parameters = {
00244  *       50, // min connection interval
00245  *       100, // max connection interval
00246  *       0, // slave latency
00247  *       600 // connection supervision timeout
00248  *    };
00249  *
00250  *    // scan parameter used to find the device to connect to
00251  *    GapScanningParams scanning_params(
00252  *      100, // interval
00253  *      100, // window
00254  *      0, // timeout
00255  *      false // active
00256  *    );
00257  *
00258  *    // Initiate the connection procedure
00259  *    gap.connect(
00260  *       packet->peerAddr,
00261  *       packet->addressType,
00262  *       &connection_parameters,
00263  *       &scanning_params
00264  *    );
00265  * }
00266  *
00267  * // set the scan parameters
00268  * gap.setScanParams(
00269  *      100, // interval between two scan window in ms
00270  *      50,  // scan window: period during which the device listen for advertising packets.
00271  *      0,   // the scan process never ends
00272  *      true // the device sends scan request to scannable peers.
00273  * );
00274  *
00275  * // start the scan procedure
00276  * gap.startScan(handle_advertising_packet);
00277  * @endcode
00278  *
00279  * @par disconnection
00280  *
00281  * The application code initiates a disconnection when it calls the
00282  * disconnect(Handle_t, DisconnectionReason_t) function.
00283  *
00284  * Disconnection may also be initiated by the remote peer or the local
00285  * controller/stack. To catch all disconnection events, application code may
00286  * set up an handler taking care of disconnection events by calling
00287  * onDisconnection().
00288  */
00289 class Gap {
00290     /*
00291      * DEPRECATION ALERT: all of the APIs in this `public` block are deprecated.
00292      * They have been relocated to the class BLEProtocol.
00293      */
00294 public:
00295     /**
00296      * Address-type for BLEProtocol addresses.
00297      *
00298      * @deprecated Use BLEProtocol::AddressType_t instead.
00299      */
00300     typedef BLEProtocol::AddressType_t AddressType_t;
00301 
00302     /**
00303      * Address-type for BLEProtocol addresses.
00304      *
00305      * @deprecated Use BLEProtocol::AddressType_t instead.
00306      */
00307     typedef BLEProtocol::AddressType_t addr_type_t;
00308 
00309     /**
00310      * Address-type for BLEProtocol addresses.
00311      *
00312      * @deprecated Use BLEProtocol::AddressType_t instead. The following
00313      * constants have been left in their deprecated state to transparently
00314      * support existing applications that may have used Gap::ADDR_TYPE_*.
00315      */
00316     enum DeprecatedAddressType_t {
00317         ADDR_TYPE_PUBLIC = BLEProtocol::AddressType::PUBLIC,
00318         ADDR_TYPE_RANDOM_STATIC = BLEProtocol::AddressType::RANDOM_STATIC,
00319         ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_RESOLVABLE,
00320         ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE
00321     };
00322 
00323     /**
00324      * Length (in octets) of the BLE MAC address.
00325      */
00326     static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN;
00327 
00328     /**
00329      * 48-bit address, LSB format.
00330      *
00331      * @deprecated Use BLEProtocol::AddressBytes_t instead.
00332      */
00333     typedef BLEProtocol::AddressBytes_t Address_t;
00334 
00335     /**
00336      * 48-bit address, LSB format.
00337      *
00338      * @deprecated Use BLEProtocol::AddressBytes_t instead.
00339      */
00340     typedef BLEProtocol::AddressBytes_t address_t;
00341 
00342 public:
00343     /**
00344      * Enumeration of possible timeout sources.
00345      */
00346     enum TimeoutSource_t {
00347         /**
00348          * Advertising timeout.
00349          */
00350         TIMEOUT_SRC_ADVERTISING = 0x00,
00351 
00352         /**
00353          * Security request timeout.
00354          */
00355         TIMEOUT_SRC_SECURITY_REQUEST = 0x01,
00356 
00357         /**
00358          * Scanning timeout.
00359          */
00360         TIMEOUT_SRC_SCAN = 0x02,
00361 
00362         /**
00363          * Connection timeout.
00364          */
00365         TIMEOUT_SRC_CONN = 0x03,
00366     };
00367 
00368     /**
00369      * Enumeration of disconnection reasons.
00370      *
00371      * @attention There might be a mismatch between the disconnection reason
00372      * passed to disconnect() and the disconnection event generated locally
00373      * because the disconnection reason passed to disconnect() is the
00374      * disconnection reason to be transmitted to the peer.
00375      */
00376     enum DisconnectionReason_t {
00377 
00378         /**
00379          * GAP or GATT failed to authenticate the peer.
00380          */
00381         AUTHENTICATION_FAILURE = 0x05,
00382 
00383         /**
00384          * The connection timed out.
00385          *
00386          * @attention shall not be used as a reason in disconnect().
00387          */
00388         CONNECTION_TIMEOUT = 0x08,
00389 
00390         /**
00391          * Connection terminated by the user.
00392          */
00393         REMOTE_USER_TERMINATED_CONNECTION = 0x13,
00394 
00395         /**
00396          * Remote device terminated connection due to low resources.
00397          */
00398         REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14,
00399 
00400         /**
00401          * Remote device terminated connection due to power off.
00402          */
00403         REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15,
00404 
00405         /**
00406          * Indicate that the local user or the internal
00407          * Bluetooth subsystem terminated the connection.
00408          *
00409          * @attention shall not be used as a reason in disconnect().
00410          */
00411         LOCAL_HOST_TERMINATED_CONNECTION = 0x16,
00412 
00413         /**
00414          * Connection parameters were unacceptable.
00415          */
00416         CONN_INTERVAL_UNACCEPTABLE = 0x3B,
00417     };
00418 
00419     /**
00420      * Advertising policy filter modes.
00421      *
00422      * @see Bluetooth Core Specification 4.2 (Vol. 6), Part B, Section 4.3.2.
00423      */
00424     enum AdvertisingPolicyMode_t {
00425         /**
00426          * The whitelist is not used to filter peer request during advertising.
00427          */
00428         ADV_POLICY_IGNORE_WHITELIST = 0,
00429 
00430         /**
00431          * The whitelist is used to filter peer scan requests.
00432          */
00433         ADV_POLICY_FILTER_SCAN_REQS = 1,
00434 
00435         /**
00436          * The whitelist is used to filter peer connection requests.
00437          */
00438         ADV_POLICY_FILTER_CONN_REQS = 2,
00439 
00440         /**
00441          * The whitelist is used to filter peer scan and connection requests.
00442          */
00443         ADV_POLICY_FILTER_ALL_REQS  = 3,
00444     };
00445 
00446     /**
00447      * Scanning policy filter mode.
00448      *
00449      * @see Bluetooth Core Specification 4.2 (Vol. 6), Part B, Section 4.3.3.
00450      */
00451     enum ScanningPolicyMode_t {
00452         /**
00453          * The whitelist is not used for scanning operations.
00454          */
00455         SCAN_POLICY_IGNORE_WHITELIST = 0,
00456 
00457         /**
00458          * The whitelist is used to filter incoming advertising.
00459          */
00460         SCAN_POLICY_FILTER_ALL_ADV = 1,
00461     };
00462 
00463     /**
00464      * Connection initiation policy filter mode.
00465      *
00466      * @see Bluetooth Core Specification 4.2 (vol. 6), Part B, Section 4.4.4.
00467      */
00468     enum InitiatorPolicyMode_t {
00469         /**
00470          * Connection can be initiated to any device.
00471          */
00472         INIT_POLICY_IGNORE_WHITELIST = 0,
00473 
00474         /**
00475          * Connection initiation is restricted to the devices present in the
00476          * whitelist.
00477          */
00478         INIT_POLICY_FILTER_ALL_ADV = 1,
00479     };
00480 
00481     /**
00482      * Representation of a whitelist of addresses.
00483      */
00484     struct Whitelist_t {
00485         /**
00486          * Pointer to the array of the addresses composing the whitelist.
00487          */
00488         BLEProtocol::Address_t *addresses;
00489 
00490         /**
00491          * Number addresses in this whitelist.
00492          */
00493         uint8_t size;
00494 
00495         /**
00496          * Capacity of the array holding the addresses.
00497          */
00498         uint8_t capacity;
00499     };
00500 
00501     /**
00502      * Description of the states of the device.
00503      */
00504     struct GapState_t {
00505         /**
00506          * If set, the device is currently advertising.
00507          */
00508         unsigned advertising : 1;
00509 
00510         /**
00511          * If set, the device is connected to at least one other peer.
00512          */
00513         unsigned connected : 1;
00514     };
00515 
00516     /**
00517      * Opaque value type representing a connection handle.
00518      *
00519      * It is used to identify to refer to a specific connection across Gap,
00520      * GattClient and GattEvent API.
00521      *
00522      * @note instances are generated by in the connection callback.
00523      */
00524     typedef ble::connection_handle_t Handle_t;
00525 
00526     /**
00527      * Enumeration of random address types.
00528      */
00529     typedef ble::random_address_type_t RandomAddressType_t;
00530 
00531     /**
00532      * Enumeration of peer address types
00533      */
00534     typedef ble::peer_address_type_t PeerAddressType_t;
00535 
00536     /**
00537      * Parameters of a BLE connection.
00538      */
00539     typedef struct {
00540         /**
00541          * Minimum interval between two connection events allowed for a
00542          * connection.
00543          *
00544          * It shall be less than or equal to maxConnectionInterval. This value,
00545          * in units of 1.25ms, is included in the range [0x0006 : 0x0C80].
00546          */
00547         uint16_t minConnectionInterval;
00548 
00549         /**
00550          * Maximum interval between two connection events allowed for a
00551          * connection.
00552          *
00553          * It shall be greater than or equal to minConnectionInterval. This
00554          * value is in unit of 1.25ms and is in the range [0x0006 : 0x0C80].
00555          */
00556         uint16_t maxConnectionInterval;
00557 
00558         /**
00559          * Number of connection events the slave can drop if it has nothing to
00560          * communicate to the master.
00561          *
00562          * This value shall be in the range [0x0000 : 0x01F3].
00563          */
00564         uint16_t slaveLatency;
00565 
00566         /**
00567          * Link supervision timeout for the connection.
00568          *
00569          * Time after which the connection is considered lost if the device
00570          * didn't receive a packet from its peer.
00571          *
00572          * It is larger than:
00573          *        (1 + slaveLatency) * maxConnectionInterval * 2
00574          *
00575          * This value is in the range [0x000A : 0x0C80] and is in unit of
00576          * 10 ms.
00577          *
00578          * @note maxConnectionInterval is in ms in the formulae above.
00579          */
00580         uint16_t connectionSupervisionTimeout;
00581     } ConnectionParams_t;
00582 
00583     /**
00584      * Enumeration of GAP roles.
00585      *
00586      * @note The BLE API does not express the broadcaster and scanner roles.
00587      *
00588      * @attention A device can fulfill different roles concurrently.
00589      */
00590     enum Role_t {
00591         /**
00592          * Peripheral Role.
00593          *
00594          * The device can advertise and it can be connected by a central. It
00595          * acts as a slave when connected.
00596          *
00597          * @note A peripheral is a broadcaster.
00598          */
00599         PERIPHERAL = 0x1,
00600 
00601         /**
00602          * Central Role.
00603          *
00604          * The device can scan and initiate connection to peripherals. It
00605          * acts as the master when a connection is established.
00606          *
00607          * @note A central is a scanner.
00608          */
00609         CENTRAL = 0x2,
00610     };
00611 
00612     /**
00613      * Representation of a scanned advertising packet.
00614      *
00615      * Instances of this type are passed to the callback registered in
00616      * startScan().
00617      */
00618     struct AdvertisementCallbackParams_t {
00619         /**
00620          * Default constructor.
00621          */
00622         AdvertisementCallbackParams_t();
00623 
00624         /**
00625          * BLE address of the device that has advertised the packet.
00626          */
00627         BLEProtocol::AddressBytes_t peerAddr;
00628 
00629         /**
00630          * RSSI value of the packet.
00631          */
00632         int8_t rssi;
00633 
00634         /**
00635          * Flag indicating if the packet is a response to a scan request.
00636          */
00637         bool isScanResponse;
00638 
00639         /**
00640          * Type of advertisement.
00641          */
00642         GapAdvertisingParams::AdvertisingType_t type;
00643 
00644         /**
00645          * Length of the advertisement data.
00646          */
00647         uint8_t advertisingDataLen;
00648 
00649         /**
00650          * Pointer to the advertisement packet's data.
00651          */
00652         const uint8_t *advertisingData;
00653 
00654         /**
00655          * Type of the address received.
00656          *
00657          * @deprecated AddressType_t do not carry enough information to be used
00658          * when privacy is enabled. Use peerAddressType instead.
00659          *
00660          * @note This value should be used in the connect function to establish
00661          * a connection with the peer that has sent this advertisement packet.
00662          */
00663         MBED_DEPRECATED_SINCE(
00664             "mbed-os-5.9.0",
00665             "addressType won't work in connect when privacy is enabled; please"
00666             "use peerAddrType"
00667         )
00668         AddressType_t addressType;
00669 
00670         /**
00671          * Type of the address received.
00672          *
00673          * @note This value should be used in the connect function to establish
00674          * a connection with the peer that has sent this advertisement packet.
00675          */
00676         PeerAddressType_t peerAddrType;
00677     };
00678 
00679     /**
00680      * Type of the callback handling scanned advertisement packets.
00681      *
00682      * @see Gap::startScan().
00683      */
00684     typedef FunctionPointerWithContext<const AdvertisementCallbackParams_t *>
00685         AdvertisementReportCallback_t ;
00686 
00687     /**
00688      * Connection events.
00689      *
00690      * It contains all the information related to a newly established connection.
00691      *
00692      * Instances of this structure are passed to handlers that
00693      * Gap::onConnection() registers when a connection is established.
00694      */
00695     struct ConnectionCallbackParams_t {
00696         /**
00697          * Connection handle.
00698          */
00699         Handle_t handle;
00700 
00701         /**
00702          * Connection Role of the local device.
00703          */
00704         Role_t role;
00705 
00706         /**
00707          * Type of the address the peer uses.
00708          *
00709          * @deprecated The type BLEProtocol::AddressType_t is not suitable when
00710          * privacy is enabled. Use peerAddressType instead.
00711          */
00712         MBED_DEPRECATED_SINCE(
00713             "mbed-os-5.9",
00714             "The type BLEProtocol::AddressType_t is not suitable when privacy is "
00715             "enabled. Use peerAddressType instead."
00716         )
00717         BLEProtocol::AddressType_t peerAddrType;
00718 
00719         /**
00720          * Address of the peer.
00721          */
00722         BLEProtocol::AddressBytes_t peerAddr;
00723 
00724         /**
00725          * Address type of the local device.
00726          */
00727         BLEProtocol::AddressType_t  ownAddrType;
00728 
00729         /**
00730          * Address of the local device.
00731          *
00732          * @deprecated The local address used for the connection may not be known,
00733          * Therefore this field is not reliable.
00734          *
00735          * @note All bytes of the address are set to 0 if not applicable
00736          */
00737         MBED_DEPRECATED_SINCE(
00738             "mbed-os-5.9",
00739             "A Bluetooth controller is not supposed to return the address it used"
00740             "to connect. With privacy enabled the controller address may be unknown"
00741             "to the host. There is no replacement for this deprecation."
00742         )
00743         BLEProtocol::AddressBytes_t ownAddr;
00744 
00745         /**
00746          * Connection parameters.
00747          */
00748         const ConnectionParams_t   *connectionParams;
00749 
00750         /**
00751          * Resolvable address used by the peer.
00752          *
00753          * @note All bytes of the address are set to 0 if not applicable
00754          */
00755         BLEProtocol::AddressBytes_t peerResolvableAddr;
00756 
00757         /**
00758          * resolvable address of the local device.
00759          *
00760          * @note All bytes of the address are set to 0 if not applicable
00761          */
00762         BLEProtocol::AddressBytes_t localResolvableAddr;
00763 
00764         /**
00765          * Type of the address the peer uses.
00766          */
00767         PeerAddressType_t peerAddressType;
00768 
00769         /**
00770          * Construct an instance of ConnectionCallbackParams_t.
00771          *
00772          * @param[in] handleIn Value to assign to handle.
00773          * @param[in] roleIn Value to assign to role.
00774          * @param[in] peerAddrTypeIn Value to assign to peerAddrType.
00775          * @param[in] peerAddrIn Value to assign to peerAddr.
00776          * @param[in] ownAddrTypeIn Value to assign to ownAddrType.
00777          * @param[in] ownAddrIn Value to assign to ownAddr. This may be NULL.
00778          * @param[in] connectionParamsIn Value to assign to connectionParams.
00779          * @param[in] peerResolvableAddrIn Value to assign to peerResolvableAddr.
00780          * @param[in] localResolvableAddrIn Value to assign to localResolvableAddr.
00781          *
00782          * @note Constructor is not meant to be called by user code.
00783          * The BLE API vendor code generates ConnectionCallbackParams_t.
00784          */
00785         ConnectionCallbackParams_t(
00786             Handle_t handleIn,
00787             Role_t roleIn,
00788             PeerAddressType_t peerAddrTypeIn,
00789             const uint8_t *peerAddrIn,
00790             BLEProtocol::AddressType_t ownAddrTypeIn,
00791             const uint8_t *ownAddrIn,
00792             const ConnectionParams_t *connectionParamsIn,
00793             const uint8_t *peerResolvableAddrIn = NULL,
00794             const uint8_t *localResolvableAddrIn = NULL
00795         );
00796 
00797         /**
00798          * Construct an instance of ConnectionCallbackParams_t.
00799          *
00800          * @param[in] handleIn Value to assign to handle.
00801          * @param[in] roleIn Value to assign to role.
00802          * @param[in] peerAddrTypeIn Value to assign to peerAddrType.
00803          * @param[in] peerAddrIn Value to assign to peerAddr.
00804          * @param[in] ownAddrTypeIn Value to assign to ownAddrType.
00805          * @param[in] ownAddrIn Value to assign to ownAddr.
00806          * @param[in] connectionParamsIn Value to assign to connectionParams.
00807          * @param[in] peerResolvableAddrIn Value to assign to peerResolvableAddr.
00808          * @param[in] localResolvableAddrIn Value to assign to localResolvableAddr.
00809          *
00810          * @note Constructor is not meant to be called by user code.
00811          * The BLE API vendor code generates ConnectionCallbackParams_t.
00812          *
00813          * @deprecated The type BLEProtocol::AddressType_t is not suitable when
00814          * privacy is enabled. Use the constructor that accepts a
00815          * PeerAddressType_t instead.
00816          */
00817         MBED_DEPRECATED_SINCE(
00818             "mbed-os-5.9.0",
00819             "The type BLEProtocol::AddressType_t is not suitable when privacy is "
00820             "enabled. Use the constructor that accepts a PeerAddressType_t instead."
00821         )
00822         ConnectionCallbackParams_t(
00823             Handle_t handleIn,
00824             Role_t roleIn,
00825             BLEProtocol::AddressType_t peerAddrTypeIn,
00826             const uint8_t *peerAddrIn,
00827             BLEProtocol::AddressType_t ownAddrTypeIn,
00828             const uint8_t *ownAddrIn,
00829             const ConnectionParams_t *connectionParamsIn,
00830             const uint8_t *peerResolvableAddrIn = NULL,
00831             const uint8_t *localResolvableAddrIn = NULL
00832         );
00833 
00834     private:
00835         void constructor_helper(
00836             const uint8_t *peerAddrIn,
00837             const uint8_t *ownAddrIn,
00838             const uint8_t *peerResolvableAddrIn,
00839             const uint8_t *localResolvableAddrIn
00840         );
00841     };
00842 
00843     /**
00844      * Disconnection event.
00845      *
00846      * Instances of this event are passed to callbacks registered with
00847      * Gap::onDisconnection() when a connection ends.
00848      *
00849      * @note Constructor is not meant to be called by user code.
00850      * The BLE API vendor code generates ConnectionCallbackParams_t.
00851      */
00852     struct DisconnectionCallbackParams_t {
00853         /**
00854          * ID of the connection that has ended.
00855          */
00856         Handle_t handle;
00857 
00858         /**
00859          * Reason of the disconnection.
00860          */
00861         DisconnectionReason_t reason;
00862 
00863         /**
00864          * Construct a DisconnectionCallbackParams_t.
00865          *
00866          * @param[in] handleIn Value assigned to handle.
00867          * @param[in] reasonIn Value assigned to reason.
00868          */
00869         DisconnectionCallbackParams_t(
00870             Handle_t handleIn,
00871             DisconnectionReason_t reasonIn
00872         ) : handle(handleIn),
00873             reason(reasonIn)
00874         {}
00875     };
00876 
00877     /**
00878      * Privacy Configuration of the peripheral role.
00879      *
00880      * @note This configuration also applies to the broadcaster role configuration.
00881      */
00882     struct PeripheralPrivacyConfiguration_t {
00883         /**
00884          * Indicates if non resolvable random address should be used when the
00885          * peripheral advertises non connectable packets.
00886          *
00887          * Resolvable random address continues to be used for connectable packets.
00888          */
00889         bool use_non_resolvable_random_address;
00890 
00891         /**
00892          * Resolution strategy for initiator resolvable addresses when a
00893          * connection request is received.
00894          */
00895         enum ResolutionStrategy {
00896             /**
00897              * Do not resolve the address of the initiator and accept the
00898              * connection request.
00899              */
00900             DO_NOT_RESOLVE,
00901 
00902             /**
00903              * If a bond is present in the secure database and the address
00904              * resolution fail then reject the connection request with the error
00905              * code AUTHENTICATION_FAILLURE.
00906              */
00907             REJECT_NON_RESOLVED_ADDRESS,
00908 
00909             /**
00910              * Perform the pairing procedure if the initiator resolvable
00911              * address failed the resolution process.
00912              */
00913             PERFORM_PAIRING_PROCEDURE,
00914 
00915             /**
00916              * Perform the authentication procedure if the initiator resolvable
00917              * address failed the resolution process.
00918              */
00919             PERFORM_AUTHENTICATION_PROCEDURE
00920         };
00921 
00922         /**
00923          * Connection strategy to use when a connection request contains a
00924          * private resolvable address.
00925          */
00926         ResolutionStrategy resolution_strategy;
00927     };
00928 
00929     /**
00930      * Privacy Configuration of the central role.
00931      *
00932      * @note This configuration is also used when the local device operates as
00933      * an observer.
00934      */
00935     struct CentralPrivacyConfiguration_t {
00936         /**
00937          * Indicates if non resolvable random address should be used when the
00938          * central or observer sends scan request packets.
00939          *
00940          * Resolvable random address continue to be used for connection requests.
00941          */
00942         bool use_non_resolvable_random_address;
00943 
00944 
00945         /**
00946          * Resolution strategy of resolvable addresses received in advertising
00947          * packets.
00948          */
00949         enum ResolutionStrategy {
00950             /**
00951              * Do not resolve the address received in advertising packets.
00952              */
00953             DO_NOT_RESOLVE,
00954 
00955             /**
00956              * Resolve the resolvable addresses in the advertising packet and
00957              * forward advertising packet to the application independently of
00958              * the address resolution procedure result.
00959              */
00960             RESOLVE_AND_FORWARD,
00961 
00962             /**
00963              * Filter out packets containing a resolvable that cannot be resolved
00964              * by this device.
00965              *
00966              * @note Filtering is applied if the local device contains at least
00967              * one bond.
00968              */
00969             RESOLVE_AND_FILTER
00970         };
00971 
00972         /**
00973          * Resolution strategy applied to advertising packets received by the
00974          * local device.
00975          */
00976         ResolutionStrategy resolution_strategy;
00977     };
00978 
00979     /**
00980      * Number of microseconds in 1.25 milliseconds.
00981      */
00982     static const uint16_t UNIT_1_25_MS  = 1250;
00983 
00984     static const PeripheralPrivacyConfiguration_t
00985         default_peripheral_privacy_configuration;
00986 
00987     static const CentralPrivacyConfiguration_t
00988         default_central_privacy_configuration;
00989 
00990     /**
00991      * Convert milliseconds into 1.25ms units.
00992      *
00993      * This function may be used to convert ms time of connection intervals into
00994      * the format expected for connection parameters.
00995      *
00996      * @param[in] durationInMillis The duration in milliseconds.
00997      *
00998      * @return The duration in unit of 1.25ms.
00999      */
01000     static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis)
01001     {
01002         return (durationInMillis * 1000) / UNIT_1_25_MS;
01003     }
01004 
01005     /**
01006      * Timeout event handler.
01007      *
01008      * @see Gap::onTimeout().
01009      */
01010     typedef FunctionPointerWithContext<TimeoutSource_t>  TimeoutEventCallback_t;
01011 
01012     /**
01013      * Callchain of timeout event handlers.
01014      *
01015      * @see Gap::onTimeout().
01016      */
01017     typedef CallChainOfFunctionPointersWithContext<TimeoutSource_t> 
01018         TimeoutEventCallbackChain_t;
01019 
01020     /**
01021      * Connection event handler.
01022      *
01023      * @see Gap::onConnection().
01024      */
01025     typedef FunctionPointerWithContext<const ConnectionCallbackParams_t *> 
01026         ConnectionEventCallback_t;
01027 
01028     /**
01029      * Callchain of connection event handlers.
01030      *
01031      * @see Gap::onConnection().
01032      */
01033     typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> 
01034         ConnectionEventCallbackChain_t;
01035 
01036     /**
01037      * Disconnection event handler.
01038      *
01039      * @see Gap::onDisconnection().
01040      */
01041     typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> 
01042         DisconnectionEventCallback_t;
01043 
01044     /**
01045      * Callchain of disconnection event handlers.
01046      *
01047      * @see Gap::onDisconnection().
01048      */
01049     typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> 
01050         DisconnectionEventCallbackChain_t;
01051 
01052     /**
01053      * Radio notification event handler.
01054      *
01055      * @see Gap::onRadioNotification().
01056      */
01057     typedef FunctionPointerWithContext<bool>  RadioNotificationEventCallback_t;
01058 
01059     /**
01060      * Gap shutdown event handler.
01061      *
01062      * @see Gap::onShutdown().
01063      */
01064     typedef FunctionPointerWithContext<const Gap *>  GapShutdownCallback_t;
01065 
01066     /**
01067      * Callchain of gap shutdown event handler.
01068      *
01069      * @see Gap::onShutdown().
01070      */
01071     typedef CallChainOfFunctionPointersWithContext<const Gap *> 
01072         GapShutdownCallbackChain_t;
01073 
01074     /*
01075      * The following functions are meant to be overridden in the platform-specific subclass.
01076      */
01077 public:
01078     /**
01079      * Set the device MAC address and type.
01080      *
01081      * The address set is used in subsequent GAP operations: scanning,
01082      * advertising and connection initiation.
01083      *
01084      * @param[in] type Type of the address to set.
01085      * @param[in] address Value of the address to set. It is ordered in
01086      * little endian. This parameter is not considered if the address type
01087      * is RANDOM_PRIVATE_RESOLVABLE or RANDOM_PRIVATE_NON_RESOLVABLE. For those
01088      * types of address, the BLE API itself generates the address.
01089      *
01090      * @note Some implementation may refuse to set a new PUBLIC address.
01091      * @note Random static address set does not change.
01092      *
01093      * @deprecated Starting with mbed-os-5.9.0 this function is deprecated and
01094      * address management is delegated to implementation. Implementations may or
01095      * may not continue to support this function. Compliance with the Bluetooth
01096      * specification and unification of behaviour between implementations are
01097      * the key reasons behind this change:
01098      *   - Many implementations do not allow changing of the public address.
01099      *   Therefore programs relying on this function are not portable across BLE
01100      *   implementations.
01101      *   - The Bluetooth specification forbid replacement of the random static
01102      *   address; this address can be set once and only once: at startup.
01103      *   Depending on the underlying implementation the random address may or
01104      *   may not have been set automatically at startup; therefore update of the
01105      *   Random Static address after ble initialisation may be a fault. As a
01106      *   result calls to this function were not portable.
01107      *   Furthermore replacement of the random static address silently
01108      *   invalidates the bond stored in the secure database.
01109 
01110      * @return BLE_ERROR_NONE on success.
01111      */
01112     MBED_DEPRECATED_SINCE(
01113         "mbed-os-5.9.0",
01114         "Non portable API, use enablePrivacy to enable use of private addresses"
01115     )
01116     virtual ble_error_t setAddress(
01117         BLEProtocol::AddressType_t type,
01118         const BLEProtocol::AddressBytes_t address
01119     ) {
01120         /* avoid compiler warnings about unused variables */
01121         (void)type;
01122         (void)address;
01123 
01124         /* Requesting action from porter(s): override this API if this capability
01125            is supported. */
01126         return BLE_ERROR_NOT_IMPLEMENTED;
01127     }
01128 
01129     /**
01130      * Fetch the current address and its type.
01131      *
01132      * @param[out] typeP Type of the current address set.
01133      * @param[out] address Value of the current address.
01134      *
01135      * @note If privacy is enabled the device address may be unavailable to
01136      * application code.
01137      *
01138      * @return BLE_ERROR_NONE on success.
01139      */
01140     virtual ble_error_t getAddress(
01141         BLEProtocol::AddressType_t *typeP,
01142         BLEProtocol::AddressBytes_t address
01143     ) {
01144         /* Avoid compiler warnings about unused variables. */
01145         (void)typeP;
01146         (void)address;
01147 
01148         /* Requesting action from porter(s): override this API if this capability
01149            is supported. */
01150         return BLE_ERROR_NOT_IMPLEMENTED;
01151     }
01152 
01153     /**
01154      * Return the type of a random address.
01155      *
01156      * @param[in] address The random address to retrieve the type from. The
01157      * address must be ordered in little endian.
01158      *
01159      * @param[out] addressType Type of the address to fill.
01160      *
01161      * @return BLE_ERROR_NONE in case of success or BLE_ERROR_INVALID_PARAM if
01162      * the address in input was not identifiable as a random address.
01163      */
01164     static ble_error_t getRandomAddressType(
01165         const BLEProtocol::AddressBytes_t address,
01166         RandomAddressType_t* addressType
01167     );
01168 
01169     /**
01170      * Get the minimum advertising interval in milliseconds, which can be used
01171      * for connectable advertising types.
01172      *
01173      * @return Minimum Advertising interval in milliseconds for connectable
01174      * undirected and connectable directed advertising types.
01175      */
01176     virtual uint16_t getMinAdvertisingInterval(void) const
01177     {
01178         /* Requesting action from porter(s): override this API if this capability
01179            is supported. */
01180         return 0;
01181     }
01182 
01183     /**
01184      * Get the minimum advertising interval in milliseconds, which can be
01185      * used for nonconnectable advertising type.
01186      *
01187      * @return Minimum Advertising interval in milliseconds for scannable
01188      * undirected and nonconnectable undirected event types.
01189      */
01190     virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const
01191     {
01192         /* Requesting action from porter(s): override this API if this capability
01193            is supported. */
01194         return 0;
01195     }
01196 
01197     /**
01198      * Get the maximum advertising interval in milliseconds.
01199      *
01200      * @return Maximum Advertising interval in milliseconds.
01201      */
01202     virtual uint16_t getMaxAdvertisingInterval(void) const
01203     {
01204         /* Requesting action from porter(s): override this API if this capability
01205            is supported. */
01206         return 0xFFFF;
01207     }
01208 
01209     /**
01210      * Stop the ongoing advertising procedure.
01211      *
01212      * @note The current advertising parameters remain in effect.
01213      *
01214      * @retval BLE_ERROR_NONE if the advertising procedure has been successfully
01215      * stopped.
01216      */
01217     virtual ble_error_t stopAdvertising(void)
01218     {
01219         /* Requesting action from porter(s): override this API if this capability
01220            is supported. */
01221         return BLE_ERROR_NOT_IMPLEMENTED;
01222     }
01223 
01224     /**
01225      * Stop the ongoing scanning procedure.
01226      *
01227      * The current scanning parameters remain in effect.
01228      *
01229      * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
01230      */
01231     virtual ble_error_t stopScan()
01232     {
01233         /* Requesting action from porter(s): override this API if this capability
01234            is supported. */
01235         return BLE_ERROR_NOT_IMPLEMENTED;
01236     }
01237 
01238     /**
01239      * Initiate a connection to a peer.
01240      *
01241      * Once the connection is established, a ConnectionCallbackParams_t event is
01242      * emitted to handlers that have been registered with onConnection().
01243      *
01244      * @param[in] peerAddr MAC address of the peer. It must be in LSB format.
01245      * @param[in] peerAddrType Address type of the peer. It is usually obtained
01246      * from advertising frames.
01247      * @param[in] connectionParams Connection parameters to use.
01248      * @param[in] scanParams Scan parameters used to find the peer.
01249      *
01250      * @return BLE_ERROR_NONE if connection establishment procedure is started
01251      * successfully. The connectionCallChain (if set) is invoked upon
01252      * a connection event.
01253      */
01254     virtual ble_error_t connect(
01255         const BLEProtocol::AddressBytes_t peerAddr,
01256         PeerAddressType_t peerAddrType,
01257         const ConnectionParams_t *connectionParams,
01258         const GapScanningParams *scanParams
01259     ) {
01260         /* Avoid compiler warnings about unused variables. */
01261         (void)peerAddr;
01262         (void)peerAddrType;
01263         (void)connectionParams;
01264         (void)scanParams;
01265 
01266         /* Requesting action from porter(s): override this API if this capability
01267            is supported. */
01268         return BLE_ERROR_NOT_IMPLEMENTED;
01269     }
01270 
01271     /**
01272      * Initiate a connection to a peer.
01273      *
01274      * Once the connection is established, a ConnectionCallbackParams_t event is
01275      * emitted to handlers that have been registered with onConnection().
01276      *
01277      * @param[in] peerAddr MAC address of the peer. It must be in LSB format.
01278      * @param[in] peerAddrType Address type of the peer.
01279      * @param[in] connectionParams Connection parameters to use.
01280      * @param[in] scanParams Scan parameters used to find the peer.
01281      *
01282      * @deprecated BLEProtocol::AddressType_t is not able to to carry accurate
01283      * meaning when privacy is in use. Please Uses the connect overload that
01284      * accept a PeerAddressType_t as the peer address type.
01285      *
01286      * @return BLE_ERROR_NONE if connection establishment procedure is started
01287      * successfully. The connectionCallChain (if set) is invoked upon
01288      * a connection event.
01289      */
01290     MBED_DEPRECATED_SINCE(
01291         "mbed-os-5.9.0",
01292         "This function won't work if privacy is enabled; You must use the overload "
01293         "accepting PeerAddressType_t."
01294     )
01295     virtual ble_error_t connect(
01296         const BLEProtocol::AddressBytes_t peerAddr,
01297         BLEProtocol::AddressType_t peerAddrType,
01298         const ConnectionParams_t *connectionParams,
01299         const GapScanningParams *scanParams
01300     ) {
01301         /* Avoid compiler warnings about unused variables. */
01302         (void)peerAddr;
01303         (void)peerAddrType;
01304         (void)connectionParams;
01305         (void)scanParams;
01306 
01307         /* Requesting action from porter(s): override this API if this capability
01308            is supported. */
01309         return BLE_ERROR_NOT_IMPLEMENTED;
01310     }
01311 
01312     /**
01313      * Initiate a connection to a peer.
01314      *
01315      * @see connect()
01316      *
01317      * @deprecated  This funtion overloads Gap::connect(
01318      *      const BLEProtocol::Address_t peerAddr,
01319      *      BLEProtocol::AddressType_t peerAddrType,
01320      *      const ConnectionParams_t *connectionParams,
01321      *      const GapScanningParams *scanParams
01322      * )
01323      * to maintain backward compatibility for changes from Gap::AddressType_t to
01324      * BLEProtocol::AddressType_t.
01325      */
01326     MBED_DEPRECATED("Gap::DeprecatedAddressType_t is deprecated, use BLEProtocol::AddressType_t instead")
01327     ble_error_t connect(
01328         const BLEProtocol::AddressBytes_t peerAddr,
01329         DeprecatedAddressType_t peerAddrType,
01330         const ConnectionParams_t *connectionParams,
01331         const GapScanningParams *scanParams
01332     );
01333 
01334     /**
01335      * Initiate a disconnection procedure.
01336      *
01337      * Once the disconnection procedure has completed a
01338      * DisconnectionCallbackParams_t, the event is emitted to handlers that
01339      * have been registered with onDisconnection().
01340      *
01341      * @param[in] reason Reason of the disconnection transmitted to the peer.
01342      * @param[in] connectionHandle Handle of the connection to end.
01343      *
01344      * @return  BLE_ERROR_NONE if the disconnection procedure successfully
01345      * started.
01346      */
01347     virtual ble_error_t disconnect(
01348         Handle_t connectionHandle, DisconnectionReason_t reason
01349     ) {
01350         /* avoid compiler warnings about unused variables */
01351         (void)connectionHandle;
01352         (void)reason;
01353 
01354         /* Requesting action from porter(s): override this API if this capability
01355            is supported. */
01356         return BLE_ERROR_NOT_IMPLEMENTED;
01357     }
01358 
01359     /**
01360      * Initiate a disconnection procedure.
01361      *
01362      * @deprecated This version of disconnect() doesn't take a connection handle.
01363      * It works reliably only for stacks that are limited to a single connection.
01364      * Use Gap::disconnect(Handle_t connectionHandle, DisconnectionReason_t reason)
01365      * instead.
01366      *
01367      * @param[in] reason The reason for disconnection; to be sent back to the peer.
01368      *
01369      * @return BLE_ERROR_NONE if disconnection was successful.
01370      */
01371     MBED_DEPRECATED("Use disconnect(Handle_t, DisconnectionReason_t) instead.")
01372     virtual ble_error_t disconnect(DisconnectionReason_t reason) {
01373         /* Avoid compiler warnings about unused variables. */
01374         (void)reason;
01375 
01376         /* Requesting action from porter(s): override this API if this capability
01377            is supported. */
01378         return BLE_ERROR_NOT_IMPLEMENTED;
01379     }
01380 
01381     /**
01382      * Returned the preferred connection parameters exposed in the GATT Generic
01383      * Access Service.
01384      *
01385      * @param[out] params Structure where the parameters are stored.
01386      *
01387      * @return BLE_ERROR_NONE if the parameters were successfully filled into
01388      * @p params.
01389      */
01390     virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params)
01391     {
01392         /* Avoid compiler warnings about unused variables. */
01393         (void)params;
01394 
01395         /* Requesting action from porter(s): override this API if this capability
01396            is supported. */
01397         return BLE_ERROR_NOT_IMPLEMENTED;
01398     }
01399 
01400     /**
01401      * Set the value of the preferred connection parameters exposed in the GATT
01402      * Generic Access Service.
01403      *
01404      * A connected peer may read the characteristic exposing these parameters
01405      * and request an update of the connection parameters to accomodate the
01406      * local device.
01407      *
01408      * @param[in] params Value of the preferred connection parameters.
01409      *
01410      * @return BLE_ERROR_NONE if the preferred connection params were set
01411      * correctly.
01412      */
01413     virtual ble_error_t setPreferredConnectionParams(
01414         const ConnectionParams_t *params
01415     ) {
01416         /* Avoid compiler warnings about unused variables. */
01417         (void)params;
01418 
01419         /* Requesting action from porter(s): override this API if this capability
01420            is supported. */
01421         return BLE_ERROR_NOT_IMPLEMENTED;
01422     }
01423 
01424     /**
01425      * Update connection parameters of an existing connection.
01426      *
01427      * In the central role, this initiates a Link Layer connection parameter
01428      * update procedure. In the peripheral role, this sends the corresponding
01429      * L2CAP request and waits for the central to perform the procedure.
01430      *
01431      * @param[in] handle Connection Handle.
01432      * @param[in] params Pointer to desired connection parameters.
01433      *
01434      * @return BLE_ERROR_NONE if the connection parameters were updated correctly.
01435      */
01436     virtual ble_error_t updateConnectionParams(
01437         Handle_t handle,
01438         const ConnectionParams_t *params
01439     ) {
01440         /* avoid compiler warnings about unused variables */
01441         (void)handle;
01442         (void)params;
01443 
01444         /* Requesting action from porter(s): override this API if this capability
01445            is supported. */
01446         return BLE_ERROR_NOT_IMPLEMENTED;
01447     }
01448 
01449     /**
01450      * Set the value of the device name characteristic in the Generic Access
01451      * Service.
01452      *
01453      * @param[in] deviceName The new value for the device-name. This is a
01454      * UTF-8 encoded, <b>NULL-terminated</b> string.
01455      *
01456      * @return BLE_ERROR_NONE if the device name was set correctly.
01457      */
01458     virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
01459         /* Avoid compiler warnings about unused variables. */
01460         (void)deviceName;
01461 
01462         /* Requesting action from porter(s): override this API if this capability
01463            is supported. */
01464         return BLE_ERROR_NOT_IMPLEMENTED;
01465     }
01466 
01467     /**
01468      * Get the value of the device name characteristic in the Generic Access
01469      * Service.
01470      *
01471      * To obtain the length of the deviceName value, this function is
01472      * invoked with the @p deviceName parameter set to NULL.
01473      *
01474      * @param[out] deviceName Pointer to an empty buffer where the UTF-8
01475      * <b>non NULL-terminated</b> string is placed.
01476      *
01477      * @param[in,out] lengthP Length of the @p deviceName buffer. If the device
01478      * name is successfully copied, then the length of the device name
01479      * string (excluding the null terminator) replaces this value.
01480      *
01481      * @return BLE_ERROR_NONE if the device name was fetched correctly from the
01482      * underlying BLE stack.
01483      *
01484      * @note If the device name is longer than the size of the supplied buffer,
01485      * length returns the complete device name length and not the number of
01486      * bytes actually returned in deviceName. The application may use this
01487      * information to retry with a suitable buffer size.
01488      */
01489     virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP)
01490     {
01491         /* avoid compiler warnings about unused variables */
01492         (void)deviceName;
01493         (void)lengthP;
01494 
01495         /* Requesting action from porter(s): override this API if this capability
01496            is supported. */
01497         return BLE_ERROR_NOT_IMPLEMENTED;
01498     }
01499 
01500     /**
01501      * Set the value of the appearance characteristic in the GAP service.
01502      *
01503      * @param[in] appearance The new value for the device-appearance.
01504      *
01505      * @return BLE_ERROR_NONE if the new appearance was set correctly.
01506      */
01507     virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance)
01508     {
01509         /* Avoid compiler warnings about unused variables. */
01510         (void)appearance;
01511 
01512         /* Requesting action from porter(s): override this API if this capability
01513            is supported. */
01514         return BLE_ERROR_NOT_IMPLEMENTED;
01515     }
01516 
01517     /**
01518      * Get the value of the appearance characteristic in the GAP service.
01519      *
01520      * @param[out] appearanceP The current device-appearance value.
01521      *
01522      * @return BLE_ERROR_NONE if the device-appearance was fetched correctly
01523      * from the underlying BLE stack.
01524      */
01525     virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP)
01526     {
01527         /* Avoid compiler warnings about unused variables. */
01528         (void)appearanceP;
01529 
01530         /* Requesting action from porter(s): override this API if this capability
01531            is supported. */
01532         return BLE_ERROR_NOT_IMPLEMENTED;
01533     }
01534 
01535     /**
01536      * Set the radio's transmit power.
01537      *
01538      * @param[in] txPower Radio's transmit power in dBm.
01539      *
01540      * @return BLE_ERROR_NONE if the new radio's transmit power was set
01541      * correctly.
01542      */
01543     virtual ble_error_t setTxPower(int8_t txPower)
01544     {
01545         /* Avoid compiler warnings about unused variables. */
01546         (void)txPower;
01547 
01548         /* Requesting action from porter(s): override this API if this capability
01549            is supported. */
01550         return BLE_ERROR_NOT_IMPLEMENTED;
01551     }
01552 
01553     /**
01554      * Query the underlying stack for allowed Tx power values.
01555      *
01556      * @param[out] valueArrayPP Receive the immutable array of Tx values.
01557      * @param[out] countP Receive the array's size.
01558      */
01559     virtual void getPermittedTxPowerValues(
01560         const int8_t **valueArrayPP, size_t *countP
01561     ) {
01562         /* Avoid compiler warnings about unused variables. */
01563         (void)valueArrayPP;
01564         (void)countP;
01565 
01566         /* Requesting action from porter(s): override this API if this capability
01567            is supported. */
01568         *countP = 0;
01569     }
01570 
01571     /**
01572      * Get the maximum size of the whitelist.
01573      *
01574      * @return Maximum size of the whitelist.
01575      *
01576      * @note If using Mbed OS, you can configure the size of the whitelist by
01577      * setting the YOTTA_CFG_WHITELIST_MAX_SIZE macro in your yotta config file.
01578      */
01579     virtual uint8_t getMaxWhitelistSize(void) const
01580     {
01581         return 0;
01582     }
01583 
01584     /**
01585      * Get the Link Layer to use the internal whitelist when scanning,
01586      * advertising or initiating a connection depending on the filter policies.
01587      *
01588      * @param[in,out] whitelist Define the whitelist instance which is used
01589      * to store the whitelist requested. In input, the caller provisions memory.
01590      *
01591      * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
01592      * copied into the supplied reference.
01593      */
01594     virtual ble_error_t getWhitelist(Whitelist_t &whitelist) const
01595     {
01596         (void) whitelist;
01597         return BLE_ERROR_NOT_IMPLEMENTED;
01598     }
01599 
01600     /**
01601      * Set the value of the whitelist to be used during GAP procedures.
01602      *
01603      * @param[in] whitelist A reference to a whitelist containing the addresses
01604      * to be copied to the internal whitelist.
01605      *
01606      * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
01607      * populated with the addresses in the given whitelist.
01608      *
01609      * @note The whitelist must not contain addresses of type @ref
01610      * BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE. This
01611      * results in a @ref BLE_ERROR_INVALID_PARAM because the remote peer might
01612      * change its private address at any time, and it is not possible to resolve
01613      * it.
01614      *
01615      * @note If the input whitelist is larger than @ref getMaxWhitelistSize(),
01616      * then @ref BLE_ERROR_PARAM_OUT_OF_RANGE is returned.
01617      */
01618     virtual ble_error_t setWhitelist(const Whitelist_t &whitelist)
01619     {
01620         (void) whitelist;
01621         return BLE_ERROR_NOT_IMPLEMENTED;
01622     }
01623 
01624     /**
01625      * Set the advertising policy filter mode to be used during the next
01626      * advertising procedure.
01627      *
01628      * @param[in] mode New advertising policy filter mode.
01629      *
01630      * @return BLE_ERROR_NONE if the specified policy filter mode was set
01631      * successfully.
01632      */
01633     virtual ble_error_t setAdvertisingPolicyMode(AdvertisingPolicyMode_t mode)
01634     {
01635         (void) mode;
01636         return BLE_ERROR_NOT_IMPLEMENTED;
01637     }
01638 
01639     /**
01640      * Set the scan policy filter mode to be used during the next scan procedure.
01641      *
01642      * @param[in] mode New scan policy filter mode.
01643      *
01644      * @return BLE_ERROR_NONE if the specified policy filter mode was set
01645      * successfully.
01646      */
01647     virtual ble_error_t setScanningPolicyMode(ScanningPolicyMode_t mode)
01648     {
01649         (void) mode;
01650         return BLE_ERROR_NOT_IMPLEMENTED;
01651     }
01652 
01653     /**
01654      * Set the initiator policy filter mode to be used during the next connection
01655      * initiation.
01656      *
01657      * @param[in] mode New initiator policy filter mode.
01658      *
01659      * @return BLE_ERROR_NONE if the specified policy filter mode was set
01660      * successfully.
01661      */
01662     virtual ble_error_t setInitiatorPolicyMode(InitiatorPolicyMode_t mode)
01663     {
01664         (void) mode;
01665         return BLE_ERROR_NOT_IMPLEMENTED;
01666     }
01667 
01668     /**
01669      * Get the current advertising policy filter mode.
01670      *
01671      * @return The current advertising policy filter mode.
01672      */
01673     virtual AdvertisingPolicyMode_t getAdvertisingPolicyMode(void) const
01674     {
01675         return ADV_POLICY_IGNORE_WHITELIST;
01676     }
01677 
01678     /**
01679      * Get the current scan policy filter mode.
01680      *
01681      * @return The current scan policy filter mode.
01682      */
01683     virtual ScanningPolicyMode_t getScanningPolicyMode(void) const
01684     {
01685         return SCAN_POLICY_IGNORE_WHITELIST;
01686     }
01687 
01688     /**
01689      * Get the current initiator policy filter mode.
01690      *
01691      * @return The current scan policy filter mode.
01692      */
01693     virtual InitiatorPolicyMode_t getInitiatorPolicyMode(void) const
01694     {
01695         return INIT_POLICY_IGNORE_WHITELIST;
01696     }
01697 
01698 protected:
01699     /* Override the following in the underlying adaptation layer to provide the
01700       functionality of scanning. */
01701 
01702     /**
01703      * Start scanning procedure in the underlying BLE stack.
01704      *
01705      * @param[in] scanningParams Parameters of the scan procedure.
01706      *
01707      * @return BLE_ERROR_NONE if the scan procedure was successfully started.
01708      */
01709     virtual ble_error_t startRadioScan(const GapScanningParams &scanningParams)
01710     {
01711         (void)scanningParams;
01712         /* Requesting action from porter(s): override this API if this capability
01713            is supported. */
01714         return BLE_ERROR_NOT_IMPLEMENTED;
01715     }
01716 
01717     /*
01718      * APIs with nonvirtual implementations.
01719      */
01720 public:
01721     /**
01722      * Get the current advertising and connection states of the device.
01723      *
01724      * @return The current GAP state of the device.
01725      */
01726     GapState_t getState(void) const
01727     {
01728         return state;
01729     }
01730 
01731     /**
01732      * Set the advertising type to use during the advertising procedure.
01733      *
01734      * @param[in] advType New type of advertising to use.
01735      */
01736     void setAdvertisingType(GapAdvertisingParams::AdvertisingType_t advType)
01737     {
01738         _advParams.setAdvertisingType(advType);
01739     }
01740 
01741     /**
01742      * Set the advertising interval.
01743      *
01744      * @param[in] interval Advertising interval in units of milliseconds.
01745      * Advertising is disabled if interval is 0. If interval is smaller than
01746      * the minimum supported value, then the minimum supported value is used
01747      * instead. This minimum value can be discovered using
01748      * getMinAdvertisingInterval().
01749      *
01750      * This field must be set to 0 if connectionMode is equal
01751      * to ADV_CONNECTABLE_DIRECTED.
01752      *
01753      * @note  Decreasing this value allows central devices to detect a
01754      * peripheral faster, at the expense of the radio using more power
01755      * due to the higher data transmit rate.
01756      */
01757     void setAdvertisingInterval(uint16_t interval)
01758     {
01759         if (interval == 0) {
01760             stopAdvertising();
01761         } else if (interval < getMinAdvertisingInterval()) {
01762             interval = getMinAdvertisingInterval();
01763         }
01764         _advParams.setInterval(interval);
01765     }
01766 
01767     /**
01768      * Set the advertising duration.
01769      *
01770      * A timeout event is genenerated once the advertising period expired.
01771      *
01772      * @param[in] timeout Advertising timeout (in seconds) between 0x1 and 0x3FFF.
01773      * The special value 0 may be used to disable the advertising timeout.
01774      */
01775     void setAdvertisingTimeout(uint16_t timeout)
01776     {
01777         _advParams.setTimeout(timeout);
01778     }
01779 
01780     /**
01781      * Start the advertising procedure.
01782      *
01783      * @return BLE_ERROR_NONE if the device started advertising successfully.
01784      */
01785     ble_error_t startAdvertising(void)
01786     {
01787         ble_error_t rc;
01788         if ((rc = startAdvertising(_advParams)) == BLE_ERROR_NONE) {
01789             state.advertising = 1;
01790         }
01791         return rc;
01792     }
01793 
01794     /**
01795      * Reset the value of the advertising payload advertised.
01796      */
01797     void clearAdvertisingPayload(void)
01798     {
01799         _advPayload.clear();
01800         setAdvertisingData(_advPayload, _scanResponse);
01801     }
01802 
01803     /**
01804      * Set gap flags in the advertising payload.
01805      *
01806      * A call to this function is equivalent to:
01807      *
01808      * @code
01809      * Gap &gap;
01810      *
01811      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01812      * payload.addFlags(flags);
01813      * gap.setAdvertisingPayload(payload);
01814      * @endcode
01815      *
01816      * @param[in] flags The flags to be added.
01817      *
01818      * @return BLE_ERROR_NONE if the data was successfully added to the
01819      * advertising payload.
01820      */
01821     ble_error_t accumulateAdvertisingPayload(uint8_t flags)
01822     {
01823         GapAdvertisingData advPayloadCopy = _advPayload;
01824         ble_error_t rc;
01825         if ((rc = advPayloadCopy.addFlags(flags)) != BLE_ERROR_NONE) {
01826             return rc;
01827         }
01828 
01829         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01830         if (rc == BLE_ERROR_NONE) {
01831             _advPayload = advPayloadCopy;
01832         }
01833 
01834         return rc;
01835     }
01836 
01837     /**
01838      * Set the appearance field in the advertising payload.
01839      *
01840      * A call to this function is equivalent to:
01841      *
01842      * @code
01843      * Gap &gap;
01844      *
01845      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01846      * payload.addAppearance(app);
01847      * gap.setAdvertisingPayload(payload);
01848      * @endcode
01849      *
01850      * @param[in] app The appearance to advertise.
01851      *
01852      * @return BLE_ERROR_NONE if the data was successfully added to the
01853      * advertising payload.
01854      */
01855     ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app)
01856     {
01857         GapAdvertisingData advPayloadCopy = _advPayload;
01858         ble_error_t rc;
01859         if ((rc = advPayloadCopy.addAppearance(app)) != BLE_ERROR_NONE) {
01860             return rc;
01861         }
01862 
01863         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01864         if (rc == BLE_ERROR_NONE) {
01865             _advPayload = advPayloadCopy;
01866         }
01867 
01868         return rc;
01869     }
01870 
01871     /**
01872      * Set the Tx Power field in the advertising payload.
01873      *
01874      * A call to this function is equivalent to:
01875      *
01876      * @code
01877      * Gap &gap;
01878      *
01879      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01880      * payload.addTxPower(power);
01881      * gap.setAdvertisingPayload(payload);
01882      * @endcode
01883      *
01884      * @param[in] power Transmit power in dBm used by the controller to advertise.
01885      *
01886      * @return BLE_ERROR_NONE if the data was successfully added to the
01887      * advertising payload.
01888      */
01889     ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power)
01890     {
01891         GapAdvertisingData advPayloadCopy = _advPayload;
01892         ble_error_t rc;
01893         if ((rc = advPayloadCopy.addTxPower(power)) != BLE_ERROR_NONE) {
01894             return rc;
01895         }
01896 
01897         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01898         if (rc == BLE_ERROR_NONE) {
01899             _advPayload = advPayloadCopy;
01900         }
01901 
01902         return rc;
01903     }
01904 
01905     /**
01906      * Add a new field in the advertising payload.
01907      *
01908      * A call to this function is equivalent to:
01909      *
01910      * @code
01911      * Gap &gap;
01912      *
01913      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01914      * payload.addData(type, data, len);
01915      * gap.setAdvertisingPayload(payload);
01916      * @endcode
01917      *
01918      * @param[in] type Identity of the field being added.
01919      * @param[in] data Buffer containing the value of the field.
01920      * @param[in] len Length of the data buffer.
01921      *
01922      * @return BLE_ERROR_NONE if the advertisement payload was updated based on
01923      * matching AD type; otherwise, an appropriate error.
01924      *
01925      * @note When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS,
01926      * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS,
01927      * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS,
01928      * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the
01929      * supplied value is appended to the values previously added to the payload.
01930      */
01931     ble_error_t accumulateAdvertisingPayload(
01932         GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len
01933     ) {
01934         GapAdvertisingData advPayloadCopy = _advPayload;
01935         ble_error_t rc;
01936         if ((rc = advPayloadCopy.addData(type, data, len)) != BLE_ERROR_NONE) {
01937             return rc;
01938         }
01939 
01940         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01941         if (rc == BLE_ERROR_NONE) {
01942             _advPayload = advPayloadCopy;
01943         }
01944 
01945         return rc;
01946     }
01947 
01948     /**
01949      * Update a particular field in the advertising payload.
01950      *
01951      * A call to this function is equivalent to:
01952      *
01953      * @code
01954      * Gap &gap;
01955      *
01956      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01957      * payload.updateData(type, data, len);
01958      * gap.setAdvertisingPayload(payload);
01959      * @endcode
01960      *
01961      *
01962      * @param[in] type Id of the field to update.
01963      * @param[in] data data buffer containing the new value of the field.
01964      * @param[in] len Length of the data buffer.
01965      *
01966      * @note If advertisements are enabled, then the update takes effect
01967      * immediately.
01968      *
01969      * @return BLE_ERROR_NONE if the advertisement payload was updated based on
01970      * matching AD type; otherwise, an appropriate error.
01971      */
01972     ble_error_t updateAdvertisingPayload(
01973         GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len
01974     ) {
01975         GapAdvertisingData advPayloadCopy = _advPayload;
01976         ble_error_t rc;
01977         if ((rc = advPayloadCopy.updateData(type, data, len)) != BLE_ERROR_NONE) {
01978             return rc;
01979         }
01980 
01981         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01982         if (rc == BLE_ERROR_NONE) {
01983             _advPayload = advPayloadCopy;
01984         }
01985 
01986         return rc;
01987     }
01988 
01989     /**
01990      * Set the value of the payload advertised.
01991      *
01992      * @param[in] payload A reference to a user constructed advertisement
01993      * payload to set.
01994      *
01995      * @return BLE_ERROR_NONE if the advertisement payload was successfully
01996      * set.
01997      */
01998     ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload)
01999     {
02000         ble_error_t rc = setAdvertisingData(payload, _scanResponse);
02001         if (rc == BLE_ERROR_NONE) {
02002             _advPayload = payload;
02003         }
02004 
02005         return rc;
02006     }
02007 
02008     /**
02009      * Get a reference to the current advertising payload.
02010      *
02011      * @return A reference to the current advertising payload.
02012      */
02013     const GapAdvertisingData &getAdvertisingPayload(void) const
02014     {
02015         return _advPayload;
02016     }
02017 
02018     /**
02019      * Add a new field in the advertising payload.
02020      *
02021      * @param[in] type AD type identifier.
02022      * @param[in] data buffer containing AD data.
02023      * @param[in] len Length of the data buffer.
02024      *
02025      * @return BLE_ERROR_NONE if the data was successfully added to the scan
02026      * response payload.
02027      */
02028     ble_error_t accumulateScanResponse(
02029         GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len
02030     ) {
02031         GapAdvertisingData scanResponseCopy = _scanResponse;
02032         ble_error_t rc;
02033         if ((rc = scanResponseCopy.addData(type, data, len)) != BLE_ERROR_NONE) {
02034             return rc;
02035         }
02036 
02037         rc = setAdvertisingData(_advPayload, scanResponseCopy);
02038         if (rc == BLE_ERROR_NONE) {
02039             _scanResponse = scanResponseCopy;
02040         }
02041 
02042         return rc;
02043     }
02044 
02045     /**
02046      * Reset the content of the scan response.
02047      *
02048      * @note This should be followed by a call to Gap::setAdvertisingPayload()
02049      * or Gap::startAdvertising() before the update takes effect.
02050      */
02051     void clearScanResponse(void) {
02052         _scanResponse.clear();
02053         setAdvertisingData(_advPayload, _scanResponse);
02054     }
02055 
02056     /**
02057      * Set the parameters used during a scan procedure.
02058      *
02059      * @param[in] interval in ms between the start of two consecutive scan windows.
02060      * That value is greater or equal to the scan window value. The
02061      * maximum allowed value is 10.24ms.
02062      *
02063      * @param[in] window Period in ms during which the scanner listens to
02064      * advertising channels. That value is in the range 2.5ms to 10.24s.
02065      *
02066      * @param[in] timeout Duration in seconds of the scan procedure if any. The
02067      * special value 0 disable specific duration of the scan procedure.
02068      *
02069      * @param[in] activeScanning If set to true, then the scanner sends scan
02070      * requests to a scannable or connectable advertiser. If set to false, then the
02071      * scanner does not send any request during the scan procedure.
02072      *
02073      * @return BLE_ERROR_NONE if the scan parameters were correctly set.
02074      *
02075      * @note The scanning window divided by the interval determines the duty
02076      * cycle for scanning. For example, if the interval is 100ms and the window
02077      * is 10ms, then the controller scans for 10 percent of the time.
02078      *
02079      * @note If the interval and the window are set to the same value, then the
02080      * device scans continuously during the scan procedure. The scanning
02081      * frequency changes at every interval.
02082      *
02083      * @note Once the scanning parameters have been configured, scanning can be
02084      * enabled by using startScan().
02085      *
02086      * @note The scan interval and window are recommendations to the BLE stack.
02087      */
02088     ble_error_t setScanParams(
02089         uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
02090         uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
02091         uint16_t timeout = 0,
02092         bool activeScanning = false
02093     ) {
02094         ble_error_t rc;
02095         if (((rc = _scanningParams.setInterval(interval)) == BLE_ERROR_NONE) &&
02096             ((rc = _scanningParams.setWindow(window))     == BLE_ERROR_NONE) &&
02097             ((rc = _scanningParams.setTimeout(timeout))   == BLE_ERROR_NONE)) {
02098             _scanningParams.setActiveScanning(activeScanning);
02099             return BLE_ERROR_NONE;
02100         }
02101 
02102         return rc;
02103     }
02104 
02105     /**
02106      * Set the interval parameter used during scanning procedures.
02107      *
02108      * @param[in] interval Interval in ms between the start of two consecutive
02109      * scan windows. That value is greater or equal to the scan window value.
02110      * The maximum allowed value is 10.24ms.
02111      *
02112      * @return BLE_ERROR_NONE if the scan interval was correctly set.
02113      */
02114     ble_error_t setScanInterval(uint16_t interval)
02115     {
02116         return _scanningParams.setInterval(interval);
02117     }
02118 
02119     /**
02120      * Set the window parameter used during scanning procedures.
02121      *
02122      * @param[in] window Period in ms during which the scanner listens to
02123      * advertising channels. That value is in the range 2.5ms to 10.24s.
02124      *
02125      * @return BLE_ERROR_NONE if the scan window was correctly set.
02126      *
02127      * @note If scanning is already active, the updated value of scanWindow
02128      * is propagated to the underlying BLE stack.
02129      */
02130     ble_error_t setScanWindow(uint16_t window)
02131     {
02132         ble_error_t rc;
02133         if ((rc = _scanningParams.setWindow(window)) != BLE_ERROR_NONE) {
02134             return rc;
02135         }
02136 
02137         /* If scanning is already active, propagate the new setting to the stack. */
02138         if (scanningActive) {
02139             return startRadioScan(_scanningParams);
02140         }
02141 
02142         return BLE_ERROR_NONE;
02143     }
02144 
02145     /**
02146      * Set the timeout parameter used during scanning procedures.
02147      *
02148      * @param[in] timeout Duration in seconds of the scan procedure if any. The
02149      * special value 0 disables specific duration of the scan procedure.
02150      *
02151      * @return BLE_ERROR_NONE if the scan timeout was correctly set.
02152      *
02153      * @note If scanning is already active, the updated value of scanTimeout
02154      * is propagated to the underlying BLE stack.
02155      */
02156     ble_error_t setScanTimeout(uint16_t timeout)
02157     {
02158         ble_error_t rc;
02159         if ((rc = _scanningParams.setTimeout(timeout)) != BLE_ERROR_NONE) {
02160             return rc;
02161         }
02162 
02163         /* If scanning is already active, propagate the new settings to the stack. */
02164         if (scanningActive) {
02165             return startRadioScan(_scanningParams);
02166         }
02167 
02168         return BLE_ERROR_NONE;
02169     }
02170 
02171     /**
02172      * Enable or disable active scanning.
02173      *
02174      * @param[in] activeScanning If set to true, then the scanner sends scan
02175      * requests to a scannable or connectable advertiser. If set to false then the
02176      * scanner does not send any request during the scan procedure.
02177      *
02178      * @return BLE_ERROR_NONE if active scanning was successfully set.
02179      *
02180      * @note If scanning is already in progress, then active scanning is
02181      * enabled for the underlying BLE stack.
02182      */
02183     ble_error_t setActiveScanning(bool activeScanning)
02184     {
02185         _scanningParams.setActiveScanning(activeScanning);
02186 
02187         /* If scanning is already active, propagate the new settings to the stack. */
02188         if (scanningActive) {
02189             return startRadioScan(_scanningParams);
02190         }
02191 
02192         return BLE_ERROR_NONE;
02193     }
02194 
02195     /**
02196      * Start the scanning procedure.
02197      *
02198      * Packets received during the scan procedure are forwarded to the
02199      * scan packet handler passed as argument to this function.
02200      *
02201      * @param[in] callback Advertisement packet event handler. Upon reception
02202      * of an advertising packet, the packet is forwarded to @p callback.
02203      *
02204      * @return BLE_ERROR_NONE if the device successfully started the scan
02205      *         procedure.
02206      *
02207      * @note The parameters used by the procedure are defined by setScanParams().
02208      */
02209     ble_error_t startScan(
02210         void (*callback)(const AdvertisementCallbackParams_t *params)
02211     ) {
02212         ble_error_t err = BLE_ERROR_NONE;
02213         if (callback) {
02214             if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
02215                 scanningActive = true;
02216                 onAdvertisementReport.attach(callback);
02217             }
02218         }
02219 
02220         return err;
02221     }
02222 
02223     /**
02224      * Start the scanning procedure.
02225      *
02226      * Packets received during the scan procedure are forwarded to the
02227      * scan packet handler passed as argument to this function.
02228      *
02229      * @param[in] object Instance used to invoke @p callbackMember.
02230      *
02231      * @param[in] callbackMember Advertisement packet event handler. Upon
02232      * reception of an advertising packet, the packet is forwarded to @p
02233      * callback invoked from @p object.
02234      *
02235      * @return BLE_ERROR_NONE if the device successfully started the scan
02236      * procedure.
02237      *
02238      * @note The parameters used by the procedure are defined by setScanParams().
02239      */
02240     template<typename T>
02241     ble_error_t startScan(
02242         T *object,
02243         void (T::*callbackMember)(const AdvertisementCallbackParams_t *params)
02244     ) {
02245         ble_error_t err = BLE_ERROR_NONE;
02246         if (object && callbackMember) {
02247             if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
02248                 scanningActive = true;
02249                 onAdvertisementReport.attach(object, callbackMember);
02250             }
02251         }
02252 
02253         return err;
02254     }
02255 
02256     /**
02257      * Enable radio-notification events.
02258      *
02259      * Radio Notification is a feature that notifies the application when the
02260      * radio is in use.
02261      *
02262      * The ACTIVE signal is sent before the radio event starts. The nACTIVE
02263      * signal is sent at the end of the radio event. The application programmer can
02264      * use these signals to synchronize application logic with radio
02265      * activity. For example, the ACTIVE signal can be used to shut off external
02266      * devices, to manage peak current drawn during periods when the radio is on
02267      * or to trigger sensor data collection for transmission in the Radio Event.
02268      *
02269      * @return BLE_ERROR_NONE on successful initialization, otherwise an error code.
02270      */
02271     virtual ble_error_t initRadioNotification(void)
02272     {
02273         /* Requesting action from porter(s): override this API if this capability
02274            is supported. */
02275         return BLE_ERROR_NOT_IMPLEMENTED;
02276     }
02277 
02278     /**
02279      * Enable or disable privacy mode of the local device.
02280      *
02281      * When privacy is enabled, the system use private addresses while it scans,
02282      * advertises or initiate a connection. The device private address is
02283      * renewed every 15 minutes.
02284      *
02285      * @par Configuration
02286      *
02287      * The privacy feature can be configured with the help of the functions
02288      * setPeripheralPrivacyConfiguration and setCentralPrivacyConfiguration
02289      * which respectively set the privacy configuration of the peripheral and
02290      * central role.
02291      *
02292      * @par Default configuration of peripheral role
02293      *
02294      * By default private resolvable addresses are used for all procedures;
02295      * including advertisement of non connectable packets. Connection request
02296      * from an unknown initiator with a private resolvable address triggers the
02297      * pairing procedure.
02298      *
02299      * @par Default configuration of central role
02300      *
02301      * By default private resolvable addresses are used for all procedures;
02302      * including active scanning. Addresses present in advertisement packet are
02303      * resolved and advertisement packets are forwarded to the application
02304      * even if the advertiser private address is unknown.
02305      *
02306      * @param[in] enable Should be set to true to enable the privacy mode and
02307      * false to disable it.
02308      *
02309      * @return BLE_ERROR_NONE in case of success or an appropriate error code.
02310      */
02311     virtual ble_error_t enablePrivacy(bool enable) {
02312         return BLE_ERROR_NOT_IMPLEMENTED;
02313     }
02314 
02315     /**
02316      * Set the privacy configuration used by the peripheral role.
02317      *
02318      * @param[in] configuration The configuration to set.
02319      *
02320      * @return BLE_ERROR_NONE in case of success or an appropriate error code.
02321      */
02322     virtual ble_error_t setPeripheralPrivacyConfiguration(
02323         const PeripheralPrivacyConfiguration_t *configuration
02324     ) {
02325         return BLE_ERROR_NOT_IMPLEMENTED;
02326     }
02327 
02328     /**
02329      * Get the privacy configuration used by the peripheral role.
02330      *
02331      * @param[out] configuration The variable filled with the current
02332      * configuration.
02333      *
02334      * @return BLE_ERROR_NONE in case of success or an appropriate error code.
02335      */
02336     virtual ble_error_t getPeripheralPrivacyConfiguration(
02337         PeripheralPrivacyConfiguration_t *configuration
02338     ) {
02339         return BLE_ERROR_NOT_IMPLEMENTED;
02340     }
02341 
02342     /**
02343      * Set the privacy configuration used by the central role.
02344      *
02345      * @param[in] configuration The configuration to set.
02346      *
02347      * @return BLE_ERROR_NONE in case of success or an appropriate error code.
02348      */
02349     virtual ble_error_t setCentralPrivacyConfiguration(
02350         const CentralPrivacyConfiguration_t *configuration
02351     ) {
02352         return BLE_ERROR_NOT_IMPLEMENTED;
02353     }
02354 
02355     /**
02356      * Get the privacy configuration used by the central role.
02357      *
02358      * @param[out] configuration The variable filled with the current
02359      * configuration.
02360      *
02361      * @return BLE_ERROR_NONE in case of success or an appropriate error code.
02362      */
02363     virtual ble_error_t getCentralPrivacyConfiguration(
02364         CentralPrivacyConfiguration_t *configuration
02365     ) {
02366         return BLE_ERROR_NOT_IMPLEMENTED;
02367     }
02368 
02369 private:
02370     /**
02371      * Set the advertising data and scan response in the vendor subsytem.
02372      *
02373      * @param[in] advData Advertising data to set.
02374      * @param[in] scanResponse Scan response to set.
02375      *
02376      * @return BLE_ERROR_NONE if the advertising data was set successfully.
02377      *
02378      * @note Must be implemented in vendor port.
02379      */
02380     virtual ble_error_t setAdvertisingData(
02381         const GapAdvertisingData &advData,
02382         const GapAdvertisingData &scanResponse
02383     ) = 0;
02384 
02385     /**
02386      * Start the advertising procedure.
02387      *
02388      * @param[in] params Advertising parameters to use.
02389      *
02390      * @return BLE_ERROR_NONE if the advertising procedure successfully
02391      * started.
02392      *
02393      * @note Must be implemented in vendor port.
02394      */
02395     virtual ble_error_t startAdvertising(const GapAdvertisingParams &params) = 0;
02396 
02397 public:
02398     /**
02399      * Get the current advertising parameters.
02400      *
02401      * @return A reference to the current advertising parameters.
02402      */
02403     GapAdvertisingParams &getAdvertisingParams(void)
02404     {
02405         return _advParams;
02406     }
02407 
02408     /**
02409      * Const alternative to Gap::getAdvertisingParams().
02410      *
02411      * @return A const reference to the current advertising parameters.
02412      */
02413     const GapAdvertisingParams &getAdvertisingParams(void) const
02414     {
02415         return _advParams;
02416     }
02417 
02418     /**
02419      * Set the advertising parameters.
02420      *
02421      * @param[in] newParams The new advertising parameters.
02422      */
02423     void setAdvertisingParams(const GapAdvertisingParams &newParams)
02424     {
02425         _advParams = newParams;
02426     }
02427 
02428     /* Event handlers. */
02429 public:
02430     /**
02431      * Register a callback handling timeout events.
02432      *
02433      * @param[in] callback Event handler being registered.
02434      *
02435      * @note A callback may be unregistered using onTimeout().detach(callback).
02436      *
02437      * @see TimeoutSource_t
02438      */
02439     void onTimeout(TimeoutEventCallback_t callback)
02440     {
02441         timeoutCallbackChain.add(callback);
02442     }
02443 
02444     /**
02445      * Get the callchain of registered timeout event handlers.
02446      *
02447      * @note To register callbacks, use onTimeout().add(callback).
02448      *
02449      * @note To unregister callbacks, use onTimeout().detach(callback).
02450      *
02451      * @return A reference to the timeout event callbacks chain.
02452      */
02453     TimeoutEventCallbackChain_t & onTimeout()
02454     {
02455         return timeoutCallbackChain;
02456     }
02457 
02458     /**
02459      * Register a callback handling connection events.
02460      *
02461      * @param[in] callback Event handler being registered.
02462      *
02463      * @note A callback may be unregistered using onConnection().detach(callback).
02464      */
02465     void onConnection(ConnectionEventCallback_t  callback)
02466     {
02467         connectionCallChain.add(callback);
02468     }
02469 
02470     /**
02471      * Register a callback handling connection events.
02472      *
02473      * @param[in] tptr Instance used to invoke @p mptr.
02474      * @param[in] mptr Event handler being registered.
02475      *
02476      * @note A callback may be unregistered using onConnection().detach(callback).
02477      */
02478     template<typename T>
02479     void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*))
02480     {
02481         connectionCallChain.add(tptr, mptr);
02482     }
02483 
02484     /**
02485      * Get the callchain of registered connection event handlers.
02486      *
02487      * @note To register callbacks, use onConnection().add(callback).
02488      *
02489      * @note To unregister callbacks, use onConnection().detach(callback).
02490      *
02491      * @return A reference to the connection event callbacks chain.
02492      */
02493     ConnectionEventCallbackChain_t & onConnection()
02494     {
02495         return connectionCallChain;
02496     }
02497 
02498     /**
02499      * Register a callback handling disconnection events.
02500      *
02501      * @param[in] callback Event handler being registered.
02502      *
02503      * @note A callback may be unregistered using onDisconnection().detach(callback).
02504      */
02505     void onDisconnection(DisconnectionEventCallback_t  callback)
02506     {
02507         disconnectionCallChain.add(callback);
02508     }
02509 
02510     /**
02511      * Register a callback handling disconnection events.
02512      *
02513      * @param[in] tptr Instance used to invoke mptr.
02514      * @param[in] mptr Event handler being registered.
02515      *
02516      * @note A callback may be unregistered using onDisconnection().detach(callback).
02517      */
02518     template<typename T>
02519     void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*))
02520     {
02521         disconnectionCallChain.add(tptr, mptr);
02522     }
02523 
02524     /**
02525      * Get the callchain of registered disconnection event handlers.
02526      *
02527      * @note To register callbacks use onDisconnection().add(callback).
02528      *
02529      * @note To unregister callbacks use onDisconnection().detach(callback).
02530      *
02531      * @return A reference to the disconnection event callbacks chain.
02532      */
02533     DisconnectionEventCallbackChain_t & onDisconnection()
02534     {
02535         return disconnectionCallChain;
02536     }
02537 
02538     /**
02539      * Set the radio-notification events handler.
02540      *
02541      * Radio Notification is a feature that enables ACTIVE and INACTIVE
02542      * (nACTIVE) signals from the stack that notify the application when the
02543      * radio is in use.
02544      *
02545      * The ACTIVE signal is sent before the radio event starts. The nACTIVE
02546      * signal is sent at the end of the radio event. The application programmer can
02547      * use these signals to synchronize application logic with radio
02548      * activity. For example, the ACTIVE signal can be used to shut off external
02549      * devices, to manage peak current drawn during periods when the radio is on
02550      * or to trigger sensor data collection for transmission in the Radio Event.
02551      *
02552      * @param[in] callback Application handler to be invoked in response to a
02553      * radio ACTIVE/INACTIVE event.
02554      */
02555     void onRadioNotification(void (*callback)(bool param))
02556     {
02557         radioNotificationCallback.attach(callback);
02558     }
02559 
02560     /**
02561      * Set the radio-notification events handler.
02562      *
02563      * @param[in] tptr Instance to be used to invoke mptr.
02564      * @param[in] mptr Application handler to be invoked in response to a
02565      * radio ACTIVE/INACTIVE event.
02566      */
02567     template <typename T>
02568     void onRadioNotification(T *tptr, void (T::*mptr)(bool))
02569     {
02570         radioNotificationCallback.attach(tptr, mptr);
02571     }
02572 
02573     /**
02574      * Register a Gap shutdown event handler.
02575      *
02576      * The handler is called when the Gap instance is about to shut down.
02577      * It is usually issued after a call to BLE::shutdown().
02578      *
02579      * @param[in] callback Shutdown event handler to register.
02580      *
02581      * @note To unregister a shutdown event handler, use
02582      * onShutdown().detach(callback).
02583      */
02584     void onShutdown(const GapShutdownCallback_t& callback)
02585     {
02586         shutdownCallChain.add(callback);
02587     }
02588 
02589     /**
02590      * Register a Gap shutdown event handler.
02591      *
02592      * @param[in] objPtr Instance used to invoke @p memberPtr.
02593      * @param[in] memberPtr Shutdown event handler to register.
02594      */
02595     template <typename T>
02596     void onShutdown(T *objPtr, void (T::*memberPtr)(const Gap *))
02597     {
02598         shutdownCallChain.add(objPtr, memberPtr);
02599     }
02600 
02601     /**
02602      * Access the callchain of shutdown event handler.
02603      *
02604      * @note To register callbacks, use onShutdown().add(callback).
02605      *
02606      * @note To unregister callbacks, use onShutdown().detach(callback).
02607      *
02608      * @return A reference to the shutdown event callback chain.
02609      */
02610     GapShutdownCallbackChain_t & onShutdown()
02611     {
02612         return shutdownCallChain;
02613     }
02614 
02615 public:
02616     /**
02617      * Reset the Gap instance.
02618      *
02619      * Reset process starts by notifying all registered shutdown event handlers
02620      * that the Gap instance is about to be shut down. Then, it clears all Gap state
02621      * of the associated object and then cleans the state present in the vendor
02622      * implementation.
02623      *
02624      * This function is meant to be overridden in the platform-specific
02625      * subclass. Nevertheless, the subclass only resets its
02626      * state and not the data held in Gap members. This is achieved by a
02627      * call to Gap::reset() from the subclass' reset() implementation.
02628      *
02629      * @return BLE_ERROR_NONE on success.
02630      *
02631      * @note Currently, a call to reset() does not reset the advertising and
02632      * scan parameters to default values.
02633      */
02634     virtual ble_error_t reset(void)
02635     {
02636         /* Notify that the instance is about to shut down */
02637         shutdownCallChain.call(this);
02638         shutdownCallChain.clear();
02639 
02640         /* Clear Gap state */
02641         state.advertising = 0;
02642         state.connected   = 0;
02643         connectionCount   = 0;
02644 
02645         /* Clear scanning state */
02646         scanningActive = false;
02647 
02648         /* Clear advertising and scanning data */
02649         _advPayload.clear();
02650         _scanResponse.clear();
02651 
02652         /* Clear callbacks */
02653         timeoutCallbackChain.clear();
02654         connectionCallChain.clear();
02655         disconnectionCallChain.clear();
02656         radioNotificationCallback = NULL;
02657         onAdvertisementReport     = NULL;
02658 
02659         return BLE_ERROR_NONE;
02660     }
02661 
02662 protected:
02663     /**
02664      * Construct a Gap instance.
02665      */
02666     Gap() :
02667         _advParams(),
02668         _advPayload(),
02669         _scanningParams(),
02670         _scanResponse(),
02671         connectionCount(0),
02672         state(),
02673         scanningActive(false),
02674         timeoutCallbackChain(),
02675         radioNotificationCallback(),
02676         onAdvertisementReport(),
02677         connectionCallChain(),
02678         disconnectionCallChain() {
02679         _advPayload.clear();
02680         _scanResponse.clear();
02681     }
02682 
02683     /* Entry points for the underlying stack to report events back to the user. */
02684 public:
02685     /**
02686      * Notify all registered connection event handlers of a connection event.
02687      *
02688      * @attention This function is meant to be called from the BLE stack specific
02689      * implementation when a connection event occurs.
02690      *
02691      * @param[in] handle Handle of the new connection.
02692      * @param[in] role Role of this BLE device in the connection.
02693      * @param[in] peerAddrType Address type of the connected peer.
02694      * @param[in] peerAddr Address of the connected peer.
02695      * @param[in] ownAddrType Address type this device uses for this
02696      * connection.
02697      * @param[in] ownAddr Address this device uses for this connection. This
02698      * parameter may be NULL if the local address is not available.
02699      * @param[in] connectionParams Parameters of the connection.
02700      * @param[in] peerResolvableAddr Resolvable address used by the peer.
02701      * @param[in] localResolvableAddr resolvable address used by the local device.
02702      */
02703     void processConnectionEvent(
02704         Handle_t handle,
02705         Role_t role,
02706         PeerAddressType_t peerAddrType,
02707         const BLEProtocol::AddressBytes_t peerAddr,
02708         BLEProtocol::AddressType_t ownAddrType,
02709         const BLEProtocol::AddressBytes_t ownAddr,
02710         const ConnectionParams_t *connectionParams,
02711         const uint8_t *peerResolvableAddr = NULL,
02712         const uint8_t *localResolvableAddr = NULL
02713     );
02714 
02715     /**
02716      * Notify all registered connection event handlers of a connection event.
02717      *
02718      * @attention This function is meant to be called from the BLE stack specific
02719      * implementation when a connection event occurs.
02720      *
02721      * @param[in] handle Handle of the new connection.
02722      * @param[in] role Role of this BLE device in the connection.
02723      * @param[in] peerAddrType Address type of the connected peer.
02724      * @param[in] peerAddr Address of the connected peer.
02725      * @param[in] ownAddrType Address type this device uses for this
02726      * connection.
02727      * @param[in] ownAddr Address this device uses for this connection.
02728      * @param[in] connectionParams Parameters of the connection.
02729      * @param[in] peerResolvableAddr Resolvable address used by the peer.
02730      * @param[in] localResolvableAddr resolvable address used by the local device.
02731      *
02732      * @deprecated The type BLEProtocol::AddressType_t is not suitable when
02733      * privacy is enabled. Use the overload that accepts a PeerAddressType_t
02734      * instead.
02735      */
02736     MBED_DEPRECATED_SINCE(
02737        "mbed-os-5.9.0",
02738        "The type BLEProtocol::AddressType_t is not suitable when privacy is "
02739        "enabled. Use the overload that accepts a PeerAddressType_t instead."
02740     )
02741     void processConnectionEvent(
02742         Handle_t handle,
02743         Role_t role,
02744         BLEProtocol::AddressType_t peerAddrType,
02745         const BLEProtocol::AddressBytes_t peerAddr,
02746         BLEProtocol::AddressType_t ownAddrType,
02747         const BLEProtocol::AddressBytes_t ownAddr,
02748         const ConnectionParams_t *connectionParams,
02749         const uint8_t *peerResolvableAddr = NULL,
02750         const uint8_t *localResolvableAddr = NULL
02751     );
02752 
02753     /**
02754      * Notify all registered disconnection event handlers of a disconnection event.
02755      *
02756      * @attention This function is meant to be called from the BLE stack specific
02757      * implementation when a disconnection event occurs.
02758      *
02759      * @param[in] handle Handle of the terminated connection.
02760      * @param[in] reason Reason of the disconnection.
02761      */
02762     void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason)
02763     {
02764         /* Update Gap state */
02765         --connectionCount;
02766         if (!connectionCount) {
02767             state.connected = 0;
02768         }
02769 
02770         DisconnectionCallbackParams_t callbackParams(handle, reason);
02771         disconnectionCallChain.call(&callbackParams);
02772     }
02773 
02774     /**
02775      * Forward a received advertising packet to all registered event handlers
02776      * listening for scanned packet events.
02777      *
02778      * @attention This function is meant to be called from the BLE stack specific
02779      * implementation when a disconnection event occurs.
02780      *
02781      * @param[in] peerAddr Address of the peer that has emitted the packet.
02782      * @param[in] rssi Value of the RSSI measured for the received packet.
02783      * @param[in] isScanResponse If true, then the packet is a response to a scan
02784      * request.
02785      * @param[in] type Advertising type of the packet.
02786      * @param[in] advertisingDataLen Length of the advertisement data received.
02787      * @param[in] advertisingData Pointer to the advertisement packet's data.
02788      * @param[in] addressType Type of the address of the peer that has emitted
02789      * the packet.
02790      */
02791     void processAdvertisementReport(
02792         const BLEProtocol::AddressBytes_t peerAddr,
02793         int8_t rssi,
02794         bool isScanResponse,
02795         GapAdvertisingParams::AdvertisingType_t type,
02796         uint8_t advertisingDataLen,
02797         const uint8_t *advertisingData,
02798         PeerAddressType_t addressType
02799     );
02800 
02801     /**
02802      * Forward a received advertising packet to all registered event handlers
02803      * listening for scanned packet events.
02804      *
02805      * @attention This function is meant to be called from the BLE stack specific
02806      * implementation when a disconnection event occurs.
02807      *
02808      * @param[in] peerAddr Address of the peer that has emitted the packet.
02809      * @param[in] rssi Value of the RSSI measured for the received packet.
02810      * @param[in] isScanResponse If true, then the packet is a response to a scan
02811      * request.
02812      * @param[in] type Advertising type of the packet.
02813      * @param[in] advertisingDataLen Length of the advertisement data received.
02814      * @param[in] advertisingData Pointer to the advertisement packet's data.
02815      * @param[in] addressType Type of the address of the peer that has emitted the packet.
02816      *
02817      * @deprecated The type BLEProtocol::AddressType_t is not suitable when
02818      * privacy is enabled. Use the overload that accepts a PeerAddressType_t
02819      * instead.
02820      */
02821     MBED_DEPRECATED_SINCE(
02822        "mbed-os-5.9.0",
02823        "The type BLEProtocol::AddressType_t is not suitable when privacy is "
02824        "enabled. Use the overload that accepts a PeerAddressType_t instead."
02825     )
02826     void processAdvertisementReport(
02827         const BLEProtocol::AddressBytes_t peerAddr,
02828         int8_t rssi,
02829         bool isScanResponse,
02830         GapAdvertisingParams::AdvertisingType_t type,
02831         uint8_t advertisingDataLen,
02832         const uint8_t *advertisingData,
02833         BLEProtocol::AddressType_t addressType = BLEProtocol::AddressType::RANDOM_STATIC
02834     );
02835 
02836     /**
02837      * Notify the occurrence of a timeout event to all registered timeout events
02838      * handler.
02839      *
02840      * @attention This function is meant to be called from the BLE stack specific
02841      * implementation when a disconnection event occurs.
02842      *
02843      * @param[in] source Source of the timout event.
02844      */
02845     void processTimeoutEvent(TimeoutSource_t source)
02846     {
02847         if (source == TIMEOUT_SRC_ADVERTISING) {
02848             /* Update gap state if the source is an advertising timeout */
02849             state.advertising = 0;
02850         }
02851         if (timeoutCallbackChain) {
02852             timeoutCallbackChain(source);
02853         }
02854     }
02855 
02856 protected:
02857     /**
02858      * Current advertising parameters.
02859      */
02860     GapAdvertisingParams _advParams;
02861 
02862     /**
02863      * Current advertising data.
02864      */
02865     GapAdvertisingData _advPayload;
02866 
02867     /**
02868      * Current scanning parameters.
02869      */
02870     GapScanningParams _scanningParams;
02871 
02872     /**
02873      * Current scan response.
02874      */
02875     GapAdvertisingData _scanResponse;
02876 
02877     /**
02878      * Number of open connections.
02879      */
02880     uint8_t connectionCount;
02881 
02882     /**
02883      * Current GAP state.
02884      */
02885     GapState_t state;
02886 
02887     /**
02888      * Active scanning flag.
02889      */
02890     bool scanningActive;
02891 
02892 protected:
02893     /**
02894      * Callchain containing all registered callback handlers for timeout
02895      * events.
02896      */
02897     TimeoutEventCallbackChain_t  timeoutCallbackChain;
02898 
02899     /**
02900      * The registered callback handler for radio notification events.
02901      */
02902     RadioNotificationEventCallback_t radioNotificationCallback;
02903 
02904     /**
02905      * The registered callback handler for scanned advertisement packet
02906      * notifications.
02907      */
02908     AdvertisementReportCallback_t  onAdvertisementReport;
02909 
02910     /**
02911      * Callchain containing all registered callback handlers for connection
02912      * events.
02913      */
02914     ConnectionEventCallbackChain_t  connectionCallChain;
02915 
02916     /**
02917      * Callchain containing all registered callback handlers for disconnection
02918      * events.
02919      */
02920     DisconnectionEventCallbackChain_t  disconnectionCallChain;
02921 
02922 private:
02923     /**
02924      * Callchain containing all registered callback handlers for shutdown
02925      * events.
02926      */
02927     GapShutdownCallbackChain_t  shutdownCallChain;
02928 
02929 private:
02930     /* Disallow copy and assignment. */
02931     Gap(const Gap &);
02932     Gap& operator=(const Gap &);
02933 };
02934 
02935 /**
02936  * @}
02937  * @}
02938  */
02939 
02940 #endif // ifndef MBED_BLE_GAP_H__