1 // Copyright 2022 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 #pragma once 15 16 #include <cstdint> 17 #include <optional> 18 19 #include "pw_bluetooth/config.h" 20 #include "pw_bluetooth/types.h" 21 #include "pw_containers/vector.h" 22 #include "pw_span/span.h" 23 24 namespace pw::bluetooth::gatt { 25 26 /// A Handle identifies a characteristic or descriptor. This is not expected to 27 /// match the actual GATT database handle, although it may. 28 enum class Handle : uint64_t {}; 29 30 /// A handle that uniquely identifies a service. 31 enum class ServiceHandle : uint64_t {}; 32 33 // Possible values for the characteristic properties bitfield. These specify 34 // the GATT procedures that are allowed for a particular characteristic. 35 enum class CharacteristicPropertyBits : uint16_t { 36 kBroadcast = 0x1, 37 kRead = 0x2, 38 kWriteWithoutResponse = 0x4, 39 kWrite = 0x8, 40 kNotify = 0x10, 41 kIndicate = 0x20, 42 kAuthenticatedSignedWrites = 0x40, 43 kReliableWrite = 0x100, 44 kWritableAuxiliaries = 0x200 45 }; 46 47 // Helper operators to allow combining and comparing CharacteristicPropertyBits 48 // values. 49 inline constexpr bool operator&(CharacteristicPropertyBits left, 50 CharacteristicPropertyBits right) { 51 return static_cast<bool>( 52 static_cast<std::underlying_type_t<CharacteristicPropertyBits>>(left) & 53 static_cast<std::underlying_type_t<CharacteristicPropertyBits>>(right)); 54 } 55 56 inline constexpr CharacteristicPropertyBits operator|( 57 CharacteristicPropertyBits left, CharacteristicPropertyBits right) { 58 return static_cast<CharacteristicPropertyBits>( 59 static_cast<std::underlying_type_t<CharacteristicPropertyBits>>(left) | 60 static_cast<std::underlying_type_t<CharacteristicPropertyBits>>(right)); 61 } 62 63 inline constexpr CharacteristicPropertyBits& operator|=( 64 CharacteristicPropertyBits& left, CharacteristicPropertyBits right) { 65 return left = left | right; 66 } 67 68 // Represents encryption, authentication, and authorization permissions that can 69 // be assigned to a specific access permission. 70 struct SecurityRequirements { 71 // If true, the physical link must be encrypted to access this attribute. 72 bool encryption_required; 73 74 // If true, the physical link must be authenticated to access this 75 // attribute. 76 bool authentication_required; 77 78 // If true, the client needs to be authorized before accessing this 79 // attribute. 80 bool authorization_required; 81 }; 82 83 /// Specifies the access permissions for a specific attribute value. 84 struct AttributePermissions { 85 // Specifies whether or not an attribute has the read permission. If null, 86 // then the attribute value cannot be read. Otherwise, it can be read only if 87 // the permissions specified in the SecurityRequirements table are satisfied. 88 std::optional<SecurityRequirements> read; 89 90 // Specifies whether or not an attribute has the write permission. If null, 91 // then the attribute value cannot be written. Otherwise, it can be written 92 // only if the permissions specified in the SecurityRequirements table are 93 // satisfied. 94 std::optional<SecurityRequirements> write; 95 96 // Specifies the security requirements for a client to subscribe to 97 // notifications or indications on a characteristic. A characteristic's 98 // support for notifications or indications is specified using the NOTIFY and 99 // INDICATE characteristic properties. If a local characteristic has one of 100 // these properties then this field can not be null. Otherwise, this field 101 // must be left as null. 102 // 103 // This field is ignored for Descriptors. 104 std::optional<SecurityRequirements> update; 105 }; 106 107 // Represents a local or remote GATT characteristic descriptor. 108 struct Descriptor { 109 // Uniquely identifies this descriptor within a service. 110 // For local descriptors, the specified handle must be unique 111 // across all characteristic and descriptor handles in this service. 112 Handle handle; 113 114 // The UUID that identifies the type of this descriptor. 115 Uuid type; 116 117 // The attribute permissions of this descriptor. For remote descriptors, this 118 // value will be null until the permissions are discovered via read and write 119 // requests. 120 std::optional<AttributePermissions> permissions; 121 }; 122 123 // Represents a local or remote GATT characteristic. 124 struct Characteristic { 125 // Uniquely identifies this characteristic within a service. 126 // For local characteristics, the specified handle must be unique across 127 // all characteristic and descriptor handles in this service. 128 Handle handle; 129 130 // The UUID that identifies the type of this characteristic. 131 Uuid type; 132 133 // The characteristic properties bitfield. This is a logic or of any number of 134 // values from `CharacteristicPropertyBits` above. 135 CharacteristicPropertyBits properties; 136 137 // The attribute permissions of this characteristic. For remote 138 // characteristics, this value will be null until the permissions are 139 // discovered via read and write requests. 140 std::optional<AttributePermissions> permissions; 141 142 // The descriptors of this characteristic. 143 span<const Descriptor> descriptors; 144 }; 145 146 /// Represents a local or remote GATT characteristic. 147 struct Characteristic2 { 148 /// Uniquely identifies this characteristic within a service. 149 /// For local characteristics, the specified handle must be unique across 150 /// all characteristic and descriptor handles in this service. 151 Handle handle; 152 153 /// The UUID that identifies the type of this characteristic. 154 Uuid type; 155 156 /// The characteristic properties bitfield. This is a logic or of any number 157 /// of values from `CharacteristicPropertyBits` above. 158 CharacteristicPropertyBits properties; 159 160 /// The attribute permissions of this characteristic. For remote 161 /// characteristics, this value will be null until the permissions are 162 /// discovered via read and write requests. 163 std::optional<AttributePermissions> permissions; 164 165 /// The descriptors of this characteristic. 166 Vector<Descriptor, PW_BLUETOOTH_DESCRIPTOR_VEC_SIZE> descriptors; 167 }; 168 169 } // namespace pw::bluetooth::gatt 170