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 Scanning
00125  *
00126  * Scanning consist of listening for peer advertising packets. From a scan, a
00127  * device can identify devices available in its environment.
00128  *
00129  * If the device scans actively, then it will send scan request to scannable
00130  * advertisers and collect their scan response.
00131  *
00132  * @code
00133  * // assuming gap has been initialized
00134  * Gap& gap;
00135  *
00136  * // Handle advertising packet by dumping their content
00137  * void handle_advertising_packet(const AdvertisementCallbackParams_t* packet)
00138  * {
00139  *    printf("Packet received: \r\n");
00140  *    printf("  - peer address: %02X:%02X:%02X:%02X:%02X:%02X\r\n",
00141  *           packet->peerAddr[5], packet->peerAddr[4], packet->peerAddr[3],
00142  *           packet->peerAddr[2], packet->peerAddr[1], packet->peerAddr[0]);
00143  *    printf("  - rssi: %d", packet->rssi);
00144  *    printf("  - scan response: %s\r\n", packet->isScanresponse ? "true" : "false");
00145  *    printf("  - advertising type: %d\r\n", packet->type);
00146  *    printf("  - advertising type: %d\r\n", packet->type);
00147  *    printf("  - Advertising data: \r\n");
00148  *
00149  *    // parse advertising data, it is a succession of AD structures where
00150  *    // the first byte is the size of the AD structure, the second byte the
00151  *    // type of the data and remaining bytes are the value.
00152  *
00153  *    for (size_t i = 0; i < packet->advertisingDataLen; i += packet->advertisingData[i]) {
00154  *        printf("    - type: 0X%02X, data: ", packet->advertisingData[i + 1]);
00155  *        for (size_t j = 0; j < packet->advertisingData[i] - 2; ++j) {
00156  *            printf("0X%02X ", packet->advertisingData[i + 2 + j]);
00157  *        }
00158  *        printf("\r\n");
00159  *    }
00160  * }
00161  *
00162  * // set the scan parameters
00163  * gap.setScanParams(
00164  *      100, // interval between two scan window in ms
00165  *      50,  // scan window: period during which the device listen for advertising packets.
00166  *      0,   // the scan process never ends
00167  *      true // the device sends scan request to scannable peers.
00168  * );
00169  *
00170  * // start the scan procedure
00171  * gap.startScan(handle_advertising_packet);
00172  * @endcode
00173  *
00174  * @par Connection event handling
00175  *
00176  * A peer may connect device advertising connectable packets. The
00177  * advertising procedure ends as soon as the device is connected.
00178  *
00179  * A device accepting a connection request from a peer is named a peripheral,
00180  * and the device initiating the connection is named a central.
00181  *
00182  * Peripheral and central receive a connection event when the connection is
00183  * effective.
00184  *
00185  * @code
00186  * Gap& gap;
00187  *
00188  * // handle connection event
00189  * void when_connected(const ConnectionCallbackParams_t *connection_event) {
00190  *    // If this callback is entered, then the connection to a peer is effective.
00191  * }
00192  *
00193  * // register connection event handler, which will be invoked whether the device
00194  * // acts as a central or a peripheral
00195  * gap.onConnection(when_connected);
00196  * @endcode
00197  *
00198  * @par Connection initiation
00199  *
00200  * Connection is initiated central devices.
00201  *
00202  * @code
00203  * // assuming gap has been initialized
00204  * Gap& gap;
00205  *
00206  * // Handle the connection event
00207  * void handle_connection(const ConnectionCallbackParams_t* connection_event)
00208  * {
00209  *    // event handling
00210  * }
00211  *
00212  * // Handle advertising packet: connect to the first connectable device
00213  * void handle_advertising_packet(const AdvertisementCallbackParams_t* packet)
00214  * {
00215  *    if (packet->type != GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED) {
00216  *       return;
00217  *    }
00218  *
00219  *    // register connection event handler
00220  *    gap.onConnection(handle_connection);
00221  *
00222  *    Gap::ConnectionParams_t connection_parameters = {
00223  *       50, // min connection interval
00224  *       100, // max connection interval
00225  *       0, // slave latency
00226  *       600 // connection supervision timeout
00227  *    };
00228  *
00229  *    // scan parameter used to find the device to connect to
00230  *    GapScanningParams scanning_params(
00231  *      100, // interval
00232  *      100, // window
00233  *      0, // timeout
00234  *      false // active
00235  *    );
00236  *
00237  *    // Initiate the connection procedure
00238  *    gap.connect(
00239  *       packet->peerAddr,
00240  *       packet->addressType,
00241  *       &connection_parameters,
00242  *       &scanning_params
00243  *    );
00244  * }
00245  *
00246  * // set the scan parameters
00247  * gap.setScanParams(
00248  *      100, // interval between two scan window in ms
00249  *      50,  // scan window: period during which the device listen for advertising packets.
00250  *      0,   // the scan process never ends
00251  *      true // the device sends scan request to scannable peers.
00252  * );
00253  *
00254  * // start the scan procedure
00255  * gap.startScan(handle_advertising_packet);
00256  * @endcode
00257  *
00258  * @par disconnection
00259  *
00260  * The application code initiates a disconnection when it calls the
00261  * disconnect(Handle_t, DisconnectionReason_t) function.
00262  *
00263  * Disconnection may also be initiated by the remote peer or the local
00264  * controller/stack. To catch all disconnection events, application code may
00265  * set up an handler taking care of disconnection events by calling
00266  * onDisconnection().
00267  */
00268 class Gap {
00269     /*
00270      * DEPRECATION ALERT: all of the APIs in this `public` block are deprecated.
00271      * They have been relocated to the class BLEProtocol.
00272      */
00273 public:
00274     /**
00275      * Address-type for BLEProtocol addresses.
00276      *
00277      * @deprecated Use BLEProtocol::AddressType_t instead.
00278      */
00279     typedef BLEProtocol::AddressType_t AddressType_t;
00280 
00281     /**
00282      * Address-type for BLEProtocol addresses.
00283      *
00284      * @deprecated Use BLEProtocol::AddressType_t instead.
00285      */
00286     typedef BLEProtocol::AddressType_t addr_type_t;
00287 
00288     /**
00289      * Address-type for BLEProtocol addresses.
00290      *
00291      * @deprecated Use BLEProtocol::AddressType_t instead. The following
00292      * constants have been left in their deprecated state to transparently
00293      * support existing applications that may have used Gap::ADDR_TYPE_*.
00294      */
00295     enum DeprecatedAddressType_t {
00296         ADDR_TYPE_PUBLIC = BLEProtocol::AddressType::PUBLIC,
00297         ADDR_TYPE_RANDOM_STATIC = BLEProtocol::AddressType::RANDOM_STATIC,
00298         ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_RESOLVABLE,
00299         ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE
00300     };
00301 
00302     /**
00303      * Length (in octets) of the BLE MAC address.
00304      */
00305     static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN;
00306 
00307     /**
00308      * 48-bit address, LSB format.
00309      *
00310      * @deprecated Use BLEProtocol::AddressBytes_t instead.
00311      */
00312     typedef BLEProtocol::AddressBytes_t Address_t;
00313 
00314     /**
00315      * 48-bit address, LSB format.
00316      *
00317      * @deprecated Use BLEProtocol::AddressBytes_t instead.
00318      */
00319     typedef BLEProtocol::AddressBytes_t address_t;
00320 
00321 public:
00322     /**
00323      * Enumeration of possible timeout sources.
00324      */
00325     enum TimeoutSource_t {
00326         /**
00327          * Advertising timeout.
00328          */
00329         TIMEOUT_SRC_ADVERTISING = 0x00,
00330 
00331         /**
00332          * Security request timeout.
00333          */
00334         TIMEOUT_SRC_SECURITY_REQUEST = 0x01,
00335 
00336         /**
00337          * Scanning timeout.
00338          */
00339         TIMEOUT_SRC_SCAN = 0x02,
00340 
00341         /**
00342          * Connection timeout.
00343          */
00344         TIMEOUT_SRC_CONN = 0x03,
00345     };
00346 
00347     /**
00348      * Enumeration of disconnection reasons.
00349      *
00350      * @attention There might be a mismatch between the disconnection reason
00351      * passed to disconnect() and the disconnection event generated locally
00352      * because the disconnection reason passed to disconnect() is the
00353      * disconnection reason to be transmitted to the peer.
00354      */
00355     enum DisconnectionReason_t {
00356         /**
00357          * The connection timed out.
00358          *
00359          * @attention shall not be used as a reason in disconnect().
00360          */
00361         CONNECTION_TIMEOUT = 0x08,
00362 
00363         /**
00364          * Connection terminated by the user.
00365          */
00366         REMOTE_USER_TERMINATED_CONNECTION = 0x13,
00367 
00368         /**
00369          * Remote device terminated connection due to low resources.
00370          */
00371         REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14,
00372 
00373         /**
00374          * Remote device terminated connection due to power off.
00375          */
00376         REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15,
00377 
00378         /**
00379          * Indicate that the local user or the internal
00380          * Bluetooth subsystem terminated the connection.
00381          *
00382          * @attention shall not be used as a reason in disconnect().
00383          */
00384         LOCAL_HOST_TERMINATED_CONNECTION = 0x16,
00385 
00386         /**
00387          * Connection parameters were unacceptable.
00388          */
00389         CONN_INTERVAL_UNACCEPTABLE = 0x3B,
00390     };
00391 
00392     /**
00393      * Advertising policy filter modes.
00394      *
00395      * @see Bluetooth Core Specification 4.2 (Vol. 6), Part B, Section 4.3.2.
00396      */
00397     enum AdvertisingPolicyMode_t {
00398         /**
00399          * The whitelist is not used to filter peer request during advertising.
00400          */
00401         ADV_POLICY_IGNORE_WHITELIST = 0,
00402 
00403         /**
00404          * The whitelist is used to filter peer scan requests.
00405          */
00406         ADV_POLICY_FILTER_SCAN_REQS = 1,
00407 
00408         /**
00409          * The whitelist is used to filter peer connection requests.
00410          */
00411         ADV_POLICY_FILTER_CONN_REQS = 2,
00412 
00413         /**
00414          * The whitelist is used to filter peer scan and connection requests.
00415          */
00416         ADV_POLICY_FILTER_ALL_REQS  = 3,
00417     };
00418 
00419     /**
00420      * Scanning policy filter mode.
00421      *
00422      * @see Bluetooth Core Specification 4.2 (Vol. 6), Part B, Section 4.3.3.
00423      */
00424     enum ScanningPolicyMode_t {
00425         /**
00426          * The whitelist is not used for scanning operations.
00427          */
00428         SCAN_POLICY_IGNORE_WHITELIST = 0,
00429 
00430         /**
00431          * The whitelist is used to filter incoming advertising.
00432          */
00433         SCAN_POLICY_FILTER_ALL_ADV = 1,
00434     };
00435 
00436     /**
00437      * Connection initiation policy filter mode.
00438      *
00439      * @see Bluetooth Core Specification 4.2 (vol. 6), Part B, Section 4.4.4.
00440      */
00441     enum InitiatorPolicyMode_t {
00442         /**
00443          * Connection can be initiated to any device.
00444          */
00445         INIT_POLICY_IGNORE_WHITELIST = 0,
00446 
00447         /**
00448          * Connection initiation is restricted to the devices present in the
00449          * whitelist.
00450          */
00451         INIT_POLICY_FILTER_ALL_ADV = 1,
00452     };
00453 
00454     /**
00455      * Representation of a whitelist of addresses.
00456      */
00457     struct Whitelist_t {
00458         /**
00459          * Pointer to the array of the addresses composing the whitelist.
00460          */
00461         BLEProtocol::Address_t *addresses;
00462 
00463         /**
00464          * Number addresses in this whitelist.
00465          */
00466         uint8_t size;
00467 
00468         /**
00469          * Capacity of the array holding the addresses.
00470          */
00471         uint8_t capacity;
00472     };
00473 
00474     /**
00475      * Description of the states of the device.
00476      */
00477     struct GapState_t {
00478         /**
00479          * If set, the device is currently advertising.
00480          */
00481         unsigned advertising : 1;
00482 
00483         /**
00484          * If set, the device is connected to at least one other peer.
00485          */
00486         unsigned connected : 1;
00487     };
00488 
00489     /**
00490      * Opaque value type representing a connection handle.
00491      *
00492      * It is used to identify to refer to a specific connection across Gap,
00493      * GattClient and GattEvent API.
00494      *
00495      * @note instances are generated by in the connection callback.
00496      */
00497     typedef ble::connection_handle_t Handle_t;
00498 
00499     /**
00500      * Parameters of a BLE connection.
00501      */
00502     typedef struct {
00503         /**
00504          * Minimum interval between two connection events allowed for a
00505          * connection.
00506          *
00507          * It shall be less than or equal to maxConnectionInterval. This value,
00508          * in units of 1.25ms, is included in the range [0x0006 : 0x0C80].
00509          */
00510         uint16_t minConnectionInterval;
00511 
00512         /**
00513          * Maximum interval between two connection events allowed for a
00514          * connection.
00515          *
00516          * It shall be greater than or equal to minConnectionInterval. This
00517          * value is in unit of 1.25ms and is in the range [0x0006 : 0x0C80].
00518          */
00519         uint16_t maxConnectionInterval;
00520 
00521         /**
00522          * Number of connection events the slave can drop if it has nothing to
00523          * communicate to the master.
00524          *
00525          * This value shall be in the range [0x0000 : 0x01F3].
00526          */
00527         uint16_t slaveLatency;
00528 
00529         /**
00530          * Link supervision timeout for the connection.
00531          *
00532          * Time after which the connection is considered lost if the device
00533          * didn't receive a packet from its peer.
00534          *
00535          * It is larger than:
00536          *        (1 + slaveLatency) * maxConnectionInterval * 2
00537          *
00538          * This value is in the range [0x000A : 0x0C80] and is in unit of
00539          * 10 ms.
00540          *
00541          * @note maxConnectionInterval is in ms in the formulae above.
00542          */
00543         uint16_t connectionSupervisionTimeout;
00544     } ConnectionParams_t;
00545 
00546     /**
00547      * Enumeration of GAP roles.
00548      *
00549      * @note The BLE API does not express the broadcaster and scanner roles.
00550      *
00551      * @attention A device can fulfill different roles concurrently.
00552      */
00553     enum Role_t {
00554         /**
00555          * Peripheral Role.
00556          *
00557          * The device can advertise and it can be connected by a central. It
00558          * acts as a slave when connected.
00559          *
00560          * @note A peripheral is a broadcaster.
00561          */
00562         PERIPHERAL = 0x1,
00563 
00564         /**
00565          * Central Role.
00566          *
00567          * The device can scan and initiate connection to peripherals. It
00568          * acts as the master when a connection is established.
00569          *
00570          * @note A central is a scanner.
00571          */
00572         CENTRAL = 0x2,
00573     };
00574 
00575     /**
00576      * Representation of a scanned advertising packet.
00577      *
00578      * Instances of this type are passed to the callback registered in
00579      * startScan().
00580      */
00581     struct AdvertisementCallbackParams_t {
00582         /**
00583          * BLE address of the device that has advertised the packet.
00584          */
00585         BLEProtocol::AddressBytes_t peerAddr;
00586 
00587         /**
00588          * RSSI value of the packet.
00589          */
00590         int8_t rssi;
00591 
00592         /**
00593          * Flag indicating if the packet is a response to a scan request.
00594          */
00595         bool isScanResponse;
00596 
00597         /**
00598          * Type of advertisement.
00599          */
00600         GapAdvertisingParams::AdvertisingType_t type;
00601 
00602         /**
00603          * Length of the advertisement data.
00604          */
00605         uint8_t advertisingDataLen;
00606 
00607         /**
00608          * Pointer to the advertisement packet's data.
00609          */
00610         const uint8_t *advertisingData;
00611 
00612         /**
00613          * Type of the address received
00614          */
00615         AddressType_t addressType;
00616     };
00617 
00618     /**
00619      * Type of the callback handling scanned advertisement packets.
00620      *
00621      * @see Gap::startScan().
00622      */
00623     typedef FunctionPointerWithContext<const AdvertisementCallbackParams_t *> 
00624         AdvertisementReportCallback_t;
00625 
00626     /**
00627      * Connection events.
00628      *
00629      * It contains all the information related to a newly established connection.
00630      *
00631      * Instances of this structure are passed to handlers that
00632      * Gap::onConnection() registers when a connection is established.
00633      */
00634     struct ConnectionCallbackParams_t {
00635         /**
00636          * Connection handle.
00637          */
00638         Handle_t handle;
00639 
00640         /**
00641          * Connection Role of the local device.
00642          */
00643         Role_t role;
00644 
00645         /**
00646          * Type of the address the peer uses.
00647          */
00648         BLEProtocol::AddressType_t peerAddrType;
00649 
00650         /**
00651          * Address of the peer.
00652          */
00653         BLEProtocol::AddressBytes_t peerAddr;
00654 
00655         /**
00656          * Address type of the local device.
00657          */
00658         BLEProtocol::AddressType_t  ownAddrType;
00659 
00660         /**
00661          * Address of the local device.
00662          */
00663         BLEProtocol::AddressBytes_t ownAddr;
00664 
00665         /**
00666          * Connection parameters.
00667          */
00668         const ConnectionParams_t   *connectionParams;
00669 
00670         /**
00671          * Construct an instance of ConnectionCallbackParams_t.
00672          *
00673          * @param[in] handleIn Value to assign to handle.
00674          * @param[in] roleIn Value to assign to role.
00675          * @param[in] peerAddrTypeIn Value to assign to peerAddrType.
00676          * @param[in] peerAddrIn Value to assign to peerAddr.
00677          * @param[in] ownAddrTypeIn Value to assign to ownAddrType.
00678          * @param[in] ownAddrIn Value to assign to ownAddr.
00679          * @param[in] connectionParamsIn Value to assign to connectionParams.
00680          *
00681          * @note Constructor is not meant to be called by user code.
00682          * The BLE API vendor code generates ConnectionCallbackParams_t.
00683          */
00684         ConnectionCallbackParams_t(
00685             Handle_t handleIn,
00686             Role_t roleIn,
00687             BLEProtocol::AddressType_t peerAddrTypeIn,
00688             const uint8_t *peerAddrIn,
00689             BLEProtocol::AddressType_t ownAddrTypeIn,
00690             const uint8_t *ownAddrIn,
00691             const ConnectionParams_t *connectionParamsIn
00692         ) : handle(handleIn),
00693             role(roleIn),
00694             peerAddrType(peerAddrTypeIn),
00695             peerAddr(),
00696             ownAddrType(ownAddrTypeIn),
00697             ownAddr(),
00698             connectionParams(connectionParamsIn)
00699         {
00700             memcpy(peerAddr, peerAddrIn, ADDR_LEN);
00701             memcpy(ownAddr, ownAddrIn, ADDR_LEN);
00702         }
00703     };
00704 
00705     /**
00706      * Disconnection event.
00707      *
00708      * Instances of this event are passed to callbacks registered with
00709      * Gap::onDisconnection() when a connection ends.
00710      *
00711      * @note Constructor is not meant to be called by user code.
00712      * The BLE API vendor code generates ConnectionCallbackParams_t.
00713      */
00714     struct DisconnectionCallbackParams_t {
00715         /**
00716          * ID of the connection that has ended.
00717          */
00718         Handle_t handle;
00719 
00720         /**
00721          * Reason of the disconnection.
00722          */
00723         DisconnectionReason_t reason;
00724 
00725         /**
00726          * Construct a DisconnectionCallbackParams_t.
00727          *
00728          * @param[in] handleIn Value assigned to handle.
00729          * @param[in] reasonIn Value assigned to reason.
00730          */
00731         DisconnectionCallbackParams_t(
00732             Handle_t handleIn,
00733             DisconnectionReason_t reasonIn
00734         ) : handle(handleIn),
00735             reason(reasonIn)
00736         {}
00737     };
00738 
00739     /**
00740      * Number of microseconds in 1.25 milliseconds.
00741      */
00742     static const uint16_t UNIT_1_25_MS  = 1250;
00743 
00744     /**
00745      * Convert milliseconds into 1.25ms units.
00746      *
00747      * This function may be used to convert ms time of connection intervals into
00748      * the format expected for connection parameters.
00749      *
00750      * @param[in] durationInMillis The duration in milliseconds.
00751      *
00752      * @return The duration in unit of 1.25ms.
00753      */
00754     static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis)
00755     {
00756         return (durationInMillis * 1000) / UNIT_1_25_MS;
00757     }
00758 
00759     /**
00760      * Timeout event handler.
00761      *
00762      * @see Gap::onTimeout().
00763      */
00764     typedef FunctionPointerWithContext<TimeoutSource_t>  TimeoutEventCallback_t;
00765 
00766     /**
00767      * Callchain of timeout event handlers.
00768      *
00769      * @see Gap::onTimeout().
00770      */
00771     typedef CallChainOfFunctionPointersWithContext<TimeoutSource_t> 
00772         TimeoutEventCallbackChain_t;
00773 
00774     /**
00775      * Connection event handler.
00776      *
00777      * @see Gap::onConnection().
00778      */
00779     typedef FunctionPointerWithContext<const ConnectionCallbackParams_t *> 
00780         ConnectionEventCallback_t;
00781 
00782     /**
00783      * Callchain of connection event handlers.
00784      *
00785      * @see Gap::onConnection().
00786      */
00787     typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> 
00788         ConnectionEventCallbackChain_t;
00789 
00790     /**
00791      * Disconnection event handler.
00792      *
00793      * @see Gap::onDisconnection().
00794      */
00795     typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> 
00796         DisconnectionEventCallback_t;
00797 
00798     /**
00799      * Callchain of disconnection event handlers.
00800      *
00801      * @see Gap::onDisconnection().
00802      */
00803     typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> 
00804         DisconnectionEventCallbackChain_t;
00805 
00806     /**
00807      * Radio notification event handler.
00808      *
00809      * @see Gap::onRadioNotification().
00810      */
00811     typedef FunctionPointerWithContext<bool>  RadioNotificationEventCallback_t;
00812 
00813     /**
00814      * Gap shutdown event handler.
00815      *
00816      * @see Gap::onShutdown().
00817      */
00818     typedef FunctionPointerWithContext<const Gap *>  GapShutdownCallback_t;
00819 
00820     /**
00821      * Callchain of gap shutdown event handler.
00822      *
00823      * @see Gap::onShutdown().
00824      */
00825     typedef CallChainOfFunctionPointersWithContext<const Gap *> 
00826         GapShutdownCallbackChain_t;
00827 
00828     /*
00829      * The following functions are meant to be overridden in the platform-specific subclass.
00830      */
00831 public:
00832     /**
00833      * Set the device MAC address and type.
00834      *
00835      * The address set is used in subsequent GAP operations: scanning,
00836      * advertising and connection initiation.
00837      *
00838      * @param[in] type Type of the address to set.
00839      * @param[in] address Value of the address to set. It is ordered in
00840      * little endian. This parameter is not considered if the address type
00841      * is RANDOM_PRIVATE_RESOLVABLE or RANDOM_PRIVATE_NON_RESOLVABLE. For those
00842      * types of address, the BLE API itself generates the address.
00843      *
00844      * @note Some implementation may refuse to set a new PUBLIC address.
00845      * @note Random static address set does not change.
00846      *
00847      * @return BLE_ERROR_NONE on success.
00848      */
00849     virtual ble_error_t setAddress(
00850         BLEProtocol::AddressType_t type,
00851         const BLEProtocol::AddressBytes_t address
00852     ) {
00853         /* avoid compiler warnings about unused variables */
00854         (void)type;
00855         (void)address;
00856 
00857         /* Requesting action from porter(s): override this API if this capability
00858            is supported. */
00859         return BLE_ERROR_NOT_IMPLEMENTED;
00860     }
00861 
00862     /**
00863      * Fetch the current address and its type.
00864      *
00865      * @param[out] typeP Type of the current address set.
00866      * @param[out] address Value of the current address.
00867      *
00868      * @return BLE_ERROR_NONE on success.
00869      */
00870     virtual ble_error_t getAddress(
00871         BLEProtocol::AddressType_t *typeP,
00872         BLEProtocol::AddressBytes_t address
00873     ) {
00874         /* Avoid compiler warnings about unused variables. */
00875         (void)typeP;
00876         (void)address;
00877 
00878         /* Requesting action from porter(s): override this API if this capability
00879            is supported. */
00880         return BLE_ERROR_NOT_IMPLEMENTED;
00881     }
00882 
00883     /**
00884      * Get the minimum advertising interval in milliseconds, which can be used
00885      * for connectable advertising types.
00886      *
00887      * @return Minimum Advertising interval in milliseconds for connectable
00888      * undirected and connectable directed advertising types.
00889      */
00890     virtual uint16_t getMinAdvertisingInterval(void) const
00891     {
00892         /* Requesting action from porter(s): override this API if this capability
00893            is supported. */
00894         return 0;
00895     }
00896 
00897     /**
00898      * Get the minimum advertising interval in milliseconds, which can be
00899      * used for nonconnectable advertising type.
00900      *
00901      * @return Minimum Advertising interval in milliseconds for scannable
00902      * undirected and nonconnectable undirected event types.
00903      */
00904     virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const
00905     {
00906         /* Requesting action from porter(s): override this API if this capability
00907            is supported. */
00908         return 0;
00909     }
00910 
00911     /**
00912      * Get the maximum advertising interval in milliseconds.
00913      *
00914      * @return Maximum Advertising interval in milliseconds.
00915      */
00916     virtual uint16_t getMaxAdvertisingInterval(void) const
00917     {
00918         /* Requesting action from porter(s): override this API if this capability
00919            is supported. */
00920         return 0xFFFF;
00921     }
00922 
00923     /**
00924      * Stop the ongoing advertising procedure.
00925      *
00926      * @note The current advertising parameters remain in effect.
00927      *
00928      * @retval BLE_ERROR_NONE if the advertising procedure has been successfully
00929      * stopped.
00930      */
00931     virtual ble_error_t stopAdvertising(void)
00932     {
00933         /* Requesting action from porter(s): override this API if this capability
00934            is supported. */
00935         return BLE_ERROR_NOT_IMPLEMENTED;
00936     }
00937 
00938     /**
00939      * Stop the ongoing scanning procedure.
00940      *
00941      * The current scanning parameters remain in effect.
00942      *
00943      * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
00944      */
00945     virtual ble_error_t stopScan()
00946     {
00947         /* Requesting action from porter(s): override this API if this capability
00948            is supported. */
00949         return BLE_ERROR_NOT_IMPLEMENTED;
00950     }
00951 
00952     /**
00953      * Initiate a connection to a peer.
00954      *
00955      * Once the connection is established, a ConnectionCallbackParams_t event is
00956      * emitted to handlers that have been registered with onConnection().
00957      *
00958      * @param[in] peerAddr MAC address of the peer. It must be in LSB format.
00959      * @param[in] peerAddrType Address type of the peer.
00960      * @param[in] connectionParams Connection parameters to use.
00961      * @param[in] scanParams Scan parameters used to find the peer.
00962      *
00963      * @return BLE_ERROR_NONE if connection establishment procedure is started
00964      * successfully. The connectionCallChain (if set) is invoked upon
00965      * a connection event.
00966      */
00967     virtual ble_error_t connect(
00968         const BLEProtocol::AddressBytes_t peerAddr,
00969         BLEProtocol::AddressType_t peerAddrType,
00970         const ConnectionParams_t *connectionParams,
00971         const GapScanningParams *scanParams
00972     ) {
00973         /* Avoid compiler warnings about unused variables. */
00974         (void)peerAddr;
00975         (void)peerAddrType;
00976         (void)connectionParams;
00977         (void)scanParams;
00978 
00979         /* Requesting action from porter(s): override this API if this capability
00980            is supported. */
00981         return BLE_ERROR_NOT_IMPLEMENTED;
00982     }
00983 
00984     /**
00985      * Initiate a connection to a peer.
00986      *
00987      * @see connect()
00988      *
00989      * @deprecated  This funtion overloads Gap::connect(
00990      *      const BLEProtocol::Address_t peerAddr,
00991      *      BLEProtocol::AddressType_t peerAddrType,
00992      *      const ConnectionParams_t *connectionParams,
00993      *      const GapScanningParams *scanParams
00994      * )
00995      * to maintain backward compatibility for changes from Gap::AddressType_t to
00996      * BLEProtocol::AddressType_t.
00997      */
00998     MBED_DEPRECATED("Gap::DeprecatedAddressType_t is deprecated, use BLEProtocol::AddressType_t instead")
00999     ble_error_t connect(
01000         const BLEProtocol::AddressBytes_t peerAddr,
01001         DeprecatedAddressType_t peerAddrType,
01002         const ConnectionParams_t *connectionParams,
01003         const GapScanningParams *scanParams
01004     ) {
01005         return connect(
01006             peerAddr,
01007             (BLEProtocol::AddressType_t)
01008             peerAddrType,
01009             connectionParams,
01010             scanParams
01011         );
01012     }
01013 
01014     /**
01015      * Initiate a disconnection procedure.
01016      *
01017      * Once the disconnection procedure has completed a
01018      * DisconnectionCallbackParams_t, the event is emitted to handlers that
01019      * have been registered with onDisconnection().
01020      *
01021      * @param[in] reason Reason of the disconnection transmitted to the peer.
01022      * @param[in] connectionHandle Handle of the connection to end.
01023      *
01024      * @return  BLE_ERROR_NONE if the disconnection procedure successfully
01025      * started.
01026      */
01027     virtual ble_error_t disconnect(
01028         Handle_t connectionHandle, DisconnectionReason_t reason
01029     ) {
01030         /* avoid compiler warnings about unused variables */
01031         (void)connectionHandle;
01032         (void)reason;
01033 
01034         /* Requesting action from porter(s): override this API if this capability
01035            is supported. */
01036         return BLE_ERROR_NOT_IMPLEMENTED;
01037     }
01038 
01039     /**
01040      * Initiate a disconnection procedure.
01041      *
01042      * @deprecated This version of disconnect() doesn't take a connection handle.
01043      * It works reliably only for stacks that are limited to a single connection.
01044      * Use Gap::disconnect(Handle_t connectionHandle, DisconnectionReason_t reason)
01045      * instead.
01046      *
01047      * @param[in] reason The reason for disconnection; to be sent back to the peer.
01048      *
01049      * @return BLE_ERROR_NONE if disconnection was successful.
01050      */
01051     MBED_DEPRECATED("Use disconnect(Handle_t, DisconnectionReason_t) instead.")
01052     virtual ble_error_t disconnect(DisconnectionReason_t reason) {
01053         /* Avoid compiler warnings about unused variables. */
01054         (void)reason;
01055 
01056         /* Requesting action from porter(s): override this API if this capability
01057            is supported. */
01058         return BLE_ERROR_NOT_IMPLEMENTED;
01059     }
01060 
01061     /**
01062      * Returned the preferred connection parameters exposed in the GATT Generic
01063      * Access Service.
01064      *
01065      * @param[out] params Structure where the parameters are stored.
01066      *
01067      * @return BLE_ERROR_NONE if the parameters were successfully filled into
01068      * @p params.
01069      */
01070     virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params)
01071     {
01072         /* Avoid compiler warnings about unused variables. */
01073         (void)params;
01074 
01075         /* Requesting action from porter(s): override this API if this capability
01076            is supported. */
01077         return BLE_ERROR_NOT_IMPLEMENTED;
01078     }
01079 
01080     /**
01081      * Set the value of the preferred connection parameters exposed in the GATT
01082      * Generic Access Service.
01083      *
01084      * A connected peer may read the characteristic exposing these parameters
01085      * and request an update of the connection parameters to accomodate the
01086      * local device.
01087      *
01088      * @param[in] params Value of the preferred connection parameters.
01089      *
01090      * @return BLE_ERROR_NONE if the preferred connection params were set
01091      * correctly.
01092      */
01093     virtual ble_error_t setPreferredConnectionParams(
01094         const ConnectionParams_t *params
01095     ) {
01096         /* Avoid compiler warnings about unused variables. */
01097         (void)params;
01098 
01099         /* Requesting action from porter(s): override this API if this capability
01100            is supported. */
01101         return BLE_ERROR_NOT_IMPLEMENTED;
01102     }
01103 
01104     /**
01105      * Update connection parameters of an existing connection.
01106      *
01107      * In the central role, this initiates a Link Layer connection parameter
01108      * update procedure. In the peripheral role, this sends the corresponding
01109      * L2CAP request and waits for the central to perform the procedure.
01110      *
01111      * @param[in] handle Connection Handle.
01112      * @param[in] params Pointer to desired connection parameters.
01113      *
01114      * @return BLE_ERROR_NONE if the connection parameters were updated correctly.
01115      */
01116     virtual ble_error_t updateConnectionParams(
01117         Handle_t handle,
01118         const ConnectionParams_t *params
01119     ) {
01120         /* avoid compiler warnings about unused variables */
01121         (void)handle;
01122         (void)params;
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      * Set the value of the device name characteristic in the Generic Access
01131      * Service.
01132      *
01133      * @param[in] deviceName The new value for the device-name. This is a
01134      * UTF-8 encoded, <b>NULL-terminated</b> string.
01135      *
01136      * @return BLE_ERROR_NONE if the device name was set correctly.
01137      */
01138     virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
01139         /* Avoid compiler warnings about unused variables. */
01140         (void)deviceName;
01141 
01142         /* Requesting action from porter(s): override this API if this capability
01143            is supported. */
01144         return BLE_ERROR_NOT_IMPLEMENTED;
01145     }
01146 
01147     /**
01148      * Get the value of the device name characteristic in the Generic Access
01149      * Service.
01150      *
01151      * To obtain the length of the deviceName value, this function is
01152      * invoked with the @p deviceName parameter set to NULL.
01153      *
01154      * @param[out] deviceName Pointer to an empty buffer where the UTF-8
01155      * <b>non NULL-terminated</b> string is placed.
01156      *
01157      * @param[in,out] lengthP Length of the @p deviceName buffer. If the device
01158      * name is successfully copied, then the length of the device name
01159      * string (excluding the null terminator) replaces this value.
01160      *
01161      * @return BLE_ERROR_NONE if the device name was fetched correctly from the
01162      * underlying BLE stack.
01163      *
01164      * @note If the device name is longer than the size of the supplied buffer,
01165      * length returns the complete device name length and not the number of
01166      * bytes actually returned in deviceName. The application may use this
01167      * information to retry with a suitable buffer size.
01168      */
01169     virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP)
01170     {
01171         /* avoid compiler warnings about unused variables */
01172         (void)deviceName;
01173         (void)lengthP;
01174 
01175         /* Requesting action from porter(s): override this API if this capability
01176            is supported. */
01177         return BLE_ERROR_NOT_IMPLEMENTED;
01178     }
01179 
01180     /**
01181      * Set the value of the appearance characteristic in the GAP service.
01182      *
01183      * @param[in] appearance The new value for the device-appearance.
01184      *
01185      * @return BLE_ERROR_NONE if the new appearance was set correctly.
01186      */
01187     virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance)
01188     {
01189         /* Avoid compiler warnings about unused variables. */
01190         (void)appearance;
01191 
01192         /* Requesting action from porter(s): override this API if this capability
01193            is supported. */
01194         return BLE_ERROR_NOT_IMPLEMENTED;
01195     }
01196 
01197     /**
01198      * Get the value of the appearance characteristic in the GAP service.
01199      *
01200      * @param[out] appearanceP The current device-appearance value.
01201      *
01202      * @return BLE_ERROR_NONE if the device-appearance was fetched correctly
01203      * from the underlying BLE stack.
01204      */
01205     virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP)
01206     {
01207         /* Avoid compiler warnings about unused variables. */
01208         (void)appearanceP;
01209 
01210         /* Requesting action from porter(s): override this API if this capability
01211            is supported. */
01212         return BLE_ERROR_NOT_IMPLEMENTED;
01213     }
01214 
01215     /**
01216      * Set the radio's transmit power.
01217      *
01218      * @param[in] txPower Radio's transmit power in dBm.
01219      *
01220      * @return BLE_ERROR_NONE if the new radio's transmit power was set
01221      * correctly.
01222      */
01223     virtual ble_error_t setTxPower(int8_t txPower)
01224     {
01225         /* Avoid compiler warnings about unused variables. */
01226         (void)txPower;
01227 
01228         /* Requesting action from porter(s): override this API if this capability
01229            is supported. */
01230         return BLE_ERROR_NOT_IMPLEMENTED;
01231     }
01232 
01233     /**
01234      * Query the underlying stack for allowed Tx power values.
01235      *
01236      * @param[out] valueArrayPP Receive the immutable array of Tx values.
01237      * @param[out] countP Receive the array's size.
01238      */
01239     virtual void getPermittedTxPowerValues(
01240         const int8_t **valueArrayPP, size_t *countP
01241     ) {
01242         /* Avoid compiler warnings about unused variables. */
01243         (void)valueArrayPP;
01244         (void)countP;
01245 
01246         /* Requesting action from porter(s): override this API if this capability
01247            is supported. */
01248         *countP = 0;
01249     }
01250 
01251     /**
01252      * Get the maximum size of the whitelist.
01253      *
01254      * @return Maximum size of the whitelist.
01255      *
01256      * @note If using Mbed OS, you can configure the size of the whitelist by
01257      * setting the YOTTA_CFG_WHITELIST_MAX_SIZE macro in your yotta config file.
01258      */
01259     virtual uint8_t getMaxWhitelistSize(void) const
01260     {
01261         return 0;
01262     }
01263 
01264     /**
01265      * Get the Link Layer to use the internal whitelist when scanning,
01266      * advertising or initiating a connection depending on the filter policies.
01267      *
01268      * @param[in,out] whitelist Define the whitelist instance which is used
01269      * to store the whitelist requested. In input, the caller provisions memory.
01270      *
01271      * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
01272      * copied into the supplied reference.
01273      */
01274     virtual ble_error_t getWhitelist(Whitelist_t &whitelist) const
01275     {
01276         (void) whitelist;
01277         return BLE_ERROR_NOT_IMPLEMENTED;
01278     }
01279 
01280     /**
01281      * Set the value of the whitelist to be used during GAP procedures.
01282      *
01283      * @param[in] whitelist A reference to a whitelist containing the addresses
01284      * to be copied to the internal whitelist.
01285      *
01286      * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
01287      * populated with the addresses in the given whitelist.
01288      *
01289      * @note The whitelist must not contain addresses of type @ref
01290      * BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE. This
01291      * results in a @ref BLE_ERROR_INVALID_PARAM because the remote peer might
01292      * change its private address at any time, and it is not possible to resolve
01293      * it.
01294      *
01295      * @note If the input whitelist is larger than @ref getMaxWhitelistSize(),
01296      * then @ref BLE_ERROR_PARAM_OUT_OF_RANGE is returned.
01297      */
01298     virtual ble_error_t setWhitelist(const Whitelist_t &whitelist)
01299     {
01300         (void) whitelist;
01301         return BLE_ERROR_NOT_IMPLEMENTED;
01302     }
01303 
01304     /**
01305      * Set the advertising policy filter mode to be used during the next
01306      * advertising procedure.
01307      *
01308      * @param[in] mode New advertising policy filter mode.
01309      *
01310      * @return BLE_ERROR_NONE if the specified policy filter mode was set
01311      * successfully.
01312      */
01313     virtual ble_error_t setAdvertisingPolicyMode(AdvertisingPolicyMode_t mode)
01314     {
01315         (void) mode;
01316         return BLE_ERROR_NOT_IMPLEMENTED;
01317     }
01318 
01319     /**
01320      * Set the scan policy filter mode to be used during the next scan procedure.
01321      *
01322      * @param[in] mode New scan policy filter mode.
01323      *
01324      * @return BLE_ERROR_NONE if the specified policy filter mode was set
01325      * successfully.
01326      */
01327     virtual ble_error_t setScanningPolicyMode(ScanningPolicyMode_t mode)
01328     {
01329         (void) mode;
01330         return BLE_ERROR_NOT_IMPLEMENTED;
01331     }
01332 
01333     /**
01334      * Set the initiator policy filter mode to be used during the next connection
01335      * initiation.
01336      *
01337      * @param[in] mode New initiator policy filter mode.
01338      *
01339      * @return BLE_ERROR_NONE if the specified policy filter mode was set
01340      * successfully.
01341      */
01342     virtual ble_error_t setInitiatorPolicyMode(InitiatorPolicyMode_t mode)
01343     {
01344         (void) mode;
01345         return BLE_ERROR_NOT_IMPLEMENTED;
01346     }
01347 
01348     /**
01349      * Get the current advertising policy filter mode.
01350      *
01351      * @return The current advertising policy filter mode.
01352      */
01353     virtual AdvertisingPolicyMode_t getAdvertisingPolicyMode(void) const
01354     {
01355         return ADV_POLICY_IGNORE_WHITELIST;
01356     }
01357 
01358     /**
01359      * Get the current scan policy filter mode.
01360      *
01361      * @return The current scan policy filter mode.
01362      */
01363     virtual ScanningPolicyMode_t getScanningPolicyMode(void) const
01364     {
01365         return SCAN_POLICY_IGNORE_WHITELIST;
01366     }
01367 
01368     /**
01369      * Get the current initiator policy filter mode.
01370      *
01371      * @return The current scan policy filter mode.
01372      */
01373     virtual InitiatorPolicyMode_t getInitiatorPolicyMode(void) const
01374     {
01375         return INIT_POLICY_IGNORE_WHITELIST;
01376     }
01377 
01378 protected:
01379     /* Override the following in the underlying adaptation layer to provide the
01380       functionality of scanning. */
01381 
01382     /**
01383      * Start scanning procedure in the underlying BLE stack.
01384      *
01385      * @param[in] scanningParams Parameters of the scan procedure.
01386      *
01387      * @return BLE_ERROR_NONE if the scan procedure was successfully started.
01388      */
01389     virtual ble_error_t startRadioScan(const GapScanningParams &scanningParams)
01390     {
01391         (void)scanningParams;
01392         /* Requesting action from porter(s): override this API if this capability
01393            is supported. */
01394         return BLE_ERROR_NOT_IMPLEMENTED;
01395     }
01396 
01397     /*
01398      * APIs with nonvirtual implementations.
01399      */
01400 public:
01401     /**
01402      * Get the current advertising and connection states of the device.
01403      *
01404      * @return The current GAP state of the device.
01405      */
01406     GapState_t getState(void) const
01407     {
01408         return state;
01409     }
01410 
01411     /**
01412      * Set the advertising type to use during the advertising procedure.
01413      *
01414      * @param[in] advType New type of advertising to use.
01415      */
01416     void setAdvertisingType(GapAdvertisingParams::AdvertisingType_t advType)
01417     {
01418         _advParams.setAdvertisingType(advType);
01419     }
01420 
01421     /**
01422      * Set the advertising interval.
01423      *
01424      * @param[in] interval Advertising interval in units of milliseconds.
01425      * Advertising is disabled if interval is 0. If interval is smaller than
01426      * the minimum supported value, then the minimum supported value is used
01427      * instead. This minimum value can be discovered using
01428      * getMinAdvertisingInterval().
01429      *
01430      * This field must be set to 0 if connectionMode is equal
01431      * to ADV_CONNECTABLE_DIRECTED.
01432      *
01433      * @note  Decreasing this value allows central devices to detect a
01434      * peripheral faster, at the expense of the radio using more power
01435      * due to the higher data transmit rate.
01436      */
01437     void setAdvertisingInterval(uint16_t interval)
01438     {
01439         if (interval == 0) {
01440             stopAdvertising();
01441         } else if (interval < getMinAdvertisingInterval()) {
01442             interval = getMinAdvertisingInterval();
01443         }
01444         _advParams.setInterval(interval);
01445     }
01446 
01447     /**
01448      * Set the advertising duration.
01449      *
01450      * A timeout event is genenerated once the advertising period expired.
01451      *
01452      * @param[in] timeout Advertising timeout (in seconds) between 0x1 and 0x3FFF.
01453      * The special value 0 may be used to disable the advertising timeout.
01454      */
01455     void setAdvertisingTimeout(uint16_t timeout)
01456     {
01457         _advParams.setTimeout(timeout);
01458     }
01459 
01460     /**
01461      * Start the advertising procedure.
01462      *
01463      * @return BLE_ERROR_NONE if the device started advertising successfully.
01464      */
01465     ble_error_t startAdvertising(void)
01466     {
01467         ble_error_t rc;
01468         if ((rc = startAdvertising(_advParams)) == BLE_ERROR_NONE) {
01469             state.advertising = 1;
01470         }
01471         return rc;
01472     }
01473 
01474     /**
01475      * Reset the value of the advertising payload advertised.
01476      */
01477     void clearAdvertisingPayload(void)
01478     {
01479         _advPayload.clear();
01480         setAdvertisingData(_advPayload, _scanResponse);
01481     }
01482 
01483     /**
01484      * Set gap flags in the advertising payload.
01485      *
01486      * A call to this function is equivalent to:
01487      *
01488      * @code
01489      * Gap &gap;
01490      *
01491      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01492      * payload.addFlags(flags);
01493      * gap.setAdvertisingPayload(payload);
01494      * @endcode
01495      *
01496      * @param[in] flags The flags to be added.
01497      *
01498      * @return BLE_ERROR_NONE if the data was successfully added to the
01499      * advertising payload.
01500      */
01501     ble_error_t accumulateAdvertisingPayload(uint8_t flags)
01502     {
01503         GapAdvertisingData advPayloadCopy = _advPayload;
01504         ble_error_t rc;
01505         if ((rc = advPayloadCopy.addFlags(flags)) != BLE_ERROR_NONE) {
01506             return rc;
01507         }
01508 
01509         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01510         if (rc == BLE_ERROR_NONE) {
01511             _advPayload = advPayloadCopy;
01512         }
01513 
01514         return rc;
01515     }
01516 
01517     /**
01518      * Set the appearance field in the advertising payload.
01519      *
01520      * A call to this function is equivalent to:
01521      *
01522      * @code
01523      * Gap &gap;
01524      *
01525      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01526      * payload.addAppearance(app);
01527      * gap.setAdvertisingPayload(payload);
01528      * @endcode
01529      *
01530      * @param[in] app The appearance to advertise.
01531      *
01532      * @return BLE_ERROR_NONE if the data was successfully added to the
01533      * advertising payload.
01534      */
01535     ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app)
01536     {
01537         GapAdvertisingData advPayloadCopy = _advPayload;
01538         ble_error_t rc;
01539         if ((rc = advPayloadCopy.addAppearance(app)) != BLE_ERROR_NONE) {
01540             return rc;
01541         }
01542 
01543         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01544         if (rc == BLE_ERROR_NONE) {
01545             _advPayload = advPayloadCopy;
01546         }
01547 
01548         return rc;
01549     }
01550 
01551     /**
01552      * Set the Tx Power field in the advertising payload.
01553      *
01554      * A call to this function is equivalent to:
01555      *
01556      * @code
01557      * Gap &gap;
01558      *
01559      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01560      * payload.addTxPower(power);
01561      * gap.setAdvertisingPayload(payload);
01562      * @endcode
01563      *
01564      * @param[in] power Transmit power in dBm used by the controller to advertise.
01565      *
01566      * @return BLE_ERROR_NONE if the data was successfully added to the
01567      * advertising payload.
01568      */
01569     ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power)
01570     {
01571         GapAdvertisingData advPayloadCopy = _advPayload;
01572         ble_error_t rc;
01573         if ((rc = advPayloadCopy.addTxPower(power)) != BLE_ERROR_NONE) {
01574             return rc;
01575         }
01576 
01577         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01578         if (rc == BLE_ERROR_NONE) {
01579             _advPayload = advPayloadCopy;
01580         }
01581 
01582         return rc;
01583     }
01584 
01585     /**
01586      * Add a new field in the advertising payload.
01587      *
01588      * A call to this function is equivalent to:
01589      *
01590      * @code
01591      * Gap &gap;
01592      *
01593      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01594      * payload.addData(type, data, len);
01595      * gap.setAdvertisingPayload(payload);
01596      * @endcode
01597      *
01598      * @param[in] type Identity of the field being added.
01599      * @param[in] data Buffer containing the value of the field.
01600      * @param[in] len Length of the data buffer.
01601      *
01602      * @return BLE_ERROR_NONE if the advertisement payload was updated based on
01603      * matching AD type; otherwise, an appropriate error.
01604      *
01605      * @note When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS,
01606      * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS,
01607      * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS,
01608      * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the
01609      * supplied value is appended to the values previously added to the payload.
01610      */
01611     ble_error_t accumulateAdvertisingPayload(
01612         GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len
01613     ) {
01614         GapAdvertisingData advPayloadCopy = _advPayload;
01615         ble_error_t rc;
01616         if ((rc = advPayloadCopy.addData(type, data, len)) != BLE_ERROR_NONE) {
01617             return rc;
01618         }
01619 
01620         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01621         if (rc == BLE_ERROR_NONE) {
01622             _advPayload = advPayloadCopy;
01623         }
01624 
01625         return rc;
01626     }
01627 
01628     /**
01629      * Update a particular field in the advertising payload.
01630      *
01631      * A call to this function is equivalent to:
01632      *
01633      * @code
01634      * Gap &gap;
01635      *
01636      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01637      * payload.updateData(type, data, len);
01638      * gap.setAdvertisingPayload(payload);
01639      * @endcode
01640      *
01641      *
01642      * @param[in] type Id of the field to update.
01643      * @param[in] data data buffer containing the new value of the field.
01644      * @param[in] len Length of the data buffer.
01645      *
01646      * @note If advertisements are enabled, then the update takes effect
01647      * immediately.
01648      *
01649      * @return BLE_ERROR_NONE if the advertisement payload was updated based on
01650      * matching AD type; otherwise, an appropriate error.
01651      */
01652     ble_error_t updateAdvertisingPayload(
01653         GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len
01654     ) {
01655         GapAdvertisingData advPayloadCopy = _advPayload;
01656         ble_error_t rc;
01657         if ((rc = advPayloadCopy.updateData(type, data, len)) != BLE_ERROR_NONE) {
01658             return rc;
01659         }
01660 
01661         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01662         if (rc == BLE_ERROR_NONE) {
01663             _advPayload = advPayloadCopy;
01664         }
01665 
01666         return rc;
01667     }
01668 
01669     /**
01670      * Set the value of the payload advertised.
01671      *
01672      * @param[in] payload A reference to a user constructed advertisement
01673      * payload to set.
01674      *
01675      * @return BLE_ERROR_NONE if the advertisement payload was successfully
01676      * set.
01677      */
01678     ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload)
01679     {
01680         ble_error_t rc = setAdvertisingData(payload, _scanResponse);
01681         if (rc == BLE_ERROR_NONE) {
01682             _advPayload = payload;
01683         }
01684 
01685         return rc;
01686     }
01687 
01688     /**
01689      * Get a reference to the current advertising payload.
01690      *
01691      * @return A reference to the current advertising payload.
01692      */
01693     const GapAdvertisingData &getAdvertisingPayload(void) const
01694     {
01695         return _advPayload;
01696     }
01697 
01698     /**
01699      * Add a new field in the advertising payload.
01700      *
01701      * @param[in] type AD type identifier.
01702      * @param[in] data buffer containing AD data.
01703      * @param[in] len Length of the data buffer.
01704      *
01705      * @return BLE_ERROR_NONE if the data was successfully added to the scan
01706      * response payload.
01707      */
01708     ble_error_t accumulateScanResponse(
01709         GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len
01710     ) {
01711         GapAdvertisingData scanResponseCopy = _scanResponse;
01712         ble_error_t rc;
01713         if ((rc = scanResponseCopy.addData(type, data, len)) != BLE_ERROR_NONE) {
01714             return rc;
01715         }
01716 
01717         rc = setAdvertisingData(_advPayload, scanResponseCopy);
01718         if (rc == BLE_ERROR_NONE) {
01719             _scanResponse = scanResponseCopy;
01720         }
01721 
01722         return rc;
01723     }
01724 
01725     /**
01726      * Reset the content of the scan response.
01727      *
01728      * @note This should be followed by a call to Gap::setAdvertisingPayload()
01729      * or Gap::startAdvertising() before the update takes effect.
01730      */
01731     void clearScanResponse(void) {
01732         _scanResponse.clear();
01733         setAdvertisingData(_advPayload, _scanResponse);
01734     }
01735 
01736     /**
01737      * Set the parameters used during a scan procedure.
01738      *
01739      * @param[in] interval in ms between the start of two consecutive scan windows.
01740      * That value is greater or equal to the scan window value. The
01741      * maximum allowed value is 10.24ms.
01742      *
01743      * @param[in] window Period in ms during which the scanner listens to
01744      * advertising channels. That value is in the range 2.5ms to 10.24s.
01745      *
01746      * @param[in] timeout Duration in seconds of the scan procedure if any. The
01747      * special value 0 disable specific duration of the scan procedure.
01748      *
01749      * @param[in] activeScanning If set to true, then the scanner sends scan
01750      * requests to a scannable or connectable advertiser. If set to false, then the
01751      * scanner does not send any request during the scan procedure.
01752      *
01753      * @return BLE_ERROR_NONE if the scan parameters were correctly set.
01754      *
01755      * @note The scanning window divided by the interval determines the duty
01756      * cycle for scanning. For example, if the interval is 100ms and the window
01757      * is 10ms, then the controller scans for 10 percent of the time.
01758      *
01759      * @note If the interval and the window are set to the same value, then the
01760      * device scans continuously during the scan procedure. The scanning
01761      * frequency changes at every interval.
01762      *
01763      * @note Once the scanning parameters have been configured, scanning can be
01764      * enabled by using startScan().
01765      *
01766      * @note The scan interval and window are recommendations to the BLE stack.
01767      */
01768     ble_error_t setScanParams(
01769         uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
01770         uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
01771         uint16_t timeout = 0,
01772         bool activeScanning = false
01773     ) {
01774         ble_error_t rc;
01775         if (((rc = _scanningParams.setInterval(interval)) == BLE_ERROR_NONE) &&
01776             ((rc = _scanningParams.setWindow(window))     == BLE_ERROR_NONE) &&
01777             ((rc = _scanningParams.setTimeout(timeout))   == BLE_ERROR_NONE)) {
01778             _scanningParams.setActiveScanning(activeScanning);
01779             return BLE_ERROR_NONE;
01780         }
01781 
01782         return rc;
01783     }
01784 
01785     /**
01786      * Set the interval parameter used during scanning procedures.
01787      *
01788      * @param[in] interval Interval in ms between the start of two consecutive
01789      * scan windows. That value is greater or equal to the scan window value.
01790      * The maximum allowed value is 10.24ms.
01791      *
01792      * @return BLE_ERROR_NONE if the scan interval was correctly set.
01793      */
01794     ble_error_t setScanInterval(uint16_t interval)
01795     {
01796         return _scanningParams.setInterval(interval);
01797     }
01798 
01799     /**
01800      * Set the window parameter used during scanning procedures.
01801      *
01802      * @param[in] window Period in ms during which the scanner listens to
01803      * advertising channels. That value is in the range 2.5ms to 10.24s.
01804      *
01805      * @return BLE_ERROR_NONE if the scan window was correctly set.
01806      *
01807      * @note If scanning is already active, the updated value of scanWindow
01808      * is propagated to the underlying BLE stack.
01809      */
01810     ble_error_t setScanWindow(uint16_t window)
01811     {
01812         ble_error_t rc;
01813         if ((rc = _scanningParams.setWindow(window)) != BLE_ERROR_NONE) {
01814             return rc;
01815         }
01816 
01817         /* If scanning is already active, propagate the new setting to the stack. */
01818         if (scanningActive) {
01819             return startRadioScan(_scanningParams);
01820         }
01821 
01822         return BLE_ERROR_NONE;
01823     }
01824 
01825     /**
01826      * Set the timeout parameter used during scanning procedures.
01827      *
01828      * @param[in] timeout Duration in seconds of the scan procedure if any. The
01829      * special value 0 disables specific duration of the scan procedure.
01830      *
01831      * @return BLE_ERROR_NONE if the scan timeout was correctly set.
01832      *
01833      * @note If scanning is already active, the updated value of scanTimeout
01834      * is propagated to the underlying BLE stack.
01835      */
01836     ble_error_t setScanTimeout(uint16_t timeout)
01837     {
01838         ble_error_t rc;
01839         if ((rc = _scanningParams.setTimeout(timeout)) != BLE_ERROR_NONE) {
01840             return rc;
01841         }
01842 
01843         /* If scanning is already active, propagate the new settings to the stack. */
01844         if (scanningActive) {
01845             return startRadioScan(_scanningParams);
01846         }
01847 
01848         return BLE_ERROR_NONE;
01849     }
01850 
01851     /**
01852      * Enable or disable active scanning.
01853      *
01854      * @param[in] activeScanning If set to true, then the scanner sends scan
01855      * requests to a scannable or connectable advertiser. If set to false then the
01856      * scanner does not send any request during the scan procedure.
01857      *
01858      * @return BLE_ERROR_NONE if active scanning was successfully set.
01859      *
01860      * @note If scanning is already in progress, then active scanning is
01861      * enabled for the underlying BLE stack.
01862      */
01863     ble_error_t setActiveScanning(bool activeScanning)
01864     {
01865         _scanningParams.setActiveScanning(activeScanning);
01866 
01867         /* If scanning is already active, propagate the new settings to the stack. */
01868         if (scanningActive) {
01869             return startRadioScan(_scanningParams);
01870         }
01871 
01872         return BLE_ERROR_NONE;
01873     }
01874 
01875     /**
01876      * Start the scanning procedure.
01877      *
01878      * Packets received during the scan procedure are forwarded to the
01879      * scan packet handler passed as argument to this function.
01880      *
01881      * @param[in] callback Advertisement packet event handler. Upon reception
01882      * of an advertising packet, the packet is forwarded to @p callback.
01883      *
01884      * @return BLE_ERROR_NONE if the device successfully started the scan
01885      *         procedure.
01886      *
01887      * @note The parameters used by the procedure are defined by setScanParams().
01888      */
01889     ble_error_t startScan(
01890         void (*callback)(const AdvertisementCallbackParams_t *params)
01891     ) {
01892         ble_error_t err = BLE_ERROR_NONE;
01893         if (callback) {
01894             if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
01895                 scanningActive = true;
01896                 onAdvertisementReport.attach(callback);
01897             }
01898         }
01899 
01900         return err;
01901     }
01902 
01903     /**
01904      * Start the scanning procedure.
01905      *
01906      * Packets received during the scan procedure are forwarded to the
01907      * scan packet handler passed as argument to this function.
01908      *
01909      * @param[in] object Instance used to invoke @p callbackMember.
01910      *
01911      * @param[in] callbackMember Advertisement packet event handler. Upon
01912      * reception of an advertising packet, the packet is forwarded to @p
01913      * callback invoked from @p object.
01914      *
01915      * @return BLE_ERROR_NONE if the device successfully started the scan
01916      * procedure.
01917      *
01918      * @note The parameters used by the procedure are defined by setScanParams().
01919      */
01920     template<typename T>
01921     ble_error_t startScan(
01922         T *object,
01923         void (T::*callbackMember)(const AdvertisementCallbackParams_t *params)
01924     ) {
01925         ble_error_t err = BLE_ERROR_NONE;
01926         if (object && callbackMember) {
01927             if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
01928                 scanningActive = true;
01929                 onAdvertisementReport.attach(object, callbackMember);
01930             }
01931         }
01932 
01933         return err;
01934     }
01935 
01936     /**
01937      * Enable radio-notification events.
01938      *
01939      * Radio Notification is a feature that notifies the application when the
01940      * radio is in use.
01941      *
01942      * The ACTIVE signal is sent before the radio event starts. The nACTIVE
01943      * signal is sent at the end of the radio event. The application programmer can
01944      * use these signals to synchronize application logic with radio
01945      * activity. For example, the ACTIVE signal can be used to shut off external
01946      * devices, to manage peak current drawn during periods when the radio is on
01947      * or to trigger sensor data collection for transmission in the Radio Event.
01948      *
01949      * @return BLE_ERROR_NONE on successful initialization, otherwise an error code.
01950      */
01951     virtual ble_error_t initRadioNotification(void)
01952     {
01953         /* Requesting action from porter(s): override this API if this capability
01954            is supported. */
01955         return BLE_ERROR_NOT_IMPLEMENTED;
01956     }
01957 
01958 private:
01959     /**
01960      * Set the advertising data and scan response in the vendor subsytem.
01961      *
01962      * @param[in] advData Advertising data to set.
01963      * @param[in] scanResponse Scan response to set.
01964      *
01965      * @return BLE_ERROR_NONE if the advertising data was set successfully.
01966      *
01967      * @note Must be implemented in vendor port.
01968      */
01969     virtual ble_error_t setAdvertisingData(
01970         const GapAdvertisingData &advData,
01971         const GapAdvertisingData &scanResponse
01972     ) = 0;
01973 
01974     /**
01975      * Start the advertising procedure.
01976      *
01977      * @param[in] params Advertising parameters to use.
01978      *
01979      * @return BLE_ERROR_NONE if the advertising procedure successfully
01980      * started.
01981      *
01982      * @note Must be implemented in vendor port.
01983      */
01984     virtual ble_error_t startAdvertising(const GapAdvertisingParams &params) = 0;
01985 
01986 public:
01987     /**
01988      * Get the current advertising parameters.
01989      *
01990      * @return A reference to the current advertising parameters.
01991      */
01992     GapAdvertisingParams &getAdvertisingParams(void)
01993     {
01994         return _advParams;
01995     }
01996 
01997     /**
01998      * Const alternative to Gap::getAdvertisingParams().
01999      *
02000      * @return A const reference to the current advertising parameters.
02001      */
02002     const GapAdvertisingParams &getAdvertisingParams(void) const
02003     {
02004         return _advParams;
02005     }
02006 
02007     /**
02008      * Set the advertising parameters.
02009      *
02010      * @param[in] newParams The new advertising parameters.
02011      */
02012     void setAdvertisingParams(const GapAdvertisingParams &newParams)
02013     {
02014         _advParams = newParams;
02015     }
02016 
02017     /* Event handlers. */
02018 public:
02019     /**
02020      * Register a callback handling timeout events.
02021      *
02022      * @param[in] callback Event handler being registered.
02023      *
02024      * @note A callback may be unregistered using onTimeout().detach(callback).
02025      *
02026      * @see TimeoutSource_t
02027      */
02028     void onTimeout(TimeoutEventCallback_t  callback)
02029     {
02030         timeoutCallbackChain.add(callback);
02031     }
02032 
02033     /**
02034      * Get the callchain of registered timeout event handlers.
02035      *
02036      * @note To register callbacks, use onTimeout().add(callback).
02037      *
02038      * @note To unregister callbacks, use onTimeout().detach(callback).
02039      *
02040      * @return A reference to the timeout event callbacks chain.
02041      */
02042     TimeoutEventCallbackChain_t & onTimeout()
02043     {
02044         return timeoutCallbackChain;
02045     }
02046 
02047     /**
02048      * Register a callback handling connection events.
02049      *
02050      * @param[in] callback Event handler being registered.
02051      *
02052      * @note A callback may be unregistered using onConnection().detach(callback).
02053      */
02054     void onConnection(ConnectionEventCallback_t  callback)
02055     {
02056         connectionCallChain.add(callback);
02057     }
02058 
02059     /**
02060      * Register a callback handling connection events.
02061      *
02062      * @param[in] tptr Instance used to invoke @p mptr.
02063      * @param[in] mptr Event handler being registered.
02064      *
02065      * @note A callback may be unregistered using onConnection().detach(callback).
02066      */
02067     template<typename T>
02068     void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*))
02069     {
02070         connectionCallChain.add(tptr, mptr);
02071     }
02072 
02073     /**
02074      * Get the callchain of registered connection event handlers.
02075      *
02076      * @note To register callbacks, use onConnection().add(callback).
02077      *
02078      * @note To unregister callbacks, use onConnection().detach(callback).
02079      *
02080      * @return A reference to the connection event callbacks chain.
02081      */
02082     ConnectionEventCallbackChain_t & onConnection()
02083     {
02084         return connectionCallChain;
02085     }
02086 
02087     /**
02088      * Register a callback handling disconnection events.
02089      *
02090      * @param[in] callback Event handler being registered.
02091      *
02092      * @note A callback may be unregistered using onDisconnection().detach(callback).
02093      */
02094     void onDisconnection(DisconnectionEventCallback_t  callback)
02095     {
02096         disconnectionCallChain.add(callback);
02097     }
02098 
02099     /**
02100      * Register a callback handling disconnection events.
02101      *
02102      * @param[in] tptr Instance used to invoke mptr.
02103      * @param[in] mptr Event handler being registered.
02104      *
02105      * @note A callback may be unregistered using onDisconnection().detach(callback).
02106      */
02107     template<typename T>
02108     void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*))
02109     {
02110         disconnectionCallChain.add(tptr, mptr);
02111     }
02112 
02113     /**
02114      * Get the callchain of registered disconnection event handlers.
02115      *
02116      * @note To register callbacks use onDisconnection().add(callback).
02117      *
02118      * @note To unregister callbacks use onDisconnection().detach(callback).
02119      *
02120      * @return A reference to the disconnection event callbacks chain.
02121      */
02122     DisconnectionEventCallbackChain_t & onDisconnection()
02123     {
02124         return disconnectionCallChain;
02125     }
02126 
02127     /**
02128      * Set the radio-notification events handler.
02129      *
02130      * Radio Notification is a feature that enables ACTIVE and INACTIVE
02131      * (nACTIVE) signals from the stack that notify the application when the
02132      * radio is in use.
02133      *
02134      * The ACTIVE signal is sent before the radio event starts. The nACTIVE
02135      * signal is sent at the end of the radio event. The application programmer can
02136      * use these signals to synchronize application logic with radio
02137      * activity. For example, the ACTIVE signal can be used to shut off external
02138      * devices, to manage peak current drawn during periods when the radio is on
02139      * or to trigger sensor data collection for transmission in the Radio Event.
02140      *
02141      * @param[in] callback Application handler to be invoked in response to a
02142      * radio ACTIVE/INACTIVE event.
02143      */
02144     void onRadioNotification(void (*callback)(bool param))
02145     {
02146         radioNotificationCallback.attach(callback);
02147     }
02148 
02149     /**
02150      * Set the radio-notification events handler.
02151      *
02152      * @param[in] tptr Instance to be used to invoke mptr.
02153      * @param[in] mptr Application handler to be invoked in response to a
02154      * radio ACTIVE/INACTIVE event.
02155      */
02156     template <typename T>
02157     void onRadioNotification(T *tptr, void (T::*mptr)(bool))
02158     {
02159         radioNotificationCallback.attach(tptr, mptr);
02160     }
02161 
02162     /**
02163      * Register a Gap shutdown event handler.
02164      *
02165      * The handler is called when the Gap instance is about to shut down.
02166      * It is usually issued after a call to BLE::shutdown().
02167      *
02168      * @param[in] callback Shutdown event handler to register.
02169      *
02170      * @note To unregister a shutdown event handler, use
02171      * onShutdown().detach(callback).
02172      */
02173     void onShutdown(const GapShutdownCallback_t & callback)
02174     {
02175         shutdownCallChain.add(callback);
02176     }
02177 
02178     /**
02179      * Register a Gap shutdown event handler.
02180      *
02181      * @param[in] objPtr Instance used to invoke @p memberPtr.
02182      * @param[in] memberPtr Shutdown event handler to register.
02183      */
02184     template <typename T>
02185     void onShutdown(T *objPtr, void (T::*memberPtr)(const Gap *))
02186     {
02187         shutdownCallChain.add(objPtr, memberPtr);
02188     }
02189 
02190     /**
02191      * Access the callchain of shutdown event handler.
02192      *
02193      * @note To register callbacks, use onShutdown().add(callback).
02194      *
02195      * @note To unregister callbacks, use onShutdown().detach(callback).
02196      *
02197      * @return A reference to the shutdown event callback chain.
02198      */
02199     GapShutdownCallbackChain_t & onShutdown()
02200     {
02201         return shutdownCallChain;
02202     }
02203 
02204 public:
02205     /**
02206      * Reset the Gap instance.
02207      *
02208      * Reset process starts by notifying all registered shutdown event handlers
02209      * that the Gap instance is about to be shut down. Then, it clears all Gap state
02210      * of the associated object and then cleans the state present in the vendor
02211      * implementation.
02212      *
02213      * This function is meant to be overridden in the platform-specific
02214      * subclass. Nevertheless, the subclass only resets its
02215      * state and not the data held in Gap members. This is achieved by a
02216      * call to Gap::reset() from the subclass' reset() implementation.
02217      *
02218      * @return BLE_ERROR_NONE on success.
02219      *
02220      * @note Currently, a call to reset() does not reset the advertising and
02221      * scan parameters to default values.
02222      */
02223     virtual ble_error_t reset(void)
02224     {
02225         /* Notify that the instance is about to shut down */
02226         shutdownCallChain.call(this);
02227         shutdownCallChain.clear();
02228 
02229         /* Clear Gap state */
02230         state.advertising = 0;
02231         state.connected   = 0;
02232         connectionCount   = 0;
02233 
02234         /* Clear scanning state */
02235         scanningActive = false;
02236 
02237         /* Clear advertising and scanning data */
02238         _advPayload.clear();
02239         _scanResponse.clear();
02240 
02241         /* Clear callbacks */
02242         timeoutCallbackChain.clear();
02243         connectionCallChain.clear();
02244         disconnectionCallChain.clear();
02245         radioNotificationCallback = NULL;
02246         onAdvertisementReport     = NULL;
02247 
02248         return BLE_ERROR_NONE;
02249     }
02250 
02251 protected:
02252     /**
02253      * Construct a Gap instance.
02254      */
02255     Gap() :
02256         _advParams(),
02257         _advPayload(),
02258         _scanningParams(),
02259         _scanResponse(),
02260         connectionCount(0),
02261         state(),
02262         scanningActive(false),
02263         timeoutCallbackChain(),
02264         radioNotificationCallback(),
02265         onAdvertisementReport(),
02266         connectionCallChain(),
02267         disconnectionCallChain() {
02268         _advPayload.clear();
02269         _scanResponse.clear();
02270     }
02271 
02272     /* Entry points for the underlying stack to report events back to the user. */
02273 public:
02274     /**
02275      * Notify all registered connection event handlers of a connection event.
02276      *
02277      * @attention This function is meant to be called from the BLE stack specific
02278      * implementation when a connection event occurs.
02279      *
02280      * @param[in] handle Handle of the new connection.
02281      * @param[in] role Role of this BLE device in the connection.
02282      * @param[in] peerAddrType Address type of the connected peer.
02283      * @param[in] peerAddr Address of the connected peer.
02284      * @param[in] ownAddrType Address type this device uses for this
02285      * connection.
02286      * @param[in] ownAddr Address this device uses for this connection.
02287      * @param[in] connectionParams Parameters of the connection.
02288      */
02289     void processConnectionEvent(
02290         Handle_t handle,
02291         Role_t role,
02292         BLEProtocol::AddressType_t peerAddrType,
02293         const BLEProtocol::AddressBytes_t peerAddr,
02294         BLEProtocol::AddressType_t ownAddrType,
02295         const BLEProtocol::AddressBytes_t ownAddr,
02296         const ConnectionParams_t *connectionParams
02297     ) {
02298         /* Update Gap state */
02299         state.advertising = 0;
02300         state.connected   = 1;
02301         ++connectionCount;
02302 
02303         ConnectionCallbackParams_t callbackParams(
02304             handle,
02305             role,
02306             peerAddrType,
02307             peerAddr,
02308             ownAddrType,
02309             ownAddr,
02310             connectionParams
02311         );
02312 
02313         connectionCallChain.call(&callbackParams);
02314     }
02315 
02316     /**
02317      * Notify all registered disconnection event handlers of a disconnection event.
02318      *
02319      * @attention This function is meant to be called from the BLE stack specific
02320      * implementation when a disconnection event occurs.
02321      *
02322      * @param[in] handle Handle of the terminated connection.
02323      * @param[in] reason Reason of the disconnection.
02324      */
02325     void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason)
02326     {
02327         /* Update Gap state */
02328         --connectionCount;
02329         if (!connectionCount) {
02330             state.connected = 0;
02331         }
02332 
02333         DisconnectionCallbackParams_t callbackParams(handle, reason);
02334         disconnectionCallChain.call(&callbackParams);
02335     }
02336 
02337     /**
02338      * Forward a received advertising packet to all registered event handlers
02339      * listening for scanned packet events.
02340      *
02341      * @attention This function is meant to be called from the BLE stack specific
02342      * implementation when a disconnection event occurs.
02343      *
02344      * @param[in] peerAddr Address of the peer that has emitted the packet.
02345      * @param[in] rssi Value of the RSSI measured for the received packet.
02346      * @param[in] isScanResponse If true, then the packet is a response to a scan
02347      * request.
02348      * @param[in] type Advertising type of the packet.
02349      * @param[in] advertisingDataLen Length of the advertisement data received.
02350      * @param[in] advertisingData Pointer to the advertisement packet's data.
02351      * @param[in] addressType Type of the address of the peer that has emitted the packet.
02352      */
02353     void processAdvertisementReport(
02354         const BLEProtocol::AddressBytes_t peerAddr,
02355         int8_t rssi,
02356         bool isScanResponse,
02357         GapAdvertisingParams::AdvertisingType_t type,
02358         uint8_t advertisingDataLen,
02359         const uint8_t *advertisingData,
02360         BLEProtocol::AddressType_t addressType = BLEProtocol::AddressType::RANDOM_STATIC
02361     ) {
02362        // FIXME: remove default parameter for addressType when ST shield is merged;
02363        // this has been added to mitigate the lack of dependency management in
02364        // testing jobs ....
02365 
02366         AdvertisementCallbackParams_t params;
02367         memcpy(params.peerAddr, peerAddr, ADDR_LEN);
02368         params.rssi = rssi;
02369         params.isScanResponse = isScanResponse;
02370         params.type = type;
02371         params.advertisingDataLen = advertisingDataLen;
02372         params.advertisingData = advertisingData;
02373         params.addressType = addressType;
02374         onAdvertisementReport.call(&params);
02375     }
02376 
02377     /**
02378      * Notify the occurrence of a timeout event to all registered timeout events
02379      * handler.
02380      *
02381      * @attention This function is meant to be called from the BLE stack specific
02382      * implementation when a disconnection event occurs.
02383      *
02384      * @param[in] source Source of the timout event.
02385      */
02386     void processTimeoutEvent(TimeoutSource_t source)
02387     {
02388         if (source == TIMEOUT_SRC_ADVERTISING) {
02389             /* Update gap state if the source is an advertising timeout */
02390             state.advertising = 0;
02391         }
02392         if (timeoutCallbackChain) {
02393             timeoutCallbackChain(source);
02394         }
02395     }
02396 
02397 protected:
02398     /**
02399      * Current advertising parameters.
02400      */
02401     GapAdvertisingParams _advParams;
02402 
02403     /**
02404      * Current advertising data.
02405      */
02406     GapAdvertisingData _advPayload;
02407 
02408     /**
02409      * Current scanning parameters.
02410      */
02411     GapScanningParams _scanningParams;
02412 
02413     /**
02414      * Current scan response.
02415      */
02416     GapAdvertisingData _scanResponse;
02417 
02418     /**
02419      * Number of open connections.
02420      */
02421     uint8_t connectionCount;
02422 
02423     /**
02424      * Current GAP state.
02425      */
02426     GapState_t state;
02427 
02428     /**
02429      * Active scanning flag.
02430      */
02431     bool scanningActive;
02432 
02433 protected:
02434     /**
02435      * Callchain containing all registered callback handlers for timeout
02436      * events.
02437      */
02438     TimeoutEventCallbackChain_t  timeoutCallbackChain;
02439 
02440     /**
02441      * The registered callback handler for radio notification events.
02442      */
02443     RadioNotificationEventCallback_t  radioNotificationCallback;
02444 
02445     /**
02446      * The registered callback handler for scanned advertisement packet
02447      * notifications.
02448      */
02449     AdvertisementReportCallback_t  onAdvertisementReport;
02450 
02451     /**
02452      * Callchain containing all registered callback handlers for connection
02453      * events.
02454      */
02455     ConnectionEventCallbackChain_t  connectionCallChain;
02456 
02457     /**
02458      * Callchain containing all registered callback handlers for disconnection
02459      * events.
02460      */
02461     DisconnectionEventCallbackChain_t  disconnectionCallChain;
02462 
02463 private:
02464     /**
02465      * Callchain containing all registered callback handlers for shutdown
02466      * events.
02467      */
02468     GapShutdownCallbackChain_t  shutdownCallChain;
02469 
02470 private:
02471     /* Disallow copy and assignment. */
02472     Gap(const Gap &);
02473     Gap& operator=(const Gap &);
02474 };
02475 
02476 /**
02477  * @}
02478  * @}
02479  */
02480 
02481 #endif // ifndef MBED_BLE_GAP_H__