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  *       BLEProtocol::RANDOM_STATIC,
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     /**
00614      * Type of the callback handling scanned advertisement packets.
00615      *
00616      * @see Gap::startScan().
00617      */
00618     typedef FunctionPointerWithContext<const AdvertisementCallbackParams_t *> 
00619         AdvertisementReportCallback_t;
00620 
00621     /**
00622      * Connection events.
00623      *
00624      * It contains all the information related to a newly established connection.
00625      *
00626      * Instances of this structure are passed to handlers that
00627      * Gap::onConnection() registers when a connection is established.
00628      */
00629     struct ConnectionCallbackParams_t {
00630         /**
00631          * Connection handle.
00632          */
00633         Handle_t handle;
00634 
00635         /**
00636          * Connection Role of the local device.
00637          */
00638         Role_t role;
00639 
00640         /**
00641          * Type of the address the peer uses.
00642          */
00643         BLEProtocol::AddressType_t peerAddrType;
00644 
00645         /**
00646          * Address of the peer.
00647          */
00648         BLEProtocol::AddressBytes_t peerAddr;
00649 
00650         /**
00651          * Address type of the local device.
00652          */
00653         BLEProtocol::AddressType_t  ownAddrType;
00654 
00655         /**
00656          * Address of the local device.
00657          */
00658         BLEProtocol::AddressBytes_t ownAddr;
00659 
00660         /**
00661          * Connection parameters.
00662          */
00663         const ConnectionParams_t   *connectionParams;
00664 
00665         /**
00666          * Construct an instance of ConnectionCallbackParams_t.
00667          *
00668          * @param[in] handleIn Value to assign to handle.
00669          * @param[in] roleIn Value to assign to role.
00670          * @param[in] peerAddrTypeIn Value to assign to peerAddrType.
00671          * @param[in] peerAddrIn Value to assign to peerAddr.
00672          * @param[in] ownAddrTypeIn Value to assign to ownAddrType.
00673          * @param[in] ownAddrIn Value to assign to ownAddr.
00674          * @param[in] connectionParamsIn Value to assign to connectionParams.
00675          *
00676          * @note Constructor is not meant to be called by user code.
00677          * The BLE API vendor code generates ConnectionCallbackParams_t.
00678          */
00679         ConnectionCallbackParams_t(
00680             Handle_t handleIn,
00681             Role_t roleIn,
00682             BLEProtocol::AddressType_t peerAddrTypeIn,
00683             const uint8_t *peerAddrIn,
00684             BLEProtocol::AddressType_t ownAddrTypeIn,
00685             const uint8_t *ownAddrIn,
00686             const ConnectionParams_t *connectionParamsIn
00687         ) : handle(handleIn),
00688             role(roleIn),
00689             peerAddrType(peerAddrTypeIn),
00690             peerAddr(),
00691             ownAddrType(ownAddrTypeIn),
00692             ownAddr(),
00693             connectionParams(connectionParamsIn)
00694         {
00695             memcpy(peerAddr, peerAddrIn, ADDR_LEN);
00696             memcpy(ownAddr, ownAddrIn, ADDR_LEN);
00697         }
00698     };
00699 
00700     /**
00701      * Disconnection event.
00702      *
00703      * Instances of this event are passed to callbacks registered with
00704      * Gap::onDisconnection() when a connection ends.
00705      *
00706      * @note Constructor is not meant to be called by user code.
00707      * The BLE API vendor code generates ConnectionCallbackParams_t.
00708      */
00709     struct DisconnectionCallbackParams_t {
00710         /**
00711          * ID of the connection that has ended.
00712          */
00713         Handle_t handle;
00714 
00715         /**
00716          * Reason of the disconnection.
00717          */
00718         DisconnectionReason_t reason;
00719 
00720         /**
00721          * Construct a DisconnectionCallbackParams_t.
00722          *
00723          * @param[in] handleIn Value assigned to handle.
00724          * @param[in] reasonIn Value assigned to reason.
00725          */
00726         DisconnectionCallbackParams_t(
00727             Handle_t handleIn,
00728             DisconnectionReason_t reasonIn
00729         ) : handle(handleIn),
00730             reason(reasonIn)
00731         {}
00732     };
00733 
00734     /**
00735      * Number of microseconds in 1.25 milliseconds.
00736      */
00737     static const uint16_t UNIT_1_25_MS  = 1250;
00738 
00739     /**
00740      * Convert milliseconds into 1.25ms units.
00741      *
00742      * This function may be used to convert ms time of connection intervals into
00743      * the format expected for connection parameters.
00744      *
00745      * @param[in] durationInMillis The duration in milliseconds.
00746      *
00747      * @return The duration in unit of 1.25ms.
00748      */
00749     static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis)
00750     {
00751         return (durationInMillis * 1000) / UNIT_1_25_MS;
00752     }
00753 
00754     /**
00755      * Timeout event handler.
00756      *
00757      * @see Gap::onTimeout().
00758      */
00759     typedef FunctionPointerWithContext<TimeoutSource_t>  TimeoutEventCallback_t;
00760 
00761     /**
00762      * Callchain of timeout event handlers.
00763      *
00764      * @see Gap::onTimeout().
00765      */
00766     typedef CallChainOfFunctionPointersWithContext<TimeoutSource_t> 
00767         TimeoutEventCallbackChain_t;
00768 
00769     /**
00770      * Connection event handler.
00771      *
00772      * @see Gap::onConnection().
00773      */
00774     typedef FunctionPointerWithContext<const ConnectionCallbackParams_t *> 
00775         ConnectionEventCallback_t;
00776 
00777     /**
00778      * Callchain of connection event handlers.
00779      *
00780      * @see Gap::onConnection().
00781      */
00782     typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> 
00783         ConnectionEventCallbackChain_t;
00784 
00785     /**
00786      * Disconnection event handler.
00787      *
00788      * @see Gap::onDisconnection().
00789      */
00790     typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> 
00791         DisconnectionEventCallback_t;
00792 
00793     /**
00794      * Callchain of disconnection event handlers.
00795      *
00796      * @see Gap::onDisconnection().
00797      */
00798     typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> 
00799         DisconnectionEventCallbackChain_t;
00800 
00801     /**
00802      * Radio notification event handler.
00803      *
00804      * @see Gap::onRadioNotification().
00805      */
00806     typedef FunctionPointerWithContext<bool>  RadioNotificationEventCallback_t;
00807 
00808     /**
00809      * Gap shutdown event handler.
00810      *
00811      * @see Gap::onShutdown().
00812      */
00813     typedef FunctionPointerWithContext<const Gap *>  GapShutdownCallback_t;
00814 
00815     /**
00816      * Callchain of gap shutdown event handler.
00817      *
00818      * @see Gap::onShutdown().
00819      */
00820     typedef CallChainOfFunctionPointersWithContext<const Gap *> 
00821         GapShutdownCallbackChain_t;
00822 
00823     /*
00824      * The following functions are meant to be overridden in the platform-specific subclass.
00825      */
00826 public:
00827     /**
00828      * Set the device MAC address and type.
00829      *
00830      * The address set is used in subsequent GAP operations: scanning,
00831      * advertising and connection initiation.
00832      *
00833      * @param[in] type Type of the address to set.
00834      * @param[in] address Value of the address to set. It is ordered in
00835      * little endian. This parameter is not considered if the address type
00836      * is RANDOM_PRIVATE_RESOLVABLE or RANDOM_PRIVATE_NON_RESOLVABLE. For those
00837      * types of address, the BLE API itself generates the address.
00838      *
00839      * @note Some implementation may refuse to set a new PUBLIC address.
00840      * @note Random static address set does not change.
00841      *
00842      * @return BLE_ERROR_NONE on success.
00843      */
00844     virtual ble_error_t setAddress(
00845         BLEProtocol::AddressType_t type,
00846         const BLEProtocol::AddressBytes_t address
00847     ) {
00848         /* avoid compiler warnings about unused variables */
00849         (void)type;
00850         (void)address;
00851 
00852         /* Requesting action from porter(s): override this API if this capability
00853            is supported. */
00854         return BLE_ERROR_NOT_IMPLEMENTED;
00855     }
00856 
00857     /**
00858      * Fetch the current address and its type.
00859      *
00860      * @param[out] typeP Type of the current address set.
00861      * @param[out] address Value of the current address.
00862      *
00863      * @return BLE_ERROR_NONE on success.
00864      */
00865     virtual ble_error_t getAddress(
00866         BLEProtocol::AddressType_t *typeP,
00867         BLEProtocol::AddressBytes_t address
00868     ) {
00869         /* Avoid compiler warnings about unused variables. */
00870         (void)typeP;
00871         (void)address;
00872 
00873         /* Requesting action from porter(s): override this API if this capability
00874            is supported. */
00875         return BLE_ERROR_NOT_IMPLEMENTED;
00876     }
00877 
00878     /**
00879      * Get the minimum advertising interval in milliseconds, which can be used
00880      * for connectable advertising types.
00881      *
00882      * @return Minimum Advertising interval in milliseconds for connectable
00883      * undirected and connectable directed advertising types.
00884      */
00885     virtual uint16_t getMinAdvertisingInterval(void) const
00886     {
00887         /* Requesting action from porter(s): override this API if this capability
00888            is supported. */
00889         return 0;
00890     }
00891 
00892     /**
00893      * Get the minimum advertising interval in milliseconds, which can be
00894      * used for nonconnectable advertising type.
00895      *
00896      * @return Minimum Advertising interval in milliseconds for scannable
00897      * undirected and nonconnectable undirected event types.
00898      */
00899     virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const
00900     {
00901         /* Requesting action from porter(s): override this API if this capability
00902            is supported. */
00903         return 0;
00904     }
00905 
00906     /**
00907      * Get the maximum advertising interval in milliseconds.
00908      *
00909      * @return Maximum Advertising interval in milliseconds.
00910      */
00911     virtual uint16_t getMaxAdvertisingInterval(void) const
00912     {
00913         /* Requesting action from porter(s): override this API if this capability
00914            is supported. */
00915         return 0xFFFF;
00916     }
00917 
00918     /**
00919      * Stop the ongoing advertising procedure.
00920      *
00921      * @note The current advertising parameters remain in effect.
00922      *
00923      * @retval BLE_ERROR_NONE if the advertising procedure has been successfully
00924      * stopped.
00925      */
00926     virtual ble_error_t stopAdvertising(void)
00927     {
00928         /* Requesting action from porter(s): override this API if this capability
00929            is supported. */
00930         return BLE_ERROR_NOT_IMPLEMENTED;
00931     }
00932 
00933     /**
00934      * Stop the ongoing scanning procedure.
00935      *
00936      * The current scanning parameters remain in effect.
00937      *
00938      * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
00939      */
00940     virtual ble_error_t stopScan()
00941     {
00942         /* Requesting action from porter(s): override this API if this capability
00943            is supported. */
00944         return BLE_ERROR_NOT_IMPLEMENTED;
00945     }
00946 
00947     /**
00948      * Initiate a connection to a peer.
00949      *
00950      * Once the connection is established, a ConnectionCallbackParams_t event is
00951      * emitted to handlers that have been registered with onConnection().
00952      *
00953      * @param[in] peerAddr MAC address of the peer. It must be in LSB format.
00954      * @param[in] peerAddrType Address type of the peer.
00955      * @param[in] connectionParams Connection parameters to use.
00956      * @param[in] scanParams Scan parameters used to find the peer.
00957      *
00958      * @return BLE_ERROR_NONE if connection establishment procedure is started
00959      * successfully. The connectionCallChain (if set) is invoked upon
00960      * a connection event.
00961      */
00962     virtual ble_error_t connect(
00963         const BLEProtocol::AddressBytes_t peerAddr,
00964         BLEProtocol::AddressType_t peerAddrType,
00965         const ConnectionParams_t *connectionParams,
00966         const GapScanningParams *scanParams
00967     ) {
00968         /* Avoid compiler warnings about unused variables. */
00969         (void)peerAddr;
00970         (void)peerAddrType;
00971         (void)connectionParams;
00972         (void)scanParams;
00973 
00974         /* Requesting action from porter(s): override this API if this capability
00975            is supported. */
00976         return BLE_ERROR_NOT_IMPLEMENTED;
00977     }
00978 
00979     /**
00980      * Initiate a connection to a peer.
00981      *
00982      * @see connect()
00983      *
00984      * @deprecated  This funtion overloads Gap::connect(
00985      *      const BLEProtocol::Address_t peerAddr,
00986      *      BLEProtocol::AddressType_t peerAddrType,
00987      *      const ConnectionParams_t *connectionParams,
00988      *      const GapScanningParams *scanParams
00989      * )
00990      * to maintain backward compatibility for changes from Gap::AddressType_t to
00991      * BLEProtocol::AddressType_t.
00992      */
00993     MBED_DEPRECATED("Gap::DeprecatedAddressType_t is deprecated, use BLEProtocol::AddressType_t instead")
00994     ble_error_t connect(
00995         const BLEProtocol::AddressBytes_t peerAddr,
00996         DeprecatedAddressType_t peerAddrType,
00997         const ConnectionParams_t *connectionParams,
00998         const GapScanningParams *scanParams
00999     ) {
01000         return connect(
01001             peerAddr,
01002             (BLEProtocol::AddressType_t)
01003             peerAddrType,
01004             connectionParams,
01005             scanParams
01006         );
01007     }
01008 
01009     /**
01010      * Initiate a disconnection procedure.
01011      *
01012      * Once the disconnection procedure has completed a
01013      * DisconnectionCallbackParams_t, the event is emitted to handlers that
01014      * have been registered with onDisconnection().
01015      *
01016      * @param[in] reason Reason of the disconnection transmitted to the peer.
01017      * @param[in] connectionHandle Handle of the connection to end.
01018      *
01019      * @return  BLE_ERROR_NONE if the disconnection procedure successfully
01020      * started.
01021      */
01022     virtual ble_error_t disconnect(
01023         Handle_t connectionHandle, DisconnectionReason_t reason
01024     ) {
01025         /* avoid compiler warnings about unused variables */
01026         (void)connectionHandle;
01027         (void)reason;
01028 
01029         /* Requesting action from porter(s): override this API if this capability
01030            is supported. */
01031         return BLE_ERROR_NOT_IMPLEMENTED;
01032     }
01033 
01034     /**
01035      * Initiate a disconnection procedure.
01036      *
01037      * @deprecated This version of disconnect() doesn't take a connection handle.
01038      * It works reliably only for stacks that are limited to a single connection.
01039      * Use Gap::disconnect(Handle_t connectionHandle, DisconnectionReason_t reason)
01040      * instead.
01041      *
01042      * @param[in] reason The reason for disconnection; to be sent back to the peer.
01043      *
01044      * @return BLE_ERROR_NONE if disconnection was successful.
01045      */
01046     MBED_DEPRECATED("Use disconnect(Handle_t, DisconnectionReason_t) instead.")
01047     virtual ble_error_t disconnect(DisconnectionReason_t reason) {
01048         /* Avoid compiler warnings about unused variables. */
01049         (void)reason;
01050 
01051         /* Requesting action from porter(s): override this API if this capability
01052            is supported. */
01053         return BLE_ERROR_NOT_IMPLEMENTED;
01054     }
01055 
01056     /**
01057      * Returned the preferred connection parameters exposed in the GATT Generic
01058      * Access Service.
01059      *
01060      * @param[out] params Structure where the parameters are stored.
01061      *
01062      * @return BLE_ERROR_NONE if the parameters were successfully filled into
01063      * @p params.
01064      */
01065     virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params)
01066     {
01067         /* Avoid compiler warnings about unused variables. */
01068         (void)params;
01069 
01070         /* Requesting action from porter(s): override this API if this capability
01071            is supported. */
01072         return BLE_ERROR_NOT_IMPLEMENTED;
01073     }
01074 
01075     /**
01076      * Set the value of the preferred connection parameters exposed in the GATT
01077      * Generic Access Service.
01078      *
01079      * A connected peer may read the characteristic exposing these parameters
01080      * and request an update of the connection parameters to accomodate the
01081      * local device.
01082      *
01083      * @param[in] params Value of the preferred connection parameters.
01084      *
01085      * @return BLE_ERROR_NONE if the preferred connection params were set
01086      * correctly.
01087      */
01088     virtual ble_error_t setPreferredConnectionParams(
01089         const ConnectionParams_t *params
01090     ) {
01091         /* Avoid compiler warnings about unused variables. */
01092         (void)params;
01093 
01094         /* Requesting action from porter(s): override this API if this capability
01095            is supported. */
01096         return BLE_ERROR_NOT_IMPLEMENTED;
01097     }
01098 
01099     /**
01100      * Update connection parameters of an existing connection.
01101      *
01102      * In the central role, this initiates a Link Layer connection parameter
01103      * update procedure. In the peripheral role, this sends the corresponding
01104      * L2CAP request and waits for the central to perform the procedure.
01105      *
01106      * @param[in] handle Connection Handle.
01107      * @param[in] params Pointer to desired connection parameters.
01108      *
01109      * @return BLE_ERROR_NONE if the connection parameters were updated correctly.
01110      */
01111     virtual ble_error_t updateConnectionParams(
01112         Handle_t handle,
01113         const ConnectionParams_t *params
01114     ) {
01115         /* avoid compiler warnings about unused variables */
01116         (void)handle;
01117         (void)params;
01118 
01119         /* Requesting action from porter(s): override this API if this capability
01120            is supported. */
01121         return BLE_ERROR_NOT_IMPLEMENTED;
01122     }
01123 
01124     /**
01125      * Set the value of the device name characteristic in the Generic Access
01126      * Service.
01127      *
01128      * @param[in] deviceName The new value for the device-name. This is a
01129      * UTF-8 encoded, <b>NULL-terminated</b> string.
01130      *
01131      * @return BLE_ERROR_NONE if the device name was set correctly.
01132      */
01133     virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
01134         /* Avoid compiler warnings about unused variables. */
01135         (void)deviceName;
01136 
01137         /* Requesting action from porter(s): override this API if this capability
01138            is supported. */
01139         return BLE_ERROR_NOT_IMPLEMENTED;
01140     }
01141 
01142     /**
01143      * Get the value of the device name characteristic in the Generic Access
01144      * Service.
01145      *
01146      * To obtain the length of the deviceName value, this function is
01147      * invoked with the @p deviceName parameter set to NULL.
01148      *
01149      * @param[out] deviceName Pointer to an empty buffer where the UTF-8
01150      * <b>non NULL-terminated</b> string is placed.
01151      *
01152      * @param[in,out] lengthP Length of the @p deviceName buffer. If the device
01153      * name is successfully copied, then the length of the device name
01154      * string (excluding the null terminator) replaces this value.
01155      *
01156      * @return BLE_ERROR_NONE if the device name was fetched correctly from the
01157      * underlying BLE stack.
01158      *
01159      * @note If the device name is longer than the size of the supplied buffer,
01160      * length returns the complete device name length and not the number of
01161      * bytes actually returned in deviceName. The application may use this
01162      * information to retry with a suitable buffer size.
01163      */
01164     virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP)
01165     {
01166         /* avoid compiler warnings about unused variables */
01167         (void)deviceName;
01168         (void)lengthP;
01169 
01170         /* Requesting action from porter(s): override this API if this capability
01171            is supported. */
01172         return BLE_ERROR_NOT_IMPLEMENTED;
01173     }
01174 
01175     /**
01176      * Set the value of the appearance characteristic in the GAP service.
01177      *
01178      * @param[in] appearance The new value for the device-appearance.
01179      *
01180      * @return BLE_ERROR_NONE if the new appearance was set correctly.
01181      */
01182     virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance)
01183     {
01184         /* Avoid compiler warnings about unused variables. */
01185         (void)appearance;
01186 
01187         /* Requesting action from porter(s): override this API if this capability
01188            is supported. */
01189         return BLE_ERROR_NOT_IMPLEMENTED;
01190     }
01191 
01192     /**
01193      * Get the value of the appearance characteristic in the GAP service.
01194      *
01195      * @param[out] appearanceP The current device-appearance value.
01196      *
01197      * @return BLE_ERROR_NONE if the device-appearance was fetched correctly
01198      * from the underlying BLE stack.
01199      */
01200     virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP)
01201     {
01202         /* Avoid compiler warnings about unused variables. */
01203         (void)appearanceP;
01204 
01205         /* Requesting action from porter(s): override this API if this capability
01206            is supported. */
01207         return BLE_ERROR_NOT_IMPLEMENTED;
01208     }
01209 
01210     /**
01211      * Set the radio's transmit power.
01212      *
01213      * @param[in] txPower Radio's transmit power in dBm.
01214      *
01215      * @return BLE_ERROR_NONE if the new radio's transmit power was set
01216      * correctly.
01217      */
01218     virtual ble_error_t setTxPower(int8_t txPower)
01219     {
01220         /* Avoid compiler warnings about unused variables. */
01221         (void)txPower;
01222 
01223         /* Requesting action from porter(s): override this API if this capability
01224            is supported. */
01225         return BLE_ERROR_NOT_IMPLEMENTED;
01226     }
01227 
01228     /**
01229      * Query the underlying stack for allowed Tx power values.
01230      *
01231      * @param[out] valueArrayPP Receive the immutable array of Tx values.
01232      * @param[out] countP Receive the array's size.
01233      */
01234     virtual void getPermittedTxPowerValues(
01235         const int8_t **valueArrayPP, size_t *countP
01236     ) {
01237         /* Avoid compiler warnings about unused variables. */
01238         (void)valueArrayPP;
01239         (void)countP;
01240 
01241         /* Requesting action from porter(s): override this API if this capability
01242            is supported. */
01243         *countP = 0;
01244     }
01245 
01246     /**
01247      * Get the maximum size of the whitelist.
01248      *
01249      * @return Maximum size of the whitelist.
01250      *
01251      * @note If using Mbed OS, you can configure the size of the whitelist by
01252      * setting the YOTTA_CFG_WHITELIST_MAX_SIZE macro in your yotta config file.
01253      */
01254     virtual uint8_t getMaxWhitelistSize(void) const
01255     {
01256         return 0;
01257     }
01258 
01259     /**
01260      * Get the Link Layer to use the internal whitelist when scanning,
01261      * advertising or initiating a connection depending on the filter policies.
01262      *
01263      * @param[in,out] whitelist Define the whitelist instance which is used
01264      * to store the whitelist requested. In input, the caller provisions memory.
01265      *
01266      * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
01267      * copied into the supplied reference.
01268      */
01269     virtual ble_error_t getWhitelist(Whitelist_t &whitelist) const
01270     {
01271         (void) whitelist;
01272         return BLE_ERROR_NOT_IMPLEMENTED;
01273     }
01274 
01275     /**
01276      * Set the value of the whitelist to be used during GAP procedures.
01277      *
01278      * @param[in] whitelist A reference to a whitelist containing the addresses
01279      * to be copied to the internal whitelist.
01280      *
01281      * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
01282      * populated with the addresses in the given whitelist.
01283      *
01284      * @note The whitelist must not contain addresses of type @ref
01285      * BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE. This
01286      * results in a @ref BLE_ERROR_INVALID_PARAM because the remote peer might
01287      * change its private address at any time, and it is not possible to resolve
01288      * it.
01289      *
01290      * @note If the input whitelist is larger than @ref getMaxWhitelistSize(),
01291      * then @ref BLE_ERROR_PARAM_OUT_OF_RANGE is returned.
01292      */
01293     virtual ble_error_t setWhitelist(const Whitelist_t &whitelist)
01294     {
01295         (void) whitelist;
01296         return BLE_ERROR_NOT_IMPLEMENTED;
01297     }
01298 
01299     /**
01300      * Set the advertising policy filter mode to be used during the next
01301      * advertising procedure.
01302      *
01303      * @param[in] mode New advertising policy filter mode.
01304      *
01305      * @return BLE_ERROR_NONE if the specified policy filter mode was set
01306      * successfully.
01307      */
01308     virtual ble_error_t setAdvertisingPolicyMode(AdvertisingPolicyMode_t mode)
01309     {
01310         (void) mode;
01311         return BLE_ERROR_NOT_IMPLEMENTED;
01312     }
01313 
01314     /**
01315      * Set the scan policy filter mode to be used during the next scan procedure.
01316      *
01317      * @param[in] mode New scan policy filter mode.
01318      *
01319      * @return BLE_ERROR_NONE if the specified policy filter mode was set
01320      * successfully.
01321      */
01322     virtual ble_error_t setScanningPolicyMode(ScanningPolicyMode_t mode)
01323     {
01324         (void) mode;
01325         return BLE_ERROR_NOT_IMPLEMENTED;
01326     }
01327 
01328     /**
01329      * Set the initiator policy filter mode to be used during the next connection
01330      * initiation.
01331      *
01332      * @param[in] mode New initiator policy filter mode.
01333      *
01334      * @return BLE_ERROR_NONE if the specified policy filter mode was set
01335      * successfully.
01336      */
01337     virtual ble_error_t setInitiatorPolicyMode(InitiatorPolicyMode_t mode)
01338     {
01339         (void) mode;
01340         return BLE_ERROR_NOT_IMPLEMENTED;
01341     }
01342 
01343     /**
01344      * Get the current advertising policy filter mode.
01345      *
01346      * @return The current advertising policy filter mode.
01347      */
01348     virtual AdvertisingPolicyMode_t getAdvertisingPolicyMode(void) const
01349     {
01350         return ADV_POLICY_IGNORE_WHITELIST;
01351     }
01352 
01353     /**
01354      * Get the current scan policy filter mode.
01355      *
01356      * @return The current scan policy filter mode.
01357      */
01358     virtual ScanningPolicyMode_t getScanningPolicyMode(void) const
01359     {
01360         return SCAN_POLICY_IGNORE_WHITELIST;
01361     }
01362 
01363     /**
01364      * Get the current initiator policy filter mode.
01365      *
01366      * @return The current scan policy filter mode.
01367      */
01368     virtual InitiatorPolicyMode_t getInitiatorPolicyMode(void) const
01369     {
01370         return INIT_POLICY_IGNORE_WHITELIST;
01371     }
01372 
01373 protected:
01374     /* Override the following in the underlying adaptation layer to provide the
01375       functionality of scanning. */
01376 
01377     /**
01378      * Start scanning procedure in the underlying BLE stack.
01379      *
01380      * @param[in] scanningParams Parameters of the scan procedure.
01381      *
01382      * @return BLE_ERROR_NONE if the scan procedure was successfully started.
01383      */
01384     virtual ble_error_t startRadioScan(const GapScanningParams &scanningParams)
01385     {
01386         (void)scanningParams;
01387         /* Requesting action from porter(s): override this API if this capability
01388            is supported. */
01389         return BLE_ERROR_NOT_IMPLEMENTED;
01390     }
01391 
01392     /*
01393      * APIs with nonvirtual implementations.
01394      */
01395 public:
01396     /**
01397      * Get the current advertising and connection states of the device.
01398      *
01399      * @return The current GAP state of the device.
01400      */
01401     GapState_t getState(void) const
01402     {
01403         return state;
01404     }
01405 
01406     /**
01407      * Set the advertising type to use during the advertising procedure.
01408      *
01409      * @param[in] advType New type of advertising to use.
01410      */
01411     void setAdvertisingType(GapAdvertisingParams::AdvertisingType_t advType)
01412     {
01413         _advParams.setAdvertisingType(advType);
01414     }
01415 
01416     /**
01417      * Set the advertising interval.
01418      *
01419      * @param[in] interval Advertising interval in units of milliseconds.
01420      * Advertising is disabled if interval is 0. If interval is smaller than
01421      * the minimum supported value, then the minimum supported value is used
01422      * instead. This minimum value can be discovered using
01423      * getMinAdvertisingInterval().
01424      *
01425      * This field must be set to 0 if connectionMode is equal
01426      * to ADV_CONNECTABLE_DIRECTED.
01427      *
01428      * @note  Decreasing this value allows central devices to detect a
01429      * peripheral faster, at the expense of the radio using more power
01430      * due to the higher data transmit rate.
01431      */
01432     void setAdvertisingInterval(uint16_t interval)
01433     {
01434         if (interval == 0) {
01435             stopAdvertising();
01436         } else if (interval < getMinAdvertisingInterval()) {
01437             interval = getMinAdvertisingInterval();
01438         }
01439         _advParams.setInterval(interval);
01440     }
01441 
01442     /**
01443      * Set the advertising duration.
01444      *
01445      * A timeout event is genenerated once the advertising period expired.
01446      *
01447      * @param[in] timeout Advertising timeout (in seconds) between 0x1 and 0x3FFF.
01448      * The special value 0 may be used to disable the advertising timeout.
01449      */
01450     void setAdvertisingTimeout(uint16_t timeout)
01451     {
01452         _advParams.setTimeout(timeout);
01453     }
01454 
01455     /**
01456      * Start the advertising procedure.
01457      *
01458      * @return BLE_ERROR_NONE if the device started advertising successfully.
01459      */
01460     ble_error_t startAdvertising(void)
01461     {
01462         ble_error_t rc;
01463         if ((rc = startAdvertising(_advParams)) == BLE_ERROR_NONE) {
01464             state.advertising = 1;
01465         }
01466         return rc;
01467     }
01468 
01469     /**
01470      * Reset the value of the advertising payload advertised.
01471      */
01472     void clearAdvertisingPayload(void)
01473     {
01474         _advPayload.clear();
01475         setAdvertisingData(_advPayload, _scanResponse);
01476     }
01477 
01478     /**
01479      * Set gap flags in the advertising payload.
01480      *
01481      * A call to this function is equivalent to:
01482      *
01483      * @code
01484      * Gap &gap;
01485      *
01486      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01487      * payload.addFlags(flags);
01488      * gap.setAdvertisingPayload(payload);
01489      * @endcode
01490      *
01491      * @param[in] flags The flags to be added.
01492      *
01493      * @return BLE_ERROR_NONE if the data was successfully added to the
01494      * advertising payload.
01495      */
01496     ble_error_t accumulateAdvertisingPayload(uint8_t flags)
01497     {
01498         GapAdvertisingData advPayloadCopy = _advPayload;
01499         ble_error_t rc;
01500         if ((rc = advPayloadCopy.addFlags(flags)) != BLE_ERROR_NONE) {
01501             return rc;
01502         }
01503 
01504         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01505         if (rc == BLE_ERROR_NONE) {
01506             _advPayload = advPayloadCopy;
01507         }
01508 
01509         return rc;
01510     }
01511 
01512     /**
01513      * Set the appearance field in the advertising payload.
01514      *
01515      * A call to this function is equivalent to:
01516      *
01517      * @code
01518      * Gap &gap;
01519      *
01520      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01521      * payload.addAppearance(app);
01522      * gap.setAdvertisingPayload(payload);
01523      * @endcode
01524      *
01525      * @param[in] app The appearance to advertise.
01526      *
01527      * @return BLE_ERROR_NONE if the data was successfully added to the
01528      * advertising payload.
01529      */
01530     ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app)
01531     {
01532         GapAdvertisingData advPayloadCopy = _advPayload;
01533         ble_error_t rc;
01534         if ((rc = advPayloadCopy.addAppearance(app)) != BLE_ERROR_NONE) {
01535             return rc;
01536         }
01537 
01538         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01539         if (rc == BLE_ERROR_NONE) {
01540             _advPayload = advPayloadCopy;
01541         }
01542 
01543         return rc;
01544     }
01545 
01546     /**
01547      * Set the Tx Power field in the advertising payload.
01548      *
01549      * A call to this function is equivalent to:
01550      *
01551      * @code
01552      * Gap &gap;
01553      *
01554      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01555      * payload.addTxPower(power);
01556      * gap.setAdvertisingPayload(payload);
01557      * @endcode
01558      *
01559      * @param[in] power Transmit power in dBm used by the controller to advertise.
01560      *
01561      * @return BLE_ERROR_NONE if the data was successfully added to the
01562      * advertising payload.
01563      */
01564     ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power)
01565     {
01566         GapAdvertisingData advPayloadCopy = _advPayload;
01567         ble_error_t rc;
01568         if ((rc = advPayloadCopy.addTxPower(power)) != BLE_ERROR_NONE) {
01569             return rc;
01570         }
01571 
01572         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01573         if (rc == BLE_ERROR_NONE) {
01574             _advPayload = advPayloadCopy;
01575         }
01576 
01577         return rc;
01578     }
01579 
01580     /**
01581      * Add a new field in the advertising payload.
01582      *
01583      * A call to this function is equivalent to:
01584      *
01585      * @code
01586      * Gap &gap;
01587      *
01588      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01589      * payload.addData(type, data, len);
01590      * gap.setAdvertisingPayload(payload);
01591      * @endcode
01592      *
01593      * @param[in] type Identity of the field being added.
01594      * @param[in] data Buffer containing the value of the field.
01595      * @param[in] len Length of the data buffer.
01596      *
01597      * @return BLE_ERROR_NONE if the advertisement payload was updated based on
01598      * matching AD type; otherwise, an appropriate error.
01599      *
01600      * @note When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS,
01601      * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS,
01602      * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS,
01603      * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the
01604      * supplied value is appended to the values previously added to the payload.
01605      */
01606     ble_error_t accumulateAdvertisingPayload(
01607         GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len
01608     ) {
01609         GapAdvertisingData advPayloadCopy = _advPayload;
01610         ble_error_t rc;
01611         if ((rc = advPayloadCopy.addData(type, data, len)) != BLE_ERROR_NONE) {
01612             return rc;
01613         }
01614 
01615         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01616         if (rc == BLE_ERROR_NONE) {
01617             _advPayload = advPayloadCopy;
01618         }
01619 
01620         return rc;
01621     }
01622 
01623     /**
01624      * Update a particular field in the advertising payload.
01625      *
01626      * A call to this function is equivalent to:
01627      *
01628      * @code
01629      * Gap &gap;
01630      *
01631      * GapAdvertisingData payload = gap.getAdvertisingPayload();
01632      * payload.updateData(type, data, len);
01633      * gap.setAdvertisingPayload(payload);
01634      * @endcode
01635      *
01636      *
01637      * @param[in] type Id of the field to update.
01638      * @param[in] data data buffer containing the new value of the field.
01639      * @param[in] len Length of the data buffer.
01640      *
01641      * @note If advertisements are enabled, then the update takes effect
01642      * immediately.
01643      *
01644      * @return BLE_ERROR_NONE if the advertisement payload was updated based on
01645      * matching AD type; otherwise, an appropriate error.
01646      */
01647     ble_error_t updateAdvertisingPayload(
01648         GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len
01649     ) {
01650         GapAdvertisingData advPayloadCopy = _advPayload;
01651         ble_error_t rc;
01652         if ((rc = advPayloadCopy.updateData(type, data, len)) != BLE_ERROR_NONE) {
01653             return rc;
01654         }
01655 
01656         rc = setAdvertisingData(advPayloadCopy, _scanResponse);
01657         if (rc == BLE_ERROR_NONE) {
01658             _advPayload = advPayloadCopy;
01659         }
01660 
01661         return rc;
01662     }
01663 
01664     /**
01665      * Set the value of the payload advertised.
01666      *
01667      * @param[in] payload A reference to a user constructed advertisement
01668      * payload to set.
01669      *
01670      * @return BLE_ERROR_NONE if the advertisement payload was successfully
01671      * set.
01672      */
01673     ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload)
01674     {
01675         ble_error_t rc = setAdvertisingData(payload, _scanResponse);
01676         if (rc == BLE_ERROR_NONE) {
01677             _advPayload = payload;
01678         }
01679 
01680         return rc;
01681     }
01682 
01683     /**
01684      * Get a reference to the current advertising payload.
01685      *
01686      * @return A reference to the current advertising payload.
01687      */
01688     const GapAdvertisingData &getAdvertisingPayload(void) const
01689     {
01690         return _advPayload;
01691     }
01692 
01693     /**
01694      * Add a new field in the advertising payload.
01695      *
01696      * @param[in] type AD type identifier.
01697      * @param[in] data buffer containing AD data.
01698      * @param[in] len Length of the data buffer.
01699      *
01700      * @return BLE_ERROR_NONE if the data was successfully added to the scan
01701      * response payload.
01702      */
01703     ble_error_t accumulateScanResponse(
01704         GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len
01705     ) {
01706         GapAdvertisingData scanResponseCopy = _scanResponse;
01707         ble_error_t rc;
01708         if ((rc = scanResponseCopy.addData(type, data, len)) != BLE_ERROR_NONE) {
01709             return rc;
01710         }
01711 
01712         rc = setAdvertisingData(_advPayload, scanResponseCopy);
01713         if (rc == BLE_ERROR_NONE) {
01714             _scanResponse = scanResponseCopy;
01715         }
01716 
01717         return rc;
01718     }
01719 
01720     /**
01721      * Reset the content of the scan response.
01722      *
01723      * @note This should be followed by a call to Gap::setAdvertisingPayload()
01724      * or Gap::startAdvertising() before the update takes effect.
01725      */
01726     void clearScanResponse(void) {
01727         _scanResponse.clear();
01728         setAdvertisingData(_advPayload, _scanResponse);
01729     }
01730 
01731     /**
01732      * Set the parameters used during a scan procedure.
01733      *
01734      * @param[in] interval in ms between the start of two consecutive scan windows.
01735      * That value is greater or equal to the scan window value. The
01736      * maximum allowed value is 10.24ms.
01737      *
01738      * @param[in] window Period in ms during which the scanner listens to
01739      * advertising channels. That value is in the range 2.5ms to 10.24s.
01740      *
01741      * @param[in] timeout Duration in seconds of the scan procedure if any. The
01742      * special value 0 disable specific duration of the scan procedure.
01743      *
01744      * @param[in] activeScanning If set to true, then the scanner sends scan
01745      * requests to a scannable or connectable advertiser. If set to false, then the
01746      * scanner does not send any request during the scan procedure.
01747      *
01748      * @return BLE_ERROR_NONE if the scan parameters were correctly set.
01749      *
01750      * @note The scanning window divided by the interval determines the duty
01751      * cycle for scanning. For example, if the interval is 100ms and the window
01752      * is 10ms, then the controller scans for 10 percent of the time.
01753      *
01754      * @note If the interval and the window are set to the same value, then the
01755      * device scans continuously during the scan procedure. The scanning
01756      * frequency changes at every interval.
01757      *
01758      * @note Once the scanning parameters have been configured, scanning can be
01759      * enabled by using startScan().
01760      *
01761      * @note The scan interval and window are recommendations to the BLE stack.
01762      */
01763     ble_error_t setScanParams(
01764         uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
01765         uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
01766         uint16_t timeout = 0,
01767         bool activeScanning = false
01768     ) {
01769         ble_error_t rc;
01770         if (((rc = _scanningParams.setInterval(interval)) == BLE_ERROR_NONE) &&
01771             ((rc = _scanningParams.setWindow(window))     == BLE_ERROR_NONE) &&
01772             ((rc = _scanningParams.setTimeout(timeout))   == BLE_ERROR_NONE)) {
01773             _scanningParams.setActiveScanning(activeScanning);
01774             return BLE_ERROR_NONE;
01775         }
01776 
01777         return rc;
01778     }
01779 
01780     /**
01781      * Set the interval parameter used during scanning procedures.
01782      *
01783      * @param[in] interval Interval in ms between the start of two consecutive
01784      * scan windows. That value is greater or equal to the scan window value.
01785      * The maximum allowed value is 10.24ms.
01786      *
01787      * @return BLE_ERROR_NONE if the scan interval was correctly set.
01788      */
01789     ble_error_t setScanInterval(uint16_t interval)
01790     {
01791         return _scanningParams.setInterval(interval);
01792     }
01793 
01794     /**
01795      * Set the window parameter used during scanning procedures.
01796      *
01797      * @param[in] window Period in ms during which the scanner listens to
01798      * advertising channels. That value is in the range 2.5ms to 10.24s.
01799      *
01800      * @return BLE_ERROR_NONE if the scan window was correctly set.
01801      *
01802      * @note If scanning is already active, the updated value of scanWindow
01803      * is propagated to the underlying BLE stack.
01804      */
01805     ble_error_t setScanWindow(uint16_t window)
01806     {
01807         ble_error_t rc;
01808         if ((rc = _scanningParams.setWindow(window)) != BLE_ERROR_NONE) {
01809             return rc;
01810         }
01811 
01812         /* If scanning is already active, propagate the new setting to the stack. */
01813         if (scanningActive) {
01814             return startRadioScan(_scanningParams);
01815         }
01816 
01817         return BLE_ERROR_NONE;
01818     }
01819 
01820     /**
01821      * Set the timeout parameter used during scanning procedures.
01822      *
01823      * @param[in] timeout Duration in seconds of the scan procedure if any. The
01824      * special value 0 disables specific duration of the scan procedure.
01825      *
01826      * @return BLE_ERROR_NONE if the scan timeout was correctly set.
01827      *
01828      * @note If scanning is already active, the updated value of scanTimeout
01829      * is propagated to the underlying BLE stack.
01830      */
01831     ble_error_t setScanTimeout(uint16_t timeout)
01832     {
01833         ble_error_t rc;
01834         if ((rc = _scanningParams.setTimeout(timeout)) != BLE_ERROR_NONE) {
01835             return rc;
01836         }
01837 
01838         /* If scanning is already active, propagate the new settings to the stack. */
01839         if (scanningActive) {
01840             return startRadioScan(_scanningParams);
01841         }
01842 
01843         return BLE_ERROR_NONE;
01844     }
01845 
01846     /**
01847      * Enable or disable active scanning.
01848      *
01849      * @param[in] activeScanning If set to true, then the scanner sends scan
01850      * requests to a scannable or connectable advertiser. If set to false then the
01851      * scanner does not send any request during the scan procedure.
01852      *
01853      * @return BLE_ERROR_NONE if active scanning was successfully set.
01854      *
01855      * @note If scanning is already in progress, then active scanning is
01856      * enabled for the underlying BLE stack.
01857      */
01858     ble_error_t setActiveScanning(bool activeScanning)
01859     {
01860         _scanningParams.setActiveScanning(activeScanning);
01861 
01862         /* If scanning is already active, propagate the new settings to the stack. */
01863         if (scanningActive) {
01864             return startRadioScan(_scanningParams);
01865         }
01866 
01867         return BLE_ERROR_NONE;
01868     }
01869 
01870     /**
01871      * Start the scanning procedure.
01872      *
01873      * Packets received during the scan procedure are forwarded to the
01874      * scan packet handler passed as argument to this function.
01875      *
01876      * @param[in] callback Advertisement packet event handler. Upon reception
01877      * of an advertising packet, the packet is forwarded to @p callback.
01878      *
01879      * @return BLE_ERROR_NONE if the device successfully started the scan
01880      *         procedure.
01881      *
01882      * @note The parameters used by the procedure are defined by setScanParams().
01883      */
01884     ble_error_t startScan(
01885         void (*callback)(const AdvertisementCallbackParams_t *params)
01886     ) {
01887         ble_error_t err = BLE_ERROR_NONE;
01888         if (callback) {
01889             if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
01890                 scanningActive = true;
01891                 onAdvertisementReport.attach(callback);
01892             }
01893         }
01894 
01895         return err;
01896     }
01897 
01898     /**
01899      * Start the scanning procedure.
01900      *
01901      * Packets received during the scan procedure are forwarded to the
01902      * scan packet handler passed as argument to this function.
01903      *
01904      * @param[in] object Instance used to invoke @p callbackMember.
01905      *
01906      * @param[in] callbackMember Advertisement packet event handler. Upon
01907      * reception of an advertising packet, the packet is forwarded to @p
01908      * callback invoked from @p object.
01909      *
01910      * @return BLE_ERROR_NONE if the device successfully started the scan
01911      * procedure.
01912      *
01913      * @note The parameters used by the procedure are defined by setScanParams().
01914      */
01915     template<typename T>
01916     ble_error_t startScan(
01917         T *object,
01918         void (T::*callbackMember)(const AdvertisementCallbackParams_t *params)
01919     ) {
01920         ble_error_t err = BLE_ERROR_NONE;
01921         if (object && callbackMember) {
01922             if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
01923                 scanningActive = true;
01924                 onAdvertisementReport.attach(object, callbackMember);
01925             }
01926         }
01927 
01928         return err;
01929     }
01930 
01931     /**
01932      * Enable radio-notification events.
01933      *
01934      * Radio Notification is a feature that notifies the application when the
01935      * radio is in use.
01936      *
01937      * The ACTIVE signal is sent before the radio event starts. The nACTIVE
01938      * signal is sent at the end of the radio event. The application programmer can
01939      * use these signals to synchronize application logic with radio
01940      * activity. For example, the ACTIVE signal can be used to shut off external
01941      * devices, to manage peak current drawn during periods when the radio is on
01942      * or to trigger sensor data collection for transmission in the Radio Event.
01943      *
01944      * @return BLE_ERROR_NONE on successful initialization, otherwise an error code.
01945      */
01946     virtual ble_error_t initRadioNotification(void)
01947     {
01948         /* Requesting action from porter(s): override this API if this capability
01949            is supported. */
01950         return BLE_ERROR_NOT_IMPLEMENTED;
01951     }
01952 
01953 private:
01954     /**
01955      * Set the advertising data and scan response in the vendor subsytem.
01956      *
01957      * @param[in] advData Advertising data to set.
01958      * @param[in] scanResponse Scan response to set.
01959      *
01960      * @return BLE_ERROR_NONE if the advertising data was set successfully.
01961      *
01962      * @note Must be implemented in vendor port.
01963      */
01964     virtual ble_error_t setAdvertisingData(
01965         const GapAdvertisingData &advData,
01966         const GapAdvertisingData &scanResponse
01967     ) = 0;
01968 
01969     /**
01970      * Start the advertising procedure.
01971      *
01972      * @param[in] params Advertising parameters to use.
01973      *
01974      * @return BLE_ERROR_NONE if the advertising procedure successfully
01975      * started.
01976      *
01977      * @note Must be implemented in vendor port.
01978      */
01979     virtual ble_error_t startAdvertising(const GapAdvertisingParams &params) = 0;
01980 
01981 public:
01982     /**
01983      * Get the current advertising parameters.
01984      *
01985      * @return A reference to the current advertising parameters.
01986      */
01987     GapAdvertisingParams &getAdvertisingParams(void)
01988     {
01989         return _advParams;
01990     }
01991 
01992     /**
01993      * Const alternative to Gap::getAdvertisingParams().
01994      *
01995      * @return A const reference to the current advertising parameters.
01996      */
01997     const GapAdvertisingParams &getAdvertisingParams(void) const
01998     {
01999         return _advParams;
02000     }
02001 
02002     /**
02003      * Set the advertising parameters.
02004      *
02005      * @param[in] newParams The new advertising parameters.
02006      */
02007     void setAdvertisingParams(const GapAdvertisingParams &newParams)
02008     {
02009         _advParams = newParams;
02010     }
02011 
02012     /* Event handlers. */
02013 public:
02014     /**
02015      * Register a callback handling timeout events.
02016      *
02017      * @param[in] callback Event handler being registered.
02018      *
02019      * @note A callback may be unregistered using onTimeout().detach(callback).
02020      *
02021      * @see TimeoutSource_t
02022      */
02023     void onTimeout(TimeoutEventCallback_t  callback)
02024     {
02025         timeoutCallbackChain.add(callback);
02026     }
02027 
02028     /**
02029      * Get the callchain of registered timeout event handlers.
02030      *
02031      * @note To register callbacks, use onTimeout().add(callback).
02032      *
02033      * @note To unregister callbacks, use onTimeout().detach(callback).
02034      *
02035      * @return A reference to the timeout event callbacks chain.
02036      */
02037     TimeoutEventCallbackChain_t & onTimeout()
02038     {
02039         return timeoutCallbackChain;
02040     }
02041 
02042     /**
02043      * Register a callback handling connection events.
02044      *
02045      * @param[in] callback Event handler being registered.
02046      *
02047      * @note A callback may be unregistered using onConnection().detach(callback).
02048      */
02049     void onConnection(ConnectionEventCallback_t  callback)
02050     {
02051         connectionCallChain.add(callback);
02052     }
02053 
02054     /**
02055      * Register a callback handling connection events.
02056      *
02057      * @param[in] tptr Instance used to invoke @p mptr.
02058      * @param[in] mptr Event handler being registered.
02059      *
02060      * @note A callback may be unregistered using onConnection().detach(callback).
02061      */
02062     template<typename T>
02063     void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*))
02064     {
02065         connectionCallChain.add(tptr, mptr);
02066     }
02067 
02068     /**
02069      * Get the callchain of registered connection event handlers.
02070      *
02071      * @note To register callbacks, use onConnection().add(callback).
02072      *
02073      * @note To unregister callbacks, use onConnection().detach(callback).
02074      *
02075      * @return A reference to the connection event callbacks chain.
02076      */
02077     ConnectionEventCallbackChain_t & onConnection()
02078     {
02079         return connectionCallChain;
02080     }
02081 
02082     /**
02083      * Register a callback handling disconnection events.
02084      *
02085      * @param[in] callback Event handler being registered.
02086      *
02087      * @note A callback may be unregistered using onDisconnection().detach(callback).
02088      */
02089     void onDisconnection(DisconnectionEventCallback_t  callback)
02090     {
02091         disconnectionCallChain.add(callback);
02092     }
02093 
02094     /**
02095      * Register a callback handling disconnection events.
02096      *
02097      * @param[in] tptr Instance used to invoke mptr.
02098      * @param[in] mptr Event handler being registered.
02099      *
02100      * @note A callback may be unregistered using onDisconnection().detach(callback).
02101      */
02102     template<typename T>
02103     void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*))
02104     {
02105         disconnectionCallChain.add(tptr, mptr);
02106     }
02107 
02108     /**
02109      * Get the callchain of registered disconnection event handlers.
02110      *
02111      * @note To register callbacks use onDisconnection().add(callback).
02112      *
02113      * @note To unregister callbacks use onDisconnection().detach(callback).
02114      *
02115      * @return A reference to the disconnection event callbacks chain.
02116      */
02117     DisconnectionEventCallbackChain_t & onDisconnection()
02118     {
02119         return disconnectionCallChain;
02120     }
02121 
02122     /**
02123      * Set the radio-notification events handler.
02124      *
02125      * Radio Notification is a feature that enables ACTIVE and INACTIVE
02126      * (nACTIVE) signals from the stack that notify the application when the
02127      * radio is in use.
02128      *
02129      * The ACTIVE signal is sent before the radio event starts. The nACTIVE
02130      * signal is sent at the end of the radio event. The application programmer can
02131      * use these signals to synchronize application logic with radio
02132      * activity. For example, the ACTIVE signal can be used to shut off external
02133      * devices, to manage peak current drawn during periods when the radio is on
02134      * or to trigger sensor data collection for transmission in the Radio Event.
02135      *
02136      * @param[in] callback Application handler to be invoked in response to a
02137      * radio ACTIVE/INACTIVE event.
02138      */
02139     void onRadioNotification(void (*callback)(bool param))
02140     {
02141         radioNotificationCallback.attach(callback);
02142     }
02143 
02144     /**
02145      * Set the radio-notification events handler.
02146      *
02147      * @param[in] tptr Instance to be used to invoke mptr.
02148      * @param[in] mptr Application handler to be invoked in response to a
02149      * radio ACTIVE/INACTIVE event.
02150      */
02151     template <typename T>
02152     void onRadioNotification(T *tptr, void (T::*mptr)(bool))
02153     {
02154         radioNotificationCallback.attach(tptr, mptr);
02155     }
02156 
02157     /**
02158      * Register a Gap shutdown event handler.
02159      *
02160      * The handler is called when the Gap instance is about to shut down.
02161      * It is usually issued after a call to BLE::shutdown().
02162      *
02163      * @param[in] callback Shutdown event handler to register.
02164      *
02165      * @note To unregister a shutdown event handler, use
02166      * onShutdown().detach(callback).
02167      */
02168     void onShutdown(const GapShutdownCallback_t & callback)
02169     {
02170         shutdownCallChain.add(callback);
02171     }
02172 
02173     /**
02174      * Register a Gap shutdown event handler.
02175      *
02176      * @param[in] objPtr Instance used to invoke @p memberPtr.
02177      * @param[in] memberPtr Shutdown event handler to register.
02178      */
02179     template <typename T>
02180     void onShutdown(T *objPtr, void (T::*memberPtr)(const Gap *))
02181     {
02182         shutdownCallChain.add(objPtr, memberPtr);
02183     }
02184 
02185     /**
02186      * Access the callchain of shutdown event handler.
02187      *
02188      * @note To register callbacks, use onShutdown().add(callback).
02189      *
02190      * @note To unregister callbacks, use onShutdown().detach(callback).
02191      *
02192      * @return A reference to the shutdown event callback chain.
02193      */
02194     GapShutdownCallbackChain_t & onShutdown()
02195     {
02196         return shutdownCallChain;
02197     }
02198 
02199 public:
02200     /**
02201      * Reset the Gap instance.
02202      *
02203      * Reset process starts by notifying all registered shutdown event handlers
02204      * that the Gap instance is about to be shut down. Then, it clears all Gap state
02205      * of the associated object and then cleans the state present in the vendor
02206      * implementation.
02207      *
02208      * This function is meant to be overridden in the platform-specific
02209      * subclass. Nevertheless, the subclass only resets its
02210      * state and not the data held in Gap members. This is achieved by a
02211      * call to Gap::reset() from the subclass' reset() implementation.
02212      *
02213      * @return BLE_ERROR_NONE on success.
02214      *
02215      * @note Currently, a call to reset() does not reset the advertising and
02216      * scan parameters to default values.
02217      */
02218     virtual ble_error_t reset(void)
02219     {
02220         /* Notify that the instance is about to shut down */
02221         shutdownCallChain.call(this);
02222         shutdownCallChain.clear();
02223 
02224         /* Clear Gap state */
02225         state.advertising = 0;
02226         state.connected   = 0;
02227         connectionCount   = 0;
02228 
02229         /* Clear scanning state */
02230         scanningActive = false;
02231 
02232         /* Clear advertising and scanning data */
02233         _advPayload.clear();
02234         _scanResponse.clear();
02235 
02236         /* Clear callbacks */
02237         timeoutCallbackChain.clear();
02238         connectionCallChain.clear();
02239         disconnectionCallChain.clear();
02240         radioNotificationCallback = NULL;
02241         onAdvertisementReport     = NULL;
02242 
02243         return BLE_ERROR_NONE;
02244     }
02245 
02246 protected:
02247     /**
02248      * Construct a Gap instance.
02249      */
02250     Gap() :
02251         _advParams(),
02252         _advPayload(),
02253         _scanningParams(),
02254         _scanResponse(),
02255         connectionCount(0),
02256         state(),
02257         scanningActive(false),
02258         timeoutCallbackChain(),
02259         radioNotificationCallback(),
02260         onAdvertisementReport(),
02261         connectionCallChain(),
02262         disconnectionCallChain() {
02263         _advPayload.clear();
02264         _scanResponse.clear();
02265     }
02266 
02267     /* Entry points for the underlying stack to report events back to the user. */
02268 public:
02269     /**
02270      * Notify all registered connection event handlers of a connection event.
02271      *
02272      * @attention This function is meant to be called from the BLE stack specific
02273      * implementation when a connection event occurs.
02274      *
02275      * @param[in] handle Handle of the new connection.
02276      * @param[in] role Role of this BLE device in the connection.
02277      * @param[in] peerAddrType Address type of the connected peer.
02278      * @param[in] peerAddr Address of the connected peer.
02279      * @param[in] ownAddrType Address type this device uses for this
02280      * connection.
02281      * @param[in] ownAddr Address this device uses for this connection.
02282      * @param[in] connectionParams Parameters of the connection.
02283      */
02284     void processConnectionEvent(
02285         Handle_t handle,
02286         Role_t role,
02287         BLEProtocol::AddressType_t peerAddrType,
02288         const BLEProtocol::AddressBytes_t peerAddr,
02289         BLEProtocol::AddressType_t ownAddrType,
02290         const BLEProtocol::AddressBytes_t ownAddr,
02291         const ConnectionParams_t *connectionParams
02292     ) {
02293         /* Update Gap state */
02294         state.advertising = 0;
02295         state.connected   = 1;
02296         ++connectionCount;
02297 
02298         ConnectionCallbackParams_t callbackParams(
02299             handle,
02300             role,
02301             peerAddrType,
02302             peerAddr,
02303             ownAddrType,
02304             ownAddr,
02305             connectionParams
02306         );
02307         connectionCallChain.call(&callbackParams);
02308     }
02309 
02310     /**
02311      * Notify all registered disconnection event handlers of a disconnection event.
02312      *
02313      * @attention This function is meant to be called from the BLE stack specific
02314      * implementation when a disconnection event occurs.
02315      *
02316      * @param[in] handle Handle of the terminated connection.
02317      * @param[in] reason Reason of the disconnection.
02318      */
02319     void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason)
02320     {
02321         /* Update Gap state */
02322         --connectionCount;
02323         if (!connectionCount) {
02324             state.connected = 0;
02325         }
02326 
02327         DisconnectionCallbackParams_t callbackParams(handle, reason);
02328         disconnectionCallChain.call(&callbackParams);
02329     }
02330 
02331     /**
02332      * Forward a received advertising packet to all registered event handlers
02333      * listening for scanned packet events.
02334      *
02335      * @attention This function is meant to be called from the BLE stack specific
02336      * implementation when a disconnection event occurs.
02337      *
02338      * @param[in] peerAddr Address of the peer that has emitted the packet.
02339      * @param[in] rssi Value of the RSSI measured for the received packet.
02340      * @param[in] isScanResponse If true, then the packet is a response to a scan
02341      * request.
02342      * @param[in] type Advertising type of the packet.
02343      * @param[in] advertisingDataLen Length of the advertisement data received.
02344      * @param[in] advertisingData Pointer to the advertisement packet's data.
02345      */
02346     void processAdvertisementReport(
02347         const BLEProtocol::AddressBytes_t peerAddr,
02348         int8_t rssi,
02349         bool isScanResponse,
02350         GapAdvertisingParams::AdvertisingType_t type,
02351         uint8_t advertisingDataLen,
02352         const uint8_t *advertisingData
02353     ) {
02354         AdvertisementCallbackParams_t params;
02355         memcpy(params.peerAddr, peerAddr, ADDR_LEN);
02356         params.rssi = rssi;
02357         params.isScanResponse = isScanResponse;
02358         params.type = type;
02359         params.advertisingDataLen = advertisingDataLen;
02360         params.advertisingData = advertisingData;
02361         onAdvertisementReport.call(&params);
02362     }
02363 
02364     /**
02365      * Notify the occurrence of a timeout event to all registered timeout events
02366      * handler.
02367      *
02368      * @attention This function is meant to be called from the BLE stack specific
02369      * implementation when a disconnection event occurs.
02370      *
02371      * @param[in] source Source of the timout event.
02372      */
02373     void processTimeoutEvent(TimeoutSource_t source)
02374     {
02375         if (source == TIMEOUT_SRC_ADVERTISING) {
02376             /* Update gap state if the source is an advertising timeout */
02377             state.advertising = 0;
02378         }
02379         if (timeoutCallbackChain) {
02380             timeoutCallbackChain(source);
02381         }
02382     }
02383 
02384 protected:
02385     /**
02386      * Current advertising parameters.
02387      */
02388     GapAdvertisingParams _advParams;
02389 
02390     /**
02391      * Current advertising data.
02392      */
02393     GapAdvertisingData _advPayload;
02394 
02395     /**
02396      * Current scanning parameters.
02397      */
02398     GapScanningParams _scanningParams;
02399 
02400     /**
02401      * Current scan response.
02402      */
02403     GapAdvertisingData _scanResponse;
02404 
02405     /**
02406      * Number of open connections.
02407      */
02408     uint8_t connectionCount;
02409 
02410     /**
02411      * Current GAP state.
02412      */
02413     GapState_t state;
02414 
02415     /**
02416      * Active scanning flag.
02417      */
02418     bool scanningActive;
02419 
02420 protected:
02421     /**
02422      * Callchain containing all registered callback handlers for timeout
02423      * events.
02424      */
02425     TimeoutEventCallbackChain_t  timeoutCallbackChain;
02426 
02427     /**
02428      * The registered callback handler for radio notification events.
02429      */
02430     RadioNotificationEventCallback_t  radioNotificationCallback;
02431 
02432     /**
02433      * The registered callback handler for scanned advertisement packet
02434      * notifications.
02435      */
02436     AdvertisementReportCallback_t  onAdvertisementReport;
02437 
02438     /**
02439      * Callchain containing all registered callback handlers for connection
02440      * events.
02441      */
02442     ConnectionEventCallbackChain_t  connectionCallChain;
02443 
02444     /**
02445      * Callchain containing all registered callback handlers for disconnection
02446      * events.
02447      */
02448     DisconnectionEventCallbackChain_t  disconnectionCallChain;
02449 
02450 private:
02451     /**
02452      * Callchain containing all registered callback handlers for shutdown
02453      * events.
02454      */
02455     GapShutdownCallbackChain_t  shutdownCallChain;
02456 
02457 private:
02458     /* Disallow copy and assignment. */
02459     Gap(const Gap &);
02460     Gap& operator=(const Gap &);
02461 };
02462 
02463 /**
02464  * @}
02465  * @}
02466  */
02467 
02468 #endif // ifndef MBED_BLE_GAP_H__