GapTypes.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_TYPES_H_
00018 #define BLE_PAL_GAP_TYPES_H_
00019 
00020 #include <algorithm>
00021 #include "ble/BLETypes.h"
00022 #include "ble/SafeEnum.h"
00023 
00024 namespace ble {
00025 namespace pal {
00026 
00027 /**
00028  * Type of advertising the LE subsystem can use when it advertise.
00029  */
00030 struct advertising_type_t : SafeEnum<advertising_type_t, uint8_t> {
00031     enum type  {
00032         /**
00033          * Connectable and scannable undirected advertising .
00034          */
00035         ADV_IND = 0x00,
00036 
00037         /**
00038          * Connectable high duty cycle directed advertising
00039          */
00040         ADV_DIRECT_IND = 0x01,
00041 
00042         /**
00043          * Scannable undirected advertising
00044          */
00045         ADV_SCAN_IND = 0x02,
00046 
00047         /**
00048          * Non connectable undirected advertising
00049          */
00050         ADV_NONCONN_IND = 0x03,
00051 
00052         /**
00053          * Connectable low duty cycle directed advertising
00054          */
00055         ADV_DIRECT_IND_LOW_DUTY_CYCLE = 0x04
00056     };
00057 
00058     /**
00059      * Construct a new advertising_type_t value.
00060      */
00061     advertising_type_t(type  value) :
00062         SafeEnum<advertising_type_t, uint8_t>(value) { }
00063 };
00064 
00065 
00066 /**
00067  * Type used to model the own address used during the following GAP operations:
00068  * advertising, scanning and initiating
00069  */
00070 struct own_address_type_t : SafeEnum<own_address_type_t, uint8_t> {
00071     enum type  {
00072         /**
00073          * Use the public device address
00074          */
00075         PUBLIC_ADDRESS = 0x00,
00076 
00077         /**
00078          * Use the random device address
00079          */
00080         RANDOM_ADDRESS = 0x01,
00081 
00082         /**
00083          * Generated resolvable private address based on the local IRK from the
00084          * resolving list. Use the public address if no entry match in the resolving
00085          * list.
00086          */
00087         RESOLVABLE_PRIVATE_ADDRESS_PUBLIC_FALLBACK = 0x02,
00088 
00089         /**
00090          * Generated resolvable private address based on the local IRK from the
00091          * resolving list. Use the random address if no entry match in the resolving
00092          * list.
00093          */
00094         RESOLVABLE_PRIVATE_ADDRESS_RANDOM_FALLBACK = 0x03,
00095     };
00096 
00097     /**
00098      * Construct a new instance of own_address_type_t.
00099      */
00100     own_address_type_t(type  value) :
00101         SafeEnum<own_address_type_t, uint8_t>(value) { }
00102 };
00103 
00104 
00105 /**
00106  * Type modeling the peer address type during direct advertising.
00107  */
00108 struct advertising_peer_address_type_t :
00109     SafeEnum<advertising_peer_address_type_t, uint8_t> {
00110     enum type  {
00111         /**
00112          * Public device address or identity address.
00113          */
00114         PUBLIC_ADDRESS = 0x00,
00115 
00116         /**
00117          * Random device address or random (static) identity address.
00118          */
00119         RANDOM_ADDRESS = 0x01
00120     };
00121 
00122     /**
00123      * Construct a new instance of advertising_peer_address_type_t.
00124      */
00125     advertising_peer_address_type_t(type  value) :
00126         SafeEnum<advertising_peer_address_type_t, uint8_t>(value) { }
00127 };
00128 
00129 
00130 /**
00131  * Peer address type used during connection initiating.
00132  */
00133 struct connection_peer_address_type_t :
00134     SafeEnum<connection_peer_address_type_t, uint8_t> {
00135     enum type  {
00136         /**
00137          * Public device address
00138          */
00139         PUBLIC_ADDRESS = 0x00,
00140 
00141         /**
00142          * Random device address
00143          */
00144         RANDOM_ADDRESS = 0x01,
00145 
00146         /**
00147          * Public identity address.
00148          * @note remove once privacy mode is supported.
00149          */
00150         PUBLIC_IDENTITY_ADDRESS = 0x02,
00151 
00152         /**
00153          * Random (static) identity address.
00154          * @note remove once privacy mode is supported.
00155          */
00156         RANDOM_IDENTITY_ADDRESS = 0x03
00157     };
00158 
00159     /**
00160      * Construct a new connection_peer_address_type_t instance.
00161      */
00162     connection_peer_address_type_t(type  value) :
00163         SafeEnum<connection_peer_address_type_t, uint8_t>(value) { }
00164 };
00165 
00166 
00167 /**
00168  * Address type used in whitelist operations
00169  */
00170 struct whitelist_address_type_t : SafeEnum<whitelist_address_type_t, uint8_t> {
00171     enum type {
00172         PUBLIC_DEVICE_ADDRESS = 0x00,
00173         RANDOM_DEVICE_ADDRESS = 0x01,
00174         /* TODO: to be added with bluetooth 5 support:
00175         ANONYMOUS_ADVERTISEMENT_DEVICE_ADRESS
00176         */
00177     };
00178 
00179     /**
00180      * Construct a new whitelist_address_type_t instance.
00181      */
00182     whitelist_address_type_t(type value) :
00183         SafeEnum<whitelist_address_type_t, uint8_t>(value) { }
00184 };
00185 
00186 
00187 /**
00188  * Channel map which can be used during advertising.
00189  */
00190 struct advertising_channel_map_t : SafeEnum<advertising_channel_map_t, uint8_t> {
00191     enum type {
00192         ADVERTISING_CHANNEL_37 = (1 << 0),
00193         ADVERTISING_CHANNEL_38 = (1 << 1),
00194         ADVERTISING_CHANNEL_37_AND_38 =
00195             ADVERTISING_CHANNEL_37 | ADVERTISING_CHANNEL_38,
00196         ADVERTISING_CHANNEL_39 = (1 << 2),
00197         ADVERTISING_CHANNEL_37_AND_39 =
00198             ADVERTISING_CHANNEL_37 | ADVERTISING_CHANNEL_39,
00199         ADVERTISING_CHANNEL_38_AND_39 =
00200             ADVERTISING_CHANNEL_38 | ADVERTISING_CHANNEL_39,
00201         ALL_ADVERTISING_CHANNELS =
00202             ADVERTISING_CHANNEL_37 | ADVERTISING_CHANNEL_38 | ADVERTISING_CHANNEL_39
00203     };
00204 
00205     /**
00206      * Construct a new advertising_channel_map_t instance.
00207      */
00208     advertising_channel_map_t(type value) :
00209         SafeEnum<advertising_channel_map_t, uint8_t>(value) { }
00210 };
00211 
00212 
00213 /**
00214  * HCI Error codes.
00215  */
00216 struct hci_error_code_t : SafeEnum<hci_error_code_t, uint8_t> {
00217     enum type {
00218         SUCCESS = 0x00,
00219         UNKNOWN_HCI_COMMAND = 0x01,
00220         UNKNOWN_CONNECTION_IDENTIFIER = 0x02,
00221         HARDWARE_FAILLURE = 0x03,
00222         PAGE_TIMEOUT = 0x04,
00223         AUTHENTICATION_FAILLURE = 0x05,
00224         PIN_OR_KEY_MISSING = 0x06,
00225         MEMORY_CAPACITY_EXCEEDED = 0x07,
00226         CONNECTION_TIMEOUT = 0x08,
00227         CONNECTION_LIMIT_EXCEEDED = 0x09,
00228         SYNCHRONOUS_CONNECTION_LIMIT_TO_A_DEVICE_EXCEEDED = 0x0A,
00229         CONNECTION_ALREADY_EXIST = 0x0B,
00230         COMMAND_DISALLOWED = 0x0C,
00231         CONNECTION_REJECTED_DUE_TO_LIMITED_RESOURCES = 0x0D,
00232         CONNECTION_REJECTED_DUE_TO_SECURITY_REASONS = 0x0E,
00233         CONNECTION_REJECTED_DUE_TO_UNACCEPTABLE_BD_ADDR = 0x0F,
00234         CONNECTION_ACCEPT_TIMEOUT_EXCEEDED = 0x10,
00235         UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE = 0x11,
00236         INVALID_HCI_COMMAND_PARAMETERS = 0x12,
00237         REMOTE_USER_TERMINATED_CONNECTION = 0x13,
00238         REMOTE_DEVICE_TERMINATED_CONNECTION_DUE_TO_LOW_RESOURCES = 0x14,
00239         REMOTE_DEVICE_TERMINATED_CONNECTION_DUE_TO_POWER_OFF = 0x15,
00240         CONNECTION_TERMINATED_BY_LOCAL_HOST = 0x16,
00241         REPEATED_ATTEMPTS = 0x17,
00242         PAIRING_NOT_ALLOWED = 0x18,
00243         UNKNOWN_LMP_PDU = 0x19,
00244         UNSUPPORTED_REMOTE_FEATURE = 0x1A,
00245         UNSUPPORTED_LMP_FEATURE = 0x1A,
00246         SCO_OFFSET_REJECTED = 0x1B,
00247         SCO_INTERVAL_REJECTED = 0x1C,
00248         SCO_AIR_MODE_REJECTED = 0x1D,
00249         INVALID_LMP_PARAMETERS = 0x1E,
00250         INVALID_LL_PARAMETERS = 0x1E,
00251         UNSPECIFIED_ERROR = 0x1F,
00252         UNSUPPORTED_LMP_PARAMETER_VALUE = 0x20,
00253         UNSUPPORTED_LL_PARAMETER_VALUE = 0x20,
00254         ROLE_CHANGE_NOT_ALLOWED = 0x21,
00255         LMP_RESPONSE_TIMEOUT = 0x22,
00256         LL_RESPONSE_TIMEOUT = 0x22,
00257         LMP_ERROR_TRANSACTION_COLLISION = 0x23,
00258         LL_PROCEDURE_COLLISION = 0x23,
00259         LMP_PDU_NOT_ALLOWED = 0x24,
00260         ENCRYPTION_MODE_NOT_ACCEPTABLE = 0x25,
00261         LINK_KEY_CANNOT_BE_CHANGED = 0x26,
00262         REQUESTED_QOS_NOT_SUPPORTED = 0x27,
00263         INSTANT_PASSED = 0x28,
00264         PAIRING_WITH_UNIT_KEY_NOT_SUPPORTED = 0x29,
00265         DIFFERENT_TRANSACTION_COLLISION = 0x2A,
00266         RESERVED_FOR_FUTURE_USE = 0x2B,
00267         QOS_UNACCEPTABLE_PARAMETER = 0x2C,
00268         QOS_REJECTED = 0x2D,
00269         CHANNEL_CLASSIFICATION_NOT_SUPPORTED = 0x2E,
00270         INSUFFICIENT_SECURITY = 0x2F,
00271         PARAMETER_OUT_OF_MANDATORY_RANGE = 0x30,
00272         //RESERVED_FOR_FUTURE_USE = 0x31,
00273         ROLE_SWITCH_PENDING = 0x32,
00274         //RESERVED_FOR_FUTURE_USE = 0x33,
00275         RESERVED_SLOT_VIOLATION = 0x34,
00276         ROLE_SWITCH_FAILED = 0x35,
00277         EXTENDED_INQUIRY_RESPONSE_TOO_LARGE = 0x36,
00278         SECURE_SIMPLE_PAIRING_NOT_SUPPORTED_BY_HOST = 0x37,
00279         HOST_BUSY_PAIRING = 0x38,
00280         CONNECTION_REJECTED_DUE_TO_NO_SUITABLE_CHANNEL_FOUND = 0x39,
00281         CONTROLLER_BUSY = 0x3A,
00282         UNACCEPTABLE_CONNECTION_PARAMETERS = 0x3B,
00283         ADVERTISING_TIMEOUT = 0x3C,
00284         CONNECTION_TERMINATED_DUE_TO_MIC_FAILURE = 0x3D,
00285         CONNECTION_FAILED_TO_BE_ESTABLISHED = 0x3E,
00286         MAC_CONNECTION_FAILED = 0x3F,
00287         COARSE_CLOCK_ADJUSTMENT_REJECTED_BUT_WILL_TRY_TO_ADJUST_USING_CLOCK_DRAGGING = 0x40,
00288         TYPE0_SUBMAP_NOT_DEFINED = 0x41,
00289         UNKNOWN_ADVERTISING_IDENTIFIER = 0x42,
00290         LIMIT_REACHED = 0x43,
00291         OPERATION_CANCELLED_BY_HOST = 0x44
00292     };
00293 
00294     /**
00295      * Construct a new hci_error_code_t instance.
00296      */
00297     hci_error_code_t(type value) :
00298         SafeEnum<hci_error_code_t, uint8_t>(value) { }
00299 };
00300 
00301 
00302 /**
00303  * Reasons which can be used to end a connection.
00304  */
00305 struct disconnection_reason_t : SafeEnum<disconnection_reason_t, uint8_t> {
00306     enum type {
00307         AUTHENTICATION_FAILLURE = 0x05,
00308         REMOTE_USER_TERMINATED_CONNECTION = 0x13,
00309         REMOTE_DEVICE_TERMINATED_CONNECTION_DUE_TO_LOW_RESOURCES = 0x14,
00310         REMOTE_DEVICE_TERMINATED_CONNECTION_DUE_TO_POWER_OFF = 0x15,
00311         UNSUPPORTED_REMOTE_FEATURE = 0x1A,
00312         PAIRING_WITH_UNIT_KEY_NOT_SUPPORTED = 0x29,
00313         UNACCEPTABLE_CONNECTION_PARAMETERS = 0x3B
00314     };
00315 
00316     /**
00317      * Construct a new disconnection_reason_t instance.
00318      */
00319     disconnection_reason_t(type value) :
00320         SafeEnum<disconnection_reason_t, uint8_t>(value) { }
00321 };
00322 
00323 
00324 /**
00325  * Filter policy which can be used during advertising.
00326  */
00327 struct advertising_filter_policy_t :
00328     SafeEnum<advertising_filter_policy_t, uint8_t> {
00329     enum type  {
00330         /**
00331          * Process connection and scan requests from all devices. The whitelist is
00332          * not used.
00333          */
00334         NO_FILTER = 0x00,
00335 
00336         /**
00337          * Process connection requests from all devices but filter out scan requests
00338          * of devices which are not in the whitelist.
00339          */
00340         FILTER_SCAN_REQUESTS = 0x01,
00341 
00342         /**
00343          * Process scan requests from all devices but filter out connection requests
00344          * of devices which are not in the whitelist.
00345          */
00346         FILTER_CONNECTION_REQUEST = 0x02,
00347 
00348         /**
00349          * Filter out scan or connection requests of devices which are not in the
00350          * whitelist.
00351          */
00352         FILTER_SCAN_AND_CONNECTION_REQUESTS = 0x03
00353     };
00354 
00355     /**
00356      * Construct a new instance of advertising_filter_policy_t.
00357      */
00358     advertising_filter_policy_t(type  value) :
00359         SafeEnum<advertising_filter_policy_t, uint8_t>(value) { }
00360 };
00361 
00362 
00363 /**
00364  * Filter policy which can be used during a scan.
00365  */
00366 struct scanning_filter_policy_t : SafeEnum<scanning_filter_policy_t, uint8_t> {
00367     enum type  {
00368         /**
00369         * Accept all advertising packets except directed advertising packet not
00370         * addressed to this device.
00371         */
00372         NO_FILTER = 0x00,
00373 
00374         /**
00375         * Accept only advertising packets from devices in the whitelist except
00376         * directed advertising packet not addressed to this device.
00377         */
00378         FILTER_ADVERTISING = 0x01
00379 
00380         // EXTENDED ADVERTISING FILTER POLICY (accept private resolvable direct advertising)
00381     };
00382 
00383     /**
00384      * Construct a new instance of scanning_filter_policy_t.
00385      */
00386     scanning_filter_policy_t(type  value) :
00387         SafeEnum<scanning_filter_policy_t, uint8_t>(value) { }
00388 
00389 };
00390 
00391 
00392 /**
00393  * Filter policy which can be used during connection initiation.
00394  */
00395 struct initiator_policy_t : SafeEnum<initiator_policy_t, uint8_t> {
00396     enum type  {
00397         /**
00398         * The whitelist is not used to determine which advertiser to connect to.
00399         */
00400         NO_FILTER,
00401 
00402         /**
00403         * Whitelist is used to determine which advertiser to connect to.
00404         */
00405         USE_WHITE_LIST
00406     };
00407 
00408     initiator_policy_t(type value) :
00409         SafeEnum<initiator_policy_t, uint8_t>(value) { }
00410 };
00411 
00412 
00413 /**
00414  * MAC address data type.
00415  */
00416 struct address_t {
00417     /**
00418      * Create an invalid mac address, equal to FF:FF:FF:FF:FF:FF
00419      */
00420     address_t() {
00421         memset(value, 0xFF, sizeof(value));
00422     }
00423 
00424     /**
00425      * Initialize a mac address from an array of bytes.
00426      *
00427      * @param input_value value of the MAC address.
00428      */
00429     address_t(const uint8_t (&input_value)[6]) {
00430         memcpy(value, input_value, sizeof(value));
00431     }
00432 
00433     /**
00434      * Initialize a mac address from a pointer to a buffer.
00435      *
00436      * @param input_value Buffer containing the mac address. It shall be at
00437      * least 6 long.
00438      *
00439      * @param tag Tag used to select this constructor. The value does not matter.
00440      */
00441     address_t(const uint8_t* input_value, bool tag) {
00442         memcpy(value, input_value, sizeof(value));
00443     }
00444 
00445     /**
00446      * Equal operator between two addresses.
00447      */
00448     friend bool operator==(const address_t& lhs, const address_t& rhs) {
00449         return memcmp(lhs.value, rhs.value, sizeof(lhs.value)) == 0;
00450     }
00451 
00452     /**
00453      * Non equal operator between two addresses.
00454      */
00455     friend bool operator!=(const address_t& lhs, const address_t& rhs) {
00456         return !(lhs == rhs);
00457     }
00458 
00459     /**
00460      * Subscript operator to access mac address content
00461      */
00462     uint8_t operator[](uint8_t i) const {
00463         return value[i];
00464     }
00465 
00466     /**
00467      * Return the pointer to the buffer holding mac address.
00468      */
00469     const uint8_t* data() const {
00470         return value;
00471     }
00472 
00473     /**
00474      * Size in byte of a mac address.
00475      */
00476     static uint8_t size() {
00477         return sizeof(value);
00478     }
00479 
00480 private:
00481     uint8_t value[6];
00482 };
00483 
00484 
00485 /**
00486  * Hold advertising data.
00487  */
00488 struct advertising_data_t {
00489     /**
00490      * Construct advertising data from an array.
00491      *
00492      * @param input_value Reference to the array containing the advertising data
00493      */
00494     advertising_data_t(const uint8_t (&input_value)[31]) {
00495         memcpy(value, input_value, sizeof(value));
00496     }
00497 
00498     /**
00499      * Construct advertising data from a pointer to a buffer.
00500      *
00501      * @param input_value Pointer to the buffer containing the advertising data.
00502      *
00503      * @param len Length of the buffer.
00504      */
00505     advertising_data_t(const uint8_t* input_value, size_t len) {
00506         const size_t actual_len = std::min(len, sizeof(value));
00507         memcpy(value, input_value, actual_len);
00508         memset(value + actual_len, 0x00, sizeof(value) - actual_len);
00509     }
00510 
00511     /**
00512      * Equal operator between two advertising data.
00513      */
00514     friend bool operator==(
00515         const advertising_data_t& lhs, const advertising_data_t& rhs
00516     ) {
00517         return memcmp(lhs.value, rhs.value, sizeof(lhs.value)) == 0;
00518     }
00519 
00520     /**
00521      * Non equal operator between two advertising data.
00522      */
00523     friend bool operator!=(
00524         const advertising_data_t& lhs, const advertising_data_t& rhs
00525     ) {
00526         return !(lhs == rhs);
00527     }
00528 
00529     /**
00530      * Subscript operator used to access the content of the advertising data.
00531      */
00532     uint8_t operator[](uint8_t i) const {
00533         return value[i];
00534     }
00535 
00536     /**
00537      * Return a pointer to the advertising data buffer.
00538      */
00539     const uint8_t* data() const {
00540         return value;
00541     }
00542 
00543     /**
00544      * Return (fixed) size of advertising data.
00545      */
00546     static uint8_t size() {
00547         return sizeof(value);
00548     }
00549 
00550 private:
00551     uint8_t value[31];
00552 };
00553 
00554 
00555 /**
00556  * Type of advertising the LE subsystem can use when it advertise.
00557  */
00558 struct received_advertising_type_t :
00559     SafeEnum<received_advertising_type_t, uint8_t> {
00560     enum type  {
00561         /**
00562          * Connectable and scannable undirected advertising .
00563          */
00564         ADV_IND = 0x00,
00565 
00566         /**
00567          * Connectable high duty cycle directed advertising
00568          */
00569         ADV_DIRECT_IND = 0x01,
00570 
00571         /**
00572          * Scannable undirected advertising
00573          */
00574         ADV_SCAN_IND = 0x02,
00575 
00576         /**
00577          * Non connectable undirected advertising
00578          */
00579         ADV_NONCONN_IND = 0x03,
00580 
00581         /**
00582          * Response to a scan request.
00583          */
00584         SCAN_RESPONSE = 0x04
00585     };
00586 
00587     /**
00588      * Construct a new received_advertising_type_t value.
00589      */
00590     received_advertising_type_t(type  value) :
00591         SafeEnum<received_advertising_type_t, uint8_t>(value) { }
00592 };
00593 
00594 
00595 /**
00596  * Model connection role. Used in GapConnectionCompleteEvent.
00597  */
00598 struct connection_role_t : SafeEnum<connection_role_t, uint8_t> {
00599     enum type {
00600         MASTER,
00601         SLAVE
00602     };
00603 
00604     connection_role_t(type value) : SafeEnum<connection_role_t, uint8_t> (value) { }
00605 };
00606 
00607 } // namespace pal
00608 } // namespace ble
00609 
00610 #endif /* BLE_PAL_GAP_TYPES_H_ */