1 /* 2 * Copyright (C) 2021-2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://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, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef OHOS_BT_GATT_CLIENT_H 17 #define OHOS_BT_GATT_CLIENT_H 18 19 #include "ohos_bt_def.h" 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 typedef enum { 26 OHOS_BT_TRANSPORT_TYPE_AUTO = 0x0, 27 OHOS_BT_TRANSPORT_TYPE_LE, 28 OHOS_BT_TRANSPORT_TYPE_CLASSIC, 29 } BtTransportType; 30 31 typedef enum { 32 OHOS_BT_GATT_PRIORITY_BALANCED = 0x0, 33 OHOS_BT_GATT_PRIORITY_HIGH, 34 OHOS_BT_GATT_PRIORITY_LOW_POWER, 35 } BtGattPriority; 36 37 typedef struct { 38 BtUuid serviceUuid; 39 BtUuid characteristicUuid; 40 } BtGattCharacteristic; 41 42 typedef struct { 43 BtGattCharacteristic characteristic; 44 BtUuid descriptorUuid; 45 } BtGattDescriptor; 46 47 /* Parameters for GATT read operations */ 48 typedef struct { 49 union { 50 BtGattCharacteristic characteristic; 51 BtGattDescriptor descriptor; 52 } attribute; 53 unsigned short dataLen; 54 unsigned char *data; 55 } BtGattReadData; 56 57 /** 58 * @brief Callback invoked when the connection state changed. 59 * 60 * @param clientId Indicates the ID of the GATT client. 61 * @param connectionState Indicate the connect state {@link BtConnectState}. 62 * @param status Indicate the operation result status {@link BtStatus}. 63 */ 64 typedef void (*ConnectionStateChangedCallback)(int clientId, int connectionState, int status); 65 66 /** 67 * @brief Callback invoked when the connection parameters for a given connection changed. 68 * 69 * @param clientId Indicates the ID of the GATT client. 70 * @param interval The connection interval used on this connection. If N is returned, it indicates N*1.25ms. 71 * @param latency The slave latency for the connection in number of connection events. 72 * @param timeout The supervision timeout for this connection. If N is returned, it indicates N*10ms. 73 * @param status Indicate the operation result status {@link BtStatus}. 74 */ 75 typedef void (*ConnectParaUpdateCallback)(int clientId, int interval, int latency, int timeout, int status); 76 77 /** 78 * @brief Invoked in response to BleGattcSearchServices when the GATT service discovery has been completed. 79 * 80 * @param clientId Indicates the ID of the GATT client. 81 * @param status Indicate the operation result status {@link BtStatus}. 82 */ 83 typedef void (*SearchServiceCompleteCallback)(int clientId, int status); 84 85 /** 86 * @brief Reports result of a characteristic read operation. 87 * 88 * @param clientId Indicates the ID of the GATT client. 89 * @param readData The characteristic value read from the server. 90 * @param status Indicate the operation result status {@link BtStatus}. 91 */ 92 typedef void (*ReadCharacteristicCallback)(int clientId, BtGattReadData *readData, int status); 93 94 /** 95 * @brief GATT write characteristic operation callback. 96 * 97 * @param clientId Indicates the ID of the GATT client. 98 * @param characteristic The UUID of the characteristic. 99 * @param status Indicate the operation result status {@link BtStatus}. 100 */ 101 typedef void (*WriteCharacteristicCallback)(int clientId, BtGattCharacteristic *characteristic, int status); 102 103 /** 104 * @brief Reports result of a descriptor read operation. 105 * 106 * @param clientId Indicates the ID of the GATT client. 107 * @param readData The descriptor value read from the server. 108 * @param status Indicate the operation result status {@link BtStatus}. 109 */ 110 typedef void (*ReadDescriptorCallback)(int clientId, BtGattReadData *readData, int status); 111 112 /** 113 * @brief GATT write descriptor operation callback. 114 * 115 * @param clientId Indicates the ID of the GATT client. 116 * @param descriptor The UUID of the descriptor. 117 * @param status Indicate the operation result status {@link BtStatus}. 118 */ 119 typedef void (*WriteDescriptorCallback)(int clientId, BtGattDescriptor *descriptor, int status); 120 121 /** 122 * @brief Callback invoked when the MTU size for a given connection changed. 123 * 124 * @param clientId Indicates the ID of the GATT client. 125 * @param mtuSize The size of MTU. 126 * @param status Indicate the operation result status {@link BtStatus}. 127 */ 128 typedef void (*ConfigureMtuSizeCallback)(int clientId, int mtuSize, int status); 129 130 /** 131 * @brief Callback invoked in response to GATT notification registered. 132 * 133 * @param clientId Indicates the ID of the GATT client. 134 * @param status Indicate the operation result status {@link BtStatus}. 135 */ 136 typedef void (*RegisterNotificationCallback)(int clientId, int status); 137 138 /** 139 * @brief Callback invoked when a remote device sends a notification that a client has registered for. 140 * 141 * @param clientId Indicates the ID of the GATT client. 142 * @param notifyData The characteristic value notifed by the server. 143 * @param status Indicate the operation result status {@link BtStatus}. 144 */ 145 typedef void (*NotificationCallback)(int clientId, BtGattReadData *notifyData, int status); 146 147 typedef struct { 148 ConnectionStateChangedCallback ConnectionStateCb; 149 ConnectParaUpdateCallback connectParaUpdateCb; 150 SearchServiceCompleteCallback searchServiceCompleteCb; 151 ReadCharacteristicCallback readCharacteristicCb; 152 WriteCharacteristicCallback writeCharacteristicCb; 153 ReadDescriptorCallback readDescriptorCb; 154 WriteDescriptorCallback writeDescriptorCb; 155 ConfigureMtuSizeCallback configureMtuSizeCb; 156 RegisterNotificationCallback registerNotificationCb; 157 NotificationCallback notificationCb; 158 } BtGattClientCallbacks; 159 160 /** 161 * @brief Registers a GATT client with a specified application UUID. 162 * 163 * @param appUuid Indicates the UUID of the application for which the GATT client is to be registered. 164 * The UUID is defined by the application. 165 * @return Returns the client ID. 166 */ 167 int BleGattcRegister(BtUuid appUuid); 168 169 /** 170 * @brief Unregisters a GATT client with a specified ID. 171 * 172 * @param clientId Indicates the ID of the GATT client. 173 * @return Returns the operation result status {@link BtStatus}. 174 */ 175 int BleGattcUnRegister(int clientId); 176 177 /** 178 * @brief Set fastest connection of the Gatt connection, add address to the accelerate connection map 179 * before create a new connection. 180 * 181 * @param clientId Indicates the ID of the GATT client. 182 * @param fastestConnFlag Indicates whether to enable the fastest connection. 183 * @return Returns the operation result status {@link BtStatus}. 184 */ 185 int BleGattcSetFastestConn(int clientId, bool fastestConnFlag); 186 187 /** 188 * @brief Create a Gatt connection to a remote device. 189 * 190 * @param clientId Indicates the ID of the GATT client. 191 * @param bdAddr Indicates the remote device's address. 192 * @param isAutoConnect Indicates whether it is a direct connection(false) or a background connection(true). 193 * @param transport Indicates the transport of Gatt client {@link BtTransportType}. 194 * @return Returns the operation result status {@link BtStatus}. 195 */ 196 int BleGattcConnect(int clientId, BtGattClientCallbacks *func, const BdAddr *bdAddr, 197 bool isAutoConnect, BtTransportType transport); 198 199 /** 200 * @brief Set priority of the Gatt connection. 201 * 202 * @param clientId Indicates the ID of the GATT client. 203 * @param bdAddr Indicates the remote device's address. 204 * @param priority Indicates the priority of Gatt client {@link BtGattPriority}. 205 * @return Returns the operation result status {@link BtStatus}. 206 */ 207 int BleGattcSetPriority(int clientId, const BdAddr *bdAddr, BtGattPriority priority); 208 209 /** 210 * @brief Disconnect a Gatt connection with a remote device. 211 * 212 * @param clientId Indicates the ID of the GATT client. 213 * @Returns the operation result status {@link BtStatus}. 214 */ 215 int BleGattcDisconnect(int clientId); 216 217 /** 218 * @brief Request a GATT service discovery on a remote device. 219 * 220 * @param clientId Indicates the ID of the GATT client. 221 * @return Returns the operation result status {@link BtStatus}. 222 */ 223 int BleGattcSearchServices(int clientId); 224 225 /** 226 * @brief Check whether the expected service exists. 227 * 228 * @param clientId Indicates the ID of the GATT client. 229 * @param serviceUuid Indicates the UUID of the service. 230 * @return Returns true or false. 231 */ 232 bool BleGattcGetService(int clientId, BtUuid serviceUuid); 233 234 /** 235 * @brief Read characteristic value from the remote device. 236 * 237 * @param clientId Indicates the ID of the GATT client. 238 * @param characteristic The specified characteristic {@link BtGattCharacteristic} to be read. 239 * @return Returns the operation result status {@link BtStatus}. 240 */ 241 int BleGattcReadCharacteristic(int clientId, BtGattCharacteristic characteristic); 242 243 /** 244 * @brief Write characteristic value to the remote device. 245 * 246 * @param clientId Indicates the ID of the GATT client. 247 * @param characteristic The specified characteristic {@link BtGattCharacteristic} to be read. 248 * @param writeType Indicates the characteristic write type. 249 * @param value The value to be write. 250 * @param len The length of the value. 251 * @return Returns the operation result status {@link BtStatus}. 252 */ 253 int BleGattcWriteCharacteristic(int clientId, BtGattCharacteristic characteristic, 254 BtGattWriteType writeType, int len, const char *value); 255 256 /** 257 * @brief Read descriptor value from the remote device. 258 * 259 * @param clientId Indicates the ID of the GATT client. 260 * @param descriptor The specified characteristic {@link BtGattDescriptor} to be read. 261 * @return Returns the operation result status {@link BtStatus}. 262 */ 263 int BleGattcReadDescriptor(int clientId, BtGattDescriptor descriptor); 264 265 /** 266 * @brief Write descriptor value to the remote device. 267 * 268 * @param clientId Indicates the ID of the GATT client. 269 * @param descriptor The specified descriptor {@link BtGattDescriptor} to be read. 270 * @param value The value to be write. 271 * @param len The length of the value. 272 * @return Returns the operation result status {@link BtStatus}. 273 */ 274 int BleGattcWriteDescriptor(int clientId, BtGattDescriptor descriptor, int len, const char *value); 275 276 /** 277 * @brief Configure the ATT MTU size. 278 * 279 * @param clientId Indicates the ID of the GATT client. 280 * @param mtuSize The size of MTU. 281 * @return Returns the operation result status {@link BtStatus}. 282 */ 283 int BleGattcConfigureMtuSize(int clientId, int mtuSize); 284 285 /** 286 * @brief Enable or disable notifications for a given characteristic. 287 * 288 * @param clientId Indicates the ID of the GATT client. 289 * @param characteristic The specified characteristic {@link BtGattCharacteristic}. 290 * @param enable True or false. 291 * @return Returns the operation result status {@link BtStatus}. 292 */ 293 int BleGattcRegisterNotification(int clientId, BtGattCharacteristic characteristic, bool enable); 294 295 #ifdef __cplusplus 296 } 297 #endif 298 #endif 299 /** @} */ 300 301