1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20 #ifndef H_BLE_ATT_ 21 #define H_BLE_ATT_ 22 23 /** 24 * @brief Bluetooth Attribute Protocol (ATT) 25 * @defgroup bt_att Bluetooth Attribute Protocol (ATT) 26 * @ingroup bt_host 27 * @{ 28 */ 29 30 #include "os/queue.h" 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 struct os_mbuf; 36 37 #define BLE_ATT_UUID_PRIMARY_SERVICE 0x2800 38 #define BLE_ATT_UUID_SECONDARY_SERVICE 0x2801 39 #define BLE_ATT_UUID_INCLUDE 0x2802 40 #define BLE_ATT_UUID_CHARACTERISTIC 0x2803 41 42 #define BLE_ATT_ERR_INVALID_HANDLE 0x01 43 #define BLE_ATT_ERR_READ_NOT_PERMITTED 0x02 44 #define BLE_ATT_ERR_WRITE_NOT_PERMITTED 0x03 45 #define BLE_ATT_ERR_INVALID_PDU 0x04 46 #define BLE_ATT_ERR_INSUFFICIENT_AUTHEN 0x05 47 #define BLE_ATT_ERR_REQ_NOT_SUPPORTED 0x06 48 #define BLE_ATT_ERR_INVALID_OFFSET 0x07 49 #define BLE_ATT_ERR_INSUFFICIENT_AUTHOR 0x08 50 #define BLE_ATT_ERR_PREPARE_QUEUE_FULL 0x09 51 #define BLE_ATT_ERR_ATTR_NOT_FOUND 0x0a 52 #define BLE_ATT_ERR_ATTR_NOT_LONG 0x0b 53 #define BLE_ATT_ERR_INSUFFICIENT_KEY_SZ 0x0c 54 #define BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN 0x0d 55 #define BLE_ATT_ERR_UNLIKELY 0x0e 56 #define BLE_ATT_ERR_INSUFFICIENT_ENC 0x0f 57 #define BLE_ATT_ERR_UNSUPPORTED_GROUP 0x10 58 #define BLE_ATT_ERR_INSUFFICIENT_RES 0x11 59 60 #define BLE_ATT_OP_ERROR_RSP 0x01 61 #define BLE_ATT_OP_MTU_REQ 0x02 62 #define BLE_ATT_OP_MTU_RSP 0x03 63 #define BLE_ATT_OP_FIND_INFO_REQ 0x04 64 #define BLE_ATT_OP_FIND_INFO_RSP 0x05 65 #define BLE_ATT_OP_FIND_TYPE_VALUE_REQ 0x06 66 #define BLE_ATT_OP_FIND_TYPE_VALUE_RSP 0x07 67 #define BLE_ATT_OP_READ_TYPE_REQ 0x08 68 #define BLE_ATT_OP_READ_TYPE_RSP 0x09 69 #define BLE_ATT_OP_READ_REQ 0x0a 70 #define BLE_ATT_OP_READ_RSP 0x0b 71 #define BLE_ATT_OP_READ_BLOB_REQ 0x0c 72 #define BLE_ATT_OP_READ_BLOB_RSP 0x0d 73 #define BLE_ATT_OP_READ_MULT_REQ 0x0e 74 #define BLE_ATT_OP_READ_MULT_RSP 0x0f 75 #define BLE_ATT_OP_READ_GROUP_TYPE_REQ 0x10 76 #define BLE_ATT_OP_READ_GROUP_TYPE_RSP 0x11 77 #define BLE_ATT_OP_WRITE_REQ 0x12 78 #define BLE_ATT_OP_WRITE_RSP 0x13 79 #define BLE_ATT_OP_PREP_WRITE_REQ 0x16 80 #define BLE_ATT_OP_PREP_WRITE_RSP 0x17 81 #define BLE_ATT_OP_EXEC_WRITE_REQ 0x18 82 #define BLE_ATT_OP_EXEC_WRITE_RSP 0x19 83 #define BLE_ATT_OP_NOTIFY_REQ 0x1b 84 #define BLE_ATT_OP_INDICATE_REQ 0x1d 85 #define BLE_ATT_OP_INDICATE_RSP 0x1e 86 #define BLE_ATT_OP_WRITE_CMD 0x52 87 88 #define BLE_ATT_ATTR_MAX_LEN 512 89 90 #define BLE_ATT_F_READ 0x01 91 #define BLE_ATT_F_WRITE 0x02 92 #define BLE_ATT_F_READ_ENC 0x04 93 #define BLE_ATT_F_READ_AUTHEN 0x08 94 #define BLE_ATT_F_READ_AUTHOR 0x10 95 #define BLE_ATT_F_WRITE_ENC 0x20 96 #define BLE_ATT_F_WRITE_AUTHEN 0x40 97 #define BLE_ATT_F_WRITE_AUTHOR 0x80 98 99 #define HA_FLAG_PERM_RW (BLE_ATT_F_READ | BLE_ATT_F_WRITE) 100 101 #define BLE_ATT_ACCESS_OP_READ 1 102 #define BLE_ATT_ACCESS_OP_WRITE 2 103 104 /** Default ATT MTU. Also the minimum. */ 105 #define BLE_ATT_MTU_DFLT 23 106 107 /** 108 * An ATT MTU of 527 allows the largest ATT command (signed write) to contain a 109 * 512-byte attribute value. 110 */ 111 #define BLE_ATT_MTU_MAX 527 112 113 /** 114 * Reads a locally registered attribute. If the specified attribute handle 115 * coresponds to a GATT characteristic value or descriptor, the read is 116 * performed by calling the registered GATT access callback. 117 * 118 * @param attr_handle The 16-bit handle of the attribute to read. 119 * @param out_om On success, this is made to point to a 120 * newly-allocated mbuf containing the 121 * attribute data read. 122 * 123 * @return 0 on success; 124 * NimBLE host ATT return code if the attribute 125 * access callback reports failure; 126 * NimBLE host core return code on unexpected 127 * error. 128 */ 129 int ble_att_svr_read_local(uint16_t attr_handle, struct os_mbuf **out_om); 130 131 /** 132 * Writes a locally registered attribute. This function consumes the supplied 133 * mbuf regardless of the outcome. If the specified attribute handle 134 * coresponds to a GATT characteristic value or descriptor, the write is 135 * performed by calling the registered GATT access callback. 136 * 137 * @param attr_handle The 16-bit handle of the attribute to write. 138 * @param om The value to write to the attribute. 139 * 140 * @return 0 on success; 141 * NimBLE host ATT return code if the attribute 142 * access callback reports failure; 143 * NimBLE host core return code on unexpected 144 * error. 145 */ 146 int ble_att_svr_write_local(uint16_t attr_handle, struct os_mbuf *om); 147 148 /** 149 * Retrieves the ATT MTU of the specified connection. If an MTU exchange for 150 * this connection has occurred, the MTU is the lower of the two peers' 151 * preferred values. Otherwise, the MTU is the default value of 23. 152 * 153 * @param conn_handle The handle of the connection to query. 154 * 155 * @return The specified connection's ATT MTU, or 0 if 156 * there is no such connection. 157 */ 158 uint16_t ble_att_mtu(uint16_t conn_handle); 159 160 /** 161 * Retrieves the preferred ATT MTU. This is the value indicated by the device 162 * during an ATT MTU exchange. 163 * 164 * @return The preferred ATT MTU. 165 */ 166 uint16_t ble_att_preferred_mtu(void); 167 168 /** 169 * Sets the preferred ATT MTU; the device will indicate this value in all 170 * subseqeunt ATT MTU exchanges. The ATT MTU of a connection is equal to the 171 * lower of the two peers' preferred MTU values. The ATT MTU is what dictates 172 * the maximum size of any message sent during a GATT procedure. 173 * 174 * The specified MTU must be within the following range: [23, BLE_ATT_MTU_MAX]. 175 * 23 is a minimum imposed by the Bluetooth specification; BLE_ATT_MTU_MAX is a 176 * NimBLE compile-time setting. 177 * 178 * @param mtu The preferred ATT MTU. 179 * 180 * @return 0 on success; 181 * BLE_HS_EINVAL if the specifeid value is not 182 * within the allowed range. 183 */ 184 int ble_att_set_preferred_mtu(uint16_t mtu); 185 186 #ifdef __cplusplus 187 } 188 #endif 189 190 /** 191 * @} 192 */ 193 194 #endif 195