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 "pw_bluetooth/gatt/client.h" 17 #include "pw_bluetooth/internal/raii_ptr.h" 18 #include "pw_bluetooth/types.h" 19 20 namespace pw::bluetooth::low_energy { 21 22 /// Actual connection parameters returned by the controller. 23 struct ConnectionParameters { 24 /// The connection interval indicates the frequency of link layer connection 25 /// events over which data channel PDUs can be transmitted. See Core Spec 26 /// v5.3, Vol 6, Part B, Section 4.5.1 for more information on the link layer 27 /// connection events. 28 /// - Range: 0x0006 to 0x0C80 29 /// - Time: N * 1.25 ms 30 /// - Time Range: 7.5 ms to 4 s. 31 uint16_t interval; 32 33 /// The maximum allowed peripheral connection latency in number of connection 34 /// events. See Core Spec v5.3, Vol 6, Part B, Section 4.5.2. 35 /// - Range: 0x0000 to 0x01F3 36 uint16_t latency; 37 38 /// This defines the maximum time between two received data packet PDUs 39 /// before the connection is considered lost. See Core Spec v5.3, Vol 6, Part 40 /// B, Section 4.5.2. 41 /// - Range: 0x000A to 0x0C80 42 /// - Time: N * 10 ms 43 /// - Time Range: 100 ms to 32 s 44 uint16_t supervision_timeout; 45 }; 46 47 /// Connection parameters that either the local device or a peer device are 48 /// requesting. 49 struct RequestedConnectionParameters { 50 /// Minimum value for the connection interval. This shall be less than or 51 /// equal to `max_interval`. The connection interval indicates the frequency 52 /// of link layer connection events over which data channel PDUs can be 53 /// transmitted. See Core Spec v5.3, Vol 6, Part B, Section 4.5.1 for more 54 /// information on the link layer connection events. 55 /// - Range: 0x0006 to 0x0C80 56 /// - Time: N * 1.25 ms 57 /// - Time Range: 7.5 ms to 4 s. 58 uint16_t min_interval; 59 60 /// Maximum value for the connection interval. This shall be greater than or 61 /// equal to `min_interval`. The connection interval indicates the frequency 62 /// of link layer connection events over which data channel PDUs can be 63 /// transmitted. See Core Spec v5.3, Vol 6, Part B, Section 4.5.1 for more 64 /// information on the link layer connection events. 65 /// - Range: 0x0006 to 0x0C80 66 /// - Time: N * 1.25 ms 67 /// - Time Range: 7.5 ms to 4 s. 68 uint16_t max_interval; 69 70 /// Maximum peripheral latency for the connection in number of connection 71 /// events. See Core Spec v5.3, Vol 6, Part B, Section 4.5.2. 72 /// - Range: 0x0000 to 0x01F3 73 uint16_t max_latency; 74 75 /// This defines the maximum time between two received data packet PDUs 76 /// before the connection is considered lost. See Core Spec v5.3, Vol 6, Part 77 /// B, Section 4.5.2. 78 /// - Range: 0x000A to 0x0C80 79 /// - Time: N * 10 ms 80 /// - Time Range: 100 ms to 32 s 81 uint16_t supervision_timeout; 82 }; 83 84 /// Represents parameters that are set on a per-connection basis. 85 struct ConnectionOptions { 86 /// When true, the connection operates in bondable mode. This means pairing 87 /// will form a bond, or persist across disconnections, if the peer is also 88 /// in bondable mode. When false, the connection operates in non-bondable 89 /// mode, which means the local device only allows pairing that does not form 90 /// a bond. 91 bool bondable_mode = true; 92 93 /// When present, service discovery performed following the connection is 94 /// restricted to primary services that match this field. Otherwise, by 95 /// default all available services are discovered. 96 std::optional<Uuid> service_filter; 97 98 /// When present, specifies the initial connection parameters. Otherwise, the 99 /// connection parameters will be selected by the implementation. 100 std::optional<RequestedConnectionParameters> parameters; 101 }; 102 103 /// Class that represents a connection to a peer. This can be used to interact 104 /// with GATT services and establish LE L2CAP channels. 105 /// 106 /// This lifetime of this object is tied to that of the LE connection it 107 /// represents. Destroying the object results in a disconnection. 108 class Connection { 109 public: 110 /// Possible errors when updating the connection parameters. 111 enum class ConnectionParameterUpdateError : uint8_t { 112 kFailure, 113 kInvalidParameters, 114 kRejected, 115 }; 116 117 /// Possible reasons a connection was disconnected. 118 enum class DisconnectReason : uint8_t { 119 kFailure, 120 kRemoteUserTerminatedConnection, 121 /// This usually indicates that the link supervision timeout expired. 122 kConnectionTimeout, 123 }; 124 125 /// If a disconnection has not occurred, destroying this object will result in 126 /// disconnection. 127 virtual ~Connection() = default; 128 129 /// Sets a callback that will be called when the peer disconnects or there is 130 /// a connection error that causes a disconnection. This should be configured 131 /// by the client immediately after establishing the connection. `callback` 132 /// will not be called for disconnections initiated by the client (e.g. by 133 /// destroying `Connection`). It is OK to destroy this object from within 134 /// `callback`. 135 virtual void SetDisconnectCallback( 136 Function<void(DisconnectReason)>&& callback) = 0; 137 138 /// Returns a GATT client to the connected peer that is valid for the lifetime 139 /// of this connection. The client is valid for the lifetime of this 140 /// connection. 141 virtual gatt::Client* GattClient() = 0; 142 143 /// Returns the current ATT Maximum Transmission Unit. By subtracting ATT 144 /// headers from the MTU, the maximum payload size of messages can be 145 /// calculated. 146 virtual uint16_t AttMtu() = 0; 147 148 /// Sets a callback that will be called with the new ATT MTU whenever it is 149 /// updated. 150 virtual void SetAttMtuChangeCallback(Function<void(uint16_t)> callback) = 0; 151 152 /// Returns the current connection parameters. 153 virtual ConnectionParameters Parameters() = 0; 154 155 /// Requests an update to the connection parameters. `callback` will be called 156 /// with the result of the request. 157 virtual void RequestConnectionParameterUpdate( 158 RequestedConnectionParameters parameters, 159 Function<void(Result<ConnectionParameterUpdateError>)>&& callback) = 0; 160 161 private: 162 /// Request to disconnect this connection. This method is called by the 163 /// ~Connection::Ptr() when it goes out of scope, the API client should never 164 /// call this method. 165 virtual void Disconnect() = 0; 166 167 public: 168 /// Movable Connection smart pointer. When Connection::Ptr is destroyed the 169 /// Connection will disconnect automatically. 170 using Ptr = internal::RaiiPtr<Connection, &Connection::Disconnect>; 171 }; 172 173 } // namespace pw::bluetooth::low_energy 174