PalGap.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2017-2017 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 BLE_PAL_GAP_H_
00018 #define BLE_PAL_GAP_H_
00019 
00020 #include "platform/Callback.h"
00021 #include "ble/pal/GapTypes.h"
00022 #include "GapEvents.h"
00023 #include "blecommon.h"
00024 
00025 namespace ble {
00026 namespace pal {
00027 
00028 /**
00029  * Adaptation interface for the GAP layer.
00030  *
00031  * Define the primitive necessary to realize GAP operations. the API and event
00032  * follow closely the definition of the HCI commands and events used
00033  * by that layer.
00034  */
00035 struct Gap {
00036     /** @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 6, Part B - 4.6 */
00037     struct ControllerSupportedFeatures_t  : SafeEnum<ControllerSupportedFeatures_t, uint8_t> {
00038         enum type {
00039             LE_ENCRYPTION = 0,
00040             CONNECTION_PARAMETERS_REQUEST_PROCEDURE,
00041             EXTENDED_REJECT_INDICATION,
00042             SLAVE_INITIATED_FEATURES_EXCHANGE,
00043             LE_PING,
00044             LE_DATA_PACKET_LENGTH_EXTENSION,
00045             LL_PRIVACY,
00046             EXTENDED_SCANNER_FILTER_POLICIES,
00047             LE_2M_PHY,
00048             STABLE_MODULATION_INDEX_TRANSMITTER,
00049             STABLE_MODULATION_INDEX_RECEIVER,
00050             LE_CODED_PHY,
00051             LE_EXTENDED_ADVERTISING,
00052             LE_PERIODIC_ADVERTISING,
00053             CHANNEL_SELECTION_ALGORITHM_2,
00054             LE_POWER_CLASS
00055         };
00056 
00057         /**
00058          * Construct a new instance of ControllerSupportedFeatures_t.
00059          */
00060         ControllerSupportedFeatures_t(type value) : SafeEnum<ControllerSupportedFeatures_t , uint8_t>(value) { }
00061     };
00062 
00063     struct EventHandler {
00064         /**
00065          * @copydoc Gap::EventHandler::onReadPhy
00066          */
00067         virtual void on_read_phy(
00068             pal::hci_error_code_t status,
00069             connection_handle_t connectionHandle,
00070             ble::phy_t tx_phy,
00071             ble::phy_t rx_phy
00072         ) = 0;
00073 
00074         /**
00075          * @copydoc Gap::EventHandler::onPhyUpdateComplete
00076          */
00077         virtual void on_phy_update_complete(
00078             pal::hci_error_code_t status,
00079             connection_handle_t connection_handle,
00080             ble::phy_t tx_phy,
00081             ble::phy_t rx_phy
00082         ) = 0;
00083     };
00084 
00085     /**
00086      * Initialisation of the instance. An implementation can use this function
00087      * to initialise the subsystems needed to realize the operations of this
00088      * interface.
00089      *
00090      * This function has to be called before any other operations.
00091      *
00092      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00093      * appropriate error otherwise.
00094      */
00095     virtual ble_error_t initialize() = 0;
00096 
00097     /**
00098      * Termination of the instance. An implementation can use this function
00099      * to release the subsystems initialised to realise the operations of
00100      * this interface.
00101      *
00102      * After a call to this function, initialise should be called again to
00103      * allow use of the interface.
00104      *
00105      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00106      * appropriate error otherwise.
00107      */
00108     virtual ble_error_t terminate() = 0;
00109 
00110     /**
00111      * Return the public device address.
00112      *
00113      * @note The public device address is usually acquired at initialization and
00114      * stored in the instance.
00115      *
00116      * @return the public device address.
00117      */
00118     virtual address_t get_device_address() = 0;
00119 
00120     /**
00121      * Return the current random address.
00122      *
00123      * @note The random address is usually acquired at initialization and stored
00124      * in the instance.
00125      *
00126      * @return the random device address.
00127      */
00128     virtual address_t get_random_address() = 0;
00129 
00130     /**
00131      * Set the random address which will used be during scan, connection or
00132      * advertising process if the own address type selected is random.
00133      *
00134      * Changing the address during scan, connection or advertising process is
00135      * forbiden.
00136      *
00137      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.4 LE set random address command.
00138      *
00139      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00140      * appropriate error otherwise.
00141      */
00142     virtual ble_error_t set_random_address(const address_t& address) = 0;
00143 
00144     /**
00145      * Set the advertising parameters which will be used during the advertising
00146      * process.
00147      *
00148      * @param advertising_interval_min: Minimum advertising interval which can
00149      * be used during undirected and low duty cycle directed advertising. This
00150      * parameter shall be less than or equal to advertising_interval_max. This
00151      * parameter shall be in the range [0x20 : 0x4000] where each unit is equal
00152      * to 0.625ms.
00153      * This parameter is not used by directed high duty cycle advertising.
00154      *
00155      * @param advertising_interval_max: Maximum advertising interval which can
00156      * be used during undirected and low duty cycle directed advertising. This
00157      * parameter shall be more than or equal to advertising_interval_min. This
00158      * parameter shall be in the range [0x20 : 0x4000] where each unit is equal
00159      * to 0.625ms.
00160      * This parameter is not used by directed high duty cycle advertising.
00161      *
00162      * @param advertising_type Packet type that is used during the
00163      * advertising process. Direct advertising require valid peer addresses
00164      * parameters and ignore the filter policy set.
00165      * If the High duty cycle advertising is used then the advertising parameter
00166      * intervals are ignored.
00167      *
00168      * @param own_address_type Own address type used during advertising.
00169      * If own address type is equal to RESOLVABLE_PRIVATE_ADDRESS_PUBLIC_FALLBACK
00170      * or RESOLVABLE_PRIVATE_ADDRESS_RANDOM_FALLBACK then the peer address
00171      * parameters (type and address) will be used to find the local IRK.
00172      *
00173      * @param peer_address_type Address type of the peer.
00174      * This parameter shall be valid if directed advertising is used (
00175      * ADV_DIRECT_IND or ADV_DIRECT_IND_LOW_DUTY_CYCLE). This parameter should
00176      * be valid if the own address type is equal to 0x02 or 0x03.
00177      * In other cases, this parameter is ignored.
00178      *
00179      * @param peer_address Public device address, Random device addres, Public
00180      * identity address or Random static identity address of the device targeted
00181      * by the advertising.
00182      * This parameter shall be valid if directed advertising is used (
00183      * ADV_DIRECT_IND or ADV_DIRECT_IND_LOW_DUTY_CYCLE). This parameter should
00184      * be valid if the own address type is equal to 0x02 or 0x03.
00185      * In other cases, this parameter is ignored.
00186      *
00187      * @param advertising_channel_map Map of the channel used to send
00188      * advertising data.
00189      *
00190      * @param advertising_filter_policy Filter policy applied during the
00191      * advertising process. The subsystem should use the whitelist to apply the
00192      * policy. This parameter is ignored if the advertising type is directed (
00193      * ADV_DIRECT_IND or ADV_DIRECT_IND_LOW_DUTY_CYCLE).
00194      *
00195      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00196      * appropriate error otherwise.
00197      *
00198      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.5 LE set advertising parameters
00199      * command.
00200      */
00201     virtual ble_error_t set_advertising_parameters(
00202         uint16_t advertising_interval_min,
00203         uint16_t advertising_interval_max,
00204         advertising_type_t advertising_type,
00205         own_address_type_t own_address_type,
00206         advertising_peer_address_type_t peer_address_type,
00207         const address_t& peer_address,
00208         advertising_channel_map_t advertising_channel_map,
00209         advertising_filter_policy_t advertising_filter_policy
00210     ) = 0;
00211 
00212     /**
00213      * Set the data sends in advertising packet. If the advertising is
00214      * currently enabled, the data shall be used when a new advertising packet
00215      * is issued.
00216      *
00217      * @param advertising_data_length Number of significant bytes in the
00218      * advertising data.
00219      *
00220      * @param advertising_data The data sends in advertising packets. Non
00221      * significant bytes shall be equal to 0.
00222      *
00223      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00224      * appropriate error otherwise.
00225      *
00226      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.5 LE set advertising data
00227      * command.
00228      */
00229     virtual ble_error_t set_advertising_data(
00230         uint8_t advertising_data_length,
00231         const advertising_data_t& advertising_data
00232     ) = 0;
00233 
00234     /**
00235      * Set the data sends in scan response packets. If the advertising is
00236      * currently enabled, the data shall be used when a new scan response is
00237      * issued.
00238      *
00239      * @param scan_response_data_length Number of significant bytes in the
00240      * scan response data.
00241      *
00242      * @param scan_response_data The data sends in scan response packets. Non
00243      * significant bytes shall be equal to 0.
00244      *
00245      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00246      * appropriate error otherwise.
00247      *
00248      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.8 LE set scan response data
00249      * command.
00250      */
00251     virtual ble_error_t set_scan_response_data(
00252         uint8_t scan_response_data_length,
00253         const advertising_data_t& scan_response_data
00254     ) = 0;
00255 
00256     /**
00257      * Start or stop advertising.
00258      *
00259      * The process use advertising and scan response data set with
00260      * set_advertising_data and set_scan_response_data while the parameters used
00261      * are the one set by set_advertising_parameters.
00262      *
00263      * The advertising shall continue until:
00264      *     - The advertising is manually disabled (advertising_enable(false)).
00265      *     - A connection is created.
00266      *     - Time out in case of high duty cycle directed advertising.
00267      *
00268      * If the random address has not been set and the advertising parameter
00269      * own_address_type is set to 0x01 then the procedure shall fail.
00270      *
00271      * If the random address has not been set and the advertising parameter
00272      * own_address_type is set to RESOLVABLE_PRIVATE_ADDRESS_RANDOM_FALLBACK and
00273      * the peer address is not in the resolving list then the procedure shall
00274      * fail.
00275      *
00276      * @param enable If true start the advertising process, if the process was
00277      * already runing and own_address_type is equal to 0x02 or 0x03, the
00278      * subsystem can change the random address.
00279      * If false and the advertising is running then the process should be
00280      * stoped.
00281      *
00282      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00283      * appropriate error otherwise.
00284      *
00285      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.9 LE set advertising enable
00286      * command.
00287      *
00288      * @note If the advertising type is ADV_DIRECT_IND and the connection is not
00289      * created during the time allowed to the procedure then a
00290      * ConnectionComplete event shall be emmited with its error code set to
00291      * ADVERTISING_TIMEOUT.
00292      *
00293      * @note Successfull connection shall emit a ConnectionComplete event. It
00294      * also means advertising is disabled.
00295      */
00296     virtual ble_error_t advertising_enable(bool enable) = 0;
00297 
00298     /**
00299      * Set the parameter of the scan process.
00300      *
00301      * This command shall not be effective when the scanning process is running.
00302      *
00303      * @param active_scanning If true the subsystem does active scanning and
00304      * the bluetooth subsystem shall send scanning PDUs. It shall also listen
00305      * to scan responses. If false no scanning PDUs are sent during the scan
00306      * process.
00307      *
00308      * @param scan_interval The time interval between two subsequent LE scans in
00309      * unit of 0.625ms. This parameter shall be in the range [0x0004 : 0x4000].
00310      *
00311      * @param scan_window Duration of the LE scan. It shall be less than or
00312      * equal to scan_interval value. This parameter shall be in the range
00313      * [0x0004 : 0x4000] and is in unit of 0.625ms.
00314      *
00315      * @param own_address_type Own address type used in scan request packets.
00316      *
00317      * @param filter_policy Filter policy applied when scanning.
00318      *
00319      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00320      * appropriate error otherwise.
00321      *
00322      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.10 LE set scan parameters
00323      * command.
00324      */
00325     virtual ble_error_t set_scan_parameters(
00326         bool active_scanning,
00327         uint16_t scan_interval,
00328         uint16_t scan_window,
00329         own_address_type_t own_address_type,
00330         scanning_filter_policy_t filter_policy
00331     ) = 0;
00332 
00333     /**
00334      * Start/stop scanning process.
00335      *
00336      * Parameters of the scanning process shall be set before the scan launch
00337      * by using the function set_scan_parameters.
00338      *
00339      * @parameter enable Start the scanning process if true and stop it if
00340      * false. If the scan process is already started, enabling it again will
00341      * only update the duplicate filtering; based on the new parameter.
00342      *
00343      * @parameter filter_duplicates Enable duplicate filtering if true,
00344      * otherwise disable it.
00345      *
00346      * @attention advertising data or scan response data is not considered
00347      * significant when determining duplicate advertising reports.
00348      *
00349      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00350      * appropriate error otherwise.
00351      *
00352      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.11 LE set scan enable command.
00353      */
00354     virtual ble_error_t scan_enable(
00355         bool enable,
00356         bool filter_duplicates
00357     ) = 0;
00358 
00359     /**
00360      * Create a new le connection to a connectable advertiser.
00361      *
00362      * @param scan_interval Hint to the le subsystem indicating how
00363      * frequently it should scan for the peer address. It represent the time
00364      * interval between two subsequent scan for the peer. It shall be in the
00365      * range [0x0004 : 0x4000] and the time is in unit of 0.625ms.
00366      *
00367      * @param scan_window Hint to the le subsystem indicating for how long it
00368      * should scan during a scan interval. The value shall be smaller or equal
00369      * to scan_interval. If it is equal to scan_interval then scanning should
00370      * run continuously. It shall be in the range [0x0004 : 0x4000] and the time
00371      * is in unit of 0.625ms.
00372      *
00373      * @param initiator_policy Used to determine if the whitelist is used to
00374      * determine the address to connect to. If the whitelist is not used, the
00375      * connection shall be made against an advertiser matching the peer_address
00376      * and the peer_address_type parameters. Otherwise those parameters are
00377      * ignored.
00378      *
00379      * @param peer_address_type Type of address used by the advertiser. Not used
00380      * if initiator_policy use the whitelist.
00381      *
00382      * @param Address used by the advertiser in its advertising packets. Not
00383      * used if initiator_policy use the whitelist.
00384      *
00385      * @param own_address_type Type of address used in the connection request
00386      * packet.
00387      *
00388      * @param connection_interval_min Minimum interval between two connection
00389      * events allowed for the connection. It shall be less than or equal to
00390      * connection_interval_max. This value shall be in range [0x0006 : 0x0C80]
00391      * and is in unit of 1.25ms.
00392      *
00393      * @param connection_interval_max Maximum interval between two connection
00394      * events allowed for the connection. It shall be greater than or equal to
00395      * connection_interval_min. This value shall be in range [0x0006 : 0x0C80]
00396      * and is in unit of 1.25ms.
00397      *
00398      * @param connection_latency Number of connection events the slave can drop
00399      * if it has nothing to communicate to the master. This value shall be in
00400      * the range [0x0000 : 0x01F3].
00401      *
00402      * @param supervision_timeout Link supervision timeout for the connection.
00403      * It shall be larger than:
00404      *        (1 + connection_latency) * connection_interval_max * 2
00405      * Note: connection_interval_max is in ms in this formulae.
00406      * Everytime the master or the slave receive a valid packet from the peer,
00407      * the supervision timer is reset. If the supervision timer reaches
00408      * supervision_timeout then the connection is considered lost and a
00409      * disconnect event shall be emmited.
00410      * This value shall be in the range [0x000A : 0x0C80] and is in unit of 10
00411      * ms.
00412      *
00413      * @param minimum_connection_event_length Informative parameter of the
00414      * minimum length a connection event. It shall be less than or equal to
00415      * maximum_connection_event_length. It shall be in the range
00416      * [0x0000 : 0xFFFF]. It should also be less than the expected connection
00417      * interval. The unit is 0.625ms.
00418      *
00419      * @param maximum_connection_event_length Informative parameter of the
00420      * maximum length a connection event. It shall be more than or equal to
00421      * minimum_connection_event_length. It shall be in the range
00422      * [0x0000 : 0xFFFF]. It should also be less than the expected connection
00423      * interval. The unit is 0.625ms.
00424      *
00425      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00426      * appropriate error otherwise.
00427      *
00428      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.12 LE create connection command.
00429      */
00430     virtual ble_error_t create_connection(
00431         uint16_t scan_interval,
00432         uint16_t scan_window,
00433         initiator_policy_t initiator_policy,
00434         connection_peer_address_type_t peer_address_type,
00435         const address_t& peer_address,
00436         own_address_type_t own_address_type,
00437         uint16_t connection_interval_min,
00438         uint16_t connection_interval_max,
00439         uint16_t connection_latency,
00440         uint16_t supervision_timeout,
00441         uint16_t minimum_connection_event_length,
00442         uint16_t maximum_connection_event_length
00443     ) = 0;
00444 
00445     /**
00446      * Cancel the ongoing connection creation process.
00447      *
00448      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00449      * appropriate error otherwise.
00450      *
00451      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.13 LE create connection cancel
00452      * command.
00453      */
00454     virtual ble_error_t cancel_connection_creation() = 0;
00455 
00456     /**
00457      * Return the number of total whitelist entries that can be stored in the
00458      * le subsystem.
00459      *
00460      * @note The value returned can change over time.
00461      *
00462      * @return The number of entries that can be stored in the LE subsystem. It
00463      * range from 0x01 to 0xFF.
00464      *
00465      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.14 LE read white list size
00466      * command.
00467      */
00468     virtual uint8_t read_white_list_capacity() = 0;
00469 
00470     /**
00471      * Clear the whitelist stored in the LE subsystem.
00472      *
00473      * @attention This command shall not be issued if the whitelist is being
00474      * used by the advertising, scanning or connection creation procedure.
00475      *
00476      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00477      * appropriate error otherwise.
00478      *
00479      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.15 LE clear white list command.
00480      */
00481     virtual ble_error_t clear_whitelist() = 0;
00482 
00483     /**
00484      * Add a device to the LE subsystem Whitelist.
00485      *
00486      * @param address_type address_type Type of the address to add in the
00487      * whitelist.
00488      *
00489      * @param address Address of the device.
00490      *
00491      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00492      * appropriate error otherwise.
00493      *
00494      * @attention This command shall not be issued if the whitelist is being
00495      * used by the advertising, scanning or connection creation procedure.
00496      *
00497      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.16 LE add device to white list
00498      * command.
00499      */
00500     virtual ble_error_t add_device_to_whitelist(
00501         whitelist_address_type_t address_type,
00502         address_t address
00503     ) = 0;
00504 
00505     /**
00506      * Remove a device from the LE subsystem Whitelist.
00507      *
00508      * @param address_type address_type Type of the address of the device to
00509      * remove from the whitelist.
00510      *
00511      * @param address Address of the device to remove from the whitelist
00512      *
00513      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00514      * appropriate error otherwise.
00515      *
00516      * @attention This command shall not be issued if the whitelist is being
00517      * used by the advertising, scanning or connection creation procedure.
00518      *
00519      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.17 LE remove device from white
00520      * list command.
00521      */
00522     virtual ble_error_t remove_device_from_whitelist(
00523         whitelist_address_type_t address_type,
00524         address_t address
00525     ) = 0;
00526 
00527     /**
00528      * Start a connection update procedure.
00529      *
00530      * This procedure change the parameter used for a connection it can be
00531      * master or slave initiated.
00532      *
00533      * The peer will received a connection parameters request and will either
00534      * accept or reject the new parameters for the connection.
00535      *
00536      * Once the peer response has been received, the procedure ends and a
00537      * Connection update complete event is emmited.
00538      *
00539      * @param connection Handle of the connection.
00540      *
00541      * @param connection_interval_min Minimum interval between two connection
00542      * events allowed for the connection. It shall be less than or equal to
00543      * connection_interval_max. This value shall be in range [0x0006 : 0x0C80]
00544      * and is in unit of 1.25ms.
00545      *
00546      * @param connection_interval_max Maximum interval between two connection
00547      * events allowed for the connection. It shall be greater than or equal to
00548      * connection_interval_min. This value shall be in range [0x0006 : 0x0C80]
00549      * and is in unit of 1.25ms.
00550      *
00551      * @param connection_latency Number of connection events the slave can drop
00552      * if it has nothing to communicate to the master. This value shall be in
00553      * the range [0x0000 : 0x01F3].
00554      *
00555      * @param supervision_timeout Link supervision timeout for the connection.
00556      * It shall be larger than:
00557      *        (1 + connection_latency) * connection_interval_max * 2
00558      * Note: connection_interval_max is in ms in this formulae.
00559      * Everytime the master or the slave receive a valid packet from the peer,
00560      * the supervision timer is reset. If the supervision timer reaches
00561      * supervision_timeout then the connection is considered lost and a
00562      * disconnect event shall be emmited.
00563      * This value shall be in the range [0x000A : 0x0C80] and is in unit of 10
00564      * ms.
00565      *
00566      * @param minimum_connection_event_length Informative parameter of the
00567      * minimum length a connection event. It shall be less than or equal to
00568      * maximum_connection_event_length. It shall be in the range
00569      * [0x0000 : 0xFFFF]. It should also be less than the expected connection
00570      * interval. The unit is 0.625ms.
00571      *
00572      * @param maximum_connection_event_length Informative parameter of the
00573      * maximum length a connection event. It shall be more than or equal to
00574      * minimum_connection_event_length. It shall be in the range
00575      * [0x0000 : 0xFFFF]. It should also be less than the expected connection
00576      * interval. The unit is 0.625ms.
00577      *
00578      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00579      * appropriate error otherwise.
00580      *
00581      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.18 LE Connection update command.
00582      *
00583      */
00584     virtual ble_error_t connection_parameters_update(
00585         connection_handle_t connection,
00586         uint16_t connection_interval_min,
00587         uint16_t connection_interval_max,
00588         uint16_t connection_latency,
00589         uint16_t supervision_timeout,
00590         uint16_t minimum_connection_event_length,
00591         uint16_t maximum_connection_event_length
00592     ) = 0;
00593 
00594     /**
00595      * Accept connection parameter request.
00596      *
00597      * This command sends a positive response to a connection parameter request
00598      * from a peer.
00599      *
00600      * @param connection Handle of the connection.
00601      *
00602      * @param connection_interval_min Minimum interval between two connection
00603      * events allowed for the connection. It shall be less than or equal to
00604      * connection_interval_max. This value shall be in range [0x0006 : 0x0C80]
00605      * and is in unit of 1.25ms.
00606      *
00607      * @param connection_interval_max Maximum interval between two connection
00608      * events allowed for the connection. It shall be greater than or equal to
00609      * connection_interval_min. This value shall be in range [0x0006 : 0x0C80]
00610      * and is in unit of 1.25ms.
00611      *
00612      * @param connection_latency Number of connection events the slave can drop
00613      * if it has nothing to communicate to the master. This value shall be in
00614      * the range [0x0000 : 0x01F3].
00615      *
00616      * @param supervision_timeout Link supervision timeout for the connection.
00617      * It shall be larger than:
00618      *        (1 + connection_latency) * connection_interval_max * 2
00619      * Note: connection_interval_max is in ms in this formulae.
00620      * Everytime the master or the slave receive a valid packet from the peer,
00621      * the supervision timer is reset. If the supervision timer reaches
00622      * supervision_timeout then the connection is considered lost and a
00623      * disconnect event shall be emmited.
00624      * This value shall be in the range [0x000A : 0x0C80] and is in unit of 10
00625      * ms.
00626      *
00627      * @param minimum_connection_event_length Informative parameter of the
00628      * minimum length a connection event. It shall be less than or equal to
00629      * maximum_connection_event_length. It shall be in the range
00630      * [0x0000 : 0xFFFF]. It should also be less than the expected connection
00631      * interval. The unit is 0.625ms.
00632      *
00633      * @param maximum_connection_event_length Informative parameter of the
00634      * maximum length a connection event. It shall be more than or equal to
00635      * minimum_connection_event_length. It shall be in the range
00636      * [0x0000 : 0xFFFF]. It should also be less than the expected connection
00637      * interval. The unit is 0.625ms.
00638      *
00639      * @note Usually parameters of this function match the connection parameters
00640      * received in the connection parameter request event.
00641      *
00642      * @attention: Once the new connection parameters are in used a Connection
00643      * Update Complete event shall be emmited.
00644      *
00645      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00646      * appropriate error otherwise.
00647      *
00648      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.31 LE remote connection parameter
00649      * request reply command.
00650      */
00651     virtual ble_error_t accept_connection_parameter_request(
00652         connection_handle_t connection_handle,
00653         uint16_t interval_min,
00654         uint16_t interval_max,
00655         uint16_t latency,
00656         uint16_t supervision_timeout,
00657         uint16_t minimum_connection_event_length,
00658         uint16_t maximum_connection_event_length
00659     ) = 0;
00660 
00661     /**
00662      * Reject a connection parameter update request.
00663      *
00664      * @param connection_handle handle to the peer which has issued the
00665      * connection parameter request.
00666      *
00667      * @param rejection_reason Indicate to the peer why the proposed connection
00668      * parameters were rejected.
00669      *
00670      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00671      * appropriate error otherwise.
00672      *
00673      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.32 LE Remote Connection Parameter
00674      * Request Negative Reply Command.
00675      */
00676     virtual ble_error_t reject_connection_parameter_request(
00677         connection_handle_t connection_handle,
00678         hci_error_code_t rejection_reason
00679     ) = 0;
00680 
00681     /**
00682      * Start a disconnection procedure.
00683      *
00684      * Once the procedure is complete it should emit a disconnection complete
00685      * event.
00686      *
00687      * @param connection Handle of the connection to terminate.
00688      *
00689      * @param disconnection_reason Indicates the reason for ending the
00690      * connection.
00691      *
00692      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00693      * appropriate error otherwise.
00694      *
00695      * @note: See Bluetooth 5 Vol 2 PartE: 7.1.6 disconenct command.
00696      */
00697     virtual ble_error_t disconnect(
00698         connection_handle_t connection,
00699         disconnection_reason_t disconnection_reason
00700     ) = 0;
00701 
00702     /** Check if privacy feature is supported by implementation
00703      *  
00704      * @return true if privacy is supported, false otherwise.
00705      * 
00706      * @note: See Bluetooth 5 Vol 3 Part C: 10.7 Privacy feature.
00707      */ 
00708     virtual bool is_privacy_supported() = 0;
00709 
00710     /** Enable or disable private addresses resolution
00711      *
00712      * @param enable whether to enable private addresses resolution
00713      *  
00714      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00715      * appropriate error otherwise.
00716      * 
00717      * @note: See Bluetooth 5 Vol 2 PartE: 7.8.44 LE Set Address Resolution Enable command.
00718      */
00719     virtual ble_error_t set_address_resolution(
00720         bool enable
00721     ) = 0;
00722 
00723     /**
00724      * Checked support for a feature in the link controller.
00725      *
00726      * @param feature feature to be checked.
00727      * @return TRUE if feature is supported.
00728      */
00729     virtual bool is_feature_supported(
00730         ControllerSupportedFeatures_t feature
00731     ) = 0;
00732      
00733     /**
00734     * @see Gap::readPhy
00735     */
00736     virtual ble_error_t read_phy (connection_handle_t connection) = 0;
00737 
00738     /**
00739     * @see Gap::setPreferredPhys
00740     */
00741     virtual ble_error_t set_preferred_phys (
00742        const phy_set_t& tx_phys,
00743        const phy_set_t& rx_phys
00744     ) = 0;
00745 
00746     /**
00747     * @see Gap::setPhy
00748     */
00749     virtual ble_error_t set_phy (
00750        connection_handle_t connection,
00751        const phy_set_t& tx_phys,
00752        const phy_set_t& rx_phys,
00753        coded_symbol_per_bit_t coded_symbol
00754     ) = 0;
00755 
00756     /**
00757      * Register a callback which will handle Gap events.
00758      *
00759      * @param cb The callback object which will handle Gap events from the
00760      * LE subsystem.
00761      * It accept a single parameter in input: The event received.
00762      */
00763     void when_gap_event_received(mbed::Callback<void(const GapEvent&)> cb)
00764     {
00765         _gap_event_cb = cb;
00766     }
00767 
00768 public:
00769     /**
00770     * Sets the event handler that us called by the PAL porters to notify the stack of events
00771     * which will in turn be passed onto the user application when appropriate.
00772     *
00773     * @param[in] event_handler the new event handler interface implementation. Memory
00774     * owned by caller who is responsible for updating this pointer if interface changes.
00775     */
00776     void set_event_handler(EventHandler *event_handler) {
00777         _pal_event_handler = event_handler;
00778     }
00779 
00780     EventHandler* get_event_handler() {
00781         return _pal_event_handler;
00782     }
00783 
00784 protected:
00785     EventHandler *_pal_event_handler;
00786 
00787 protected:
00788     Gap() : _pal_event_handler(NULL) { }
00789 
00790     virtual ~Gap() { }
00791 
00792     /**
00793      * Implementation shall call this function whenever the LE subsystem
00794      * generate a Gap event.
00795      *
00796      * @param gap_event The event to emit to higher layer.
00797      */
00798     void emit_gap_event(const GapEvent& gap_event)
00799     {
00800         if (_gap_event_cb) {
00801             _gap_event_cb(gap_event);
00802         }
00803     }
00804 
00805 public:
00806     /**
00807      * Create an ALL_PHYS parameter used in LE Set PHY Command
00808      * and LE Set Default PHY Command.
00809      * @see BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E - 7.8.49
00810      */
00811     static uint8_t create_all_phys_value(
00812         const phy_set_t& tx_phys,
00813         const phy_set_t& rx_phys
00814     ) {
00815         /* if phy set is empty set corresponding all_phys bit to 1 */
00816         uint8_t all_phys = 0;
00817         if (tx_phys.value() == 0) {
00818             all_phys |= 0x01;
00819         }
00820         if (rx_phys.value() == 0) {
00821             all_phys |= 0x02;
00822         }
00823         return all_phys;
00824     }
00825 
00826 private:
00827     /**
00828      * Callback called when an event is emitted by the LE subsystem.
00829      */
00830     mbed::Callback<void(const GapEvent&)> _gap_event_cb;
00831 
00832 private:
00833     // Disallow copy construction and copy assignment.
00834     Gap(const Gap&);
00835     Gap& operator=(const Gap&);
00836 };
00837 
00838 } // namespace pal
00839 } // namespace ble
00840 
00841 #endif /* BLE_PAL_GAP_H_ */