1 /* 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 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. * Description: BT SPP module. 14 */ 15 16 /** 17 * @defgroup bluetooth_bts_spp SPP API 18 * @ingroup bluetooth 19 * @{ 20 */ 21 22 #ifndef BTS_SPP_H 23 #define BTS_SPP_H 24 25 #include <stdbool.h> 26 #include "bts_def.h" 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /** 33 * @if Eng 34 * @brief SPP is disconnected. 35 * @else 36 * @brief SPP连接已经断开。 37 * @endif 38 */ 39 #define SPP_READ_SOCKET_CLOSED (0) 40 41 /** 42 * @if Eng 43 * @brief Read data failed. 44 * @else 45 * @brief 读取数据失败。 46 * @endif 47 */ 48 #define SPP_READ_FAILED (-1) 49 50 /** 51 * @if Eng 52 * @brief Write data failed. 53 * @else 54 * @brief 写数据失败。 55 * @endif 56 */ 57 #define SPP_WRITE_FAILED (-1) 58 59 /** 60 * @if Eng 61 * @brief Invalid SPP server/client ID. 62 * @else 63 * @brief 非法SPP Server 或 Client ID。 64 * @endif 65 */ 66 #define SPP_INVALID_ID (-1) 67 68 /** 69 * @if Eng 70 * @brief Enum of SPP socket type. 71 * @else 72 * @brief SPP socket类型定义枚举。 73 * @endif 74 */ 75 typedef enum { 76 SPP_SOCKET_RFCOMM = 0x0, /*!< @if Eng RFCOMM 77 @else RFCOMM @endif */ 78 } spp_socket_type_t; 79 80 /** 81 * @if Eng 82 * @brief Parameters for create SPP socket. 83 * @else 84 * @brief 创建SPP socket的参数。 85 * @endif 86 */ 87 typedef struct { 88 bt_uuid_t uuid; /*!< @if Eng UUID of service. 89 @else SPP socket对应的服务UUID。 @endif */ 90 spp_socket_type_t socket_type; /*!< @if Eng SPP socket type 91 @else SPP socket类型。@endif */ 92 bool is_encrypt; /*!< @if Eng is encrypted (not use now, encrypted default) 93 @else 是否加密（目前此参数未使用，默认加密）。@endif */ 94 } spp_create_socket_para_t; 95 96 /** 97 * @if Eng 98 * @brief Creates an server listening socket based on the service record. 99 * @attention NULL. 100 * @param [in] socket_para The parameters to create a server socket. 101 * @param [in] name The service's name. 102 * @param [in] len The length of the service's name, len = strlen(name) + 1. 103 * @retval SPP_INVALID_ID create server fail. 104 * @retval others create server success, return a server ID. 105 * @par Dependency: 106 * @li bts_spp.h 107 * @see spp_server_accept | spp_server_close 108 * @else 109 * @brief 创建SPP Server。 110 * @attention NULL. 111 * @param [in] socket_para 入参，SPP Server创建参数。 112 * @param [in] name 入参，SPP Server 名称。 113 * @param [in] len 入参，SPP Server 名称长度，取值为strlen(name) + 1。 114 * @retval SPP_INVALID_ID 创建Server失败，返回非法ID。 115 * @retval others 创建Server成功，返回Server ID。 116 * @par 依赖: 117 * @li bts_spp.h 118 * @see spp_server_accept | spp_server_close 119 * @endif 120 */ 121 int spp_server_create(spp_create_socket_para_t *socket_para, const char *name, unsigned int len); 122 123 /** 124 * @if Eng 125 * @brief Waits for a remote device to connect to this server socket. 126 * @par Description: 127 * This method return a client ID indicates a client socket 128 * can be used to read data from and write data to remote device. 129 * @attention This is a synchronous API. 130 * @param [in] server_id The relative ID used to identify the current server 131 * socket, obtain the value by calling {@link spp_server_create}. 132 * @retval SPP_INVALID_ID Accept fail. 133 * @retval others Return a client ID if accept success. 134 * @par Dependency: 135 * @li bts_spp.h 136 * @see spp_server_create | spp_disconnect | is_spp_connected | spp_get_remote_addr | 137 * spp_read | spp_write 138 * @else 139 * @brief 等待远端设备来连接此Server。 140 * @par Description:此方法将返回一个Client ID，用户可以使用该Client与远端设备进行数据收发。 141 * @attention 这是一个同步接口。 142 * @param [in] server_id 入参，调用接口 {@link spp_server_create} 创建Server成功后得到的Server ID。 143 * @retval SPP_INVALID_ID 等待失败。 144 * @retval others 等待成功，返回一个有效的Client ID。 145 * @par 依赖: 146 * @li bts_spp.h 147 * @see spp_server_create | spp_disconnect | is_spp_connected | spp_get_remote_addr | 148 * spp_read | spp_write 149 * @endif 150 */ 151 int spp_server_accept(int server_id); 152 153 /** 154 * @if Eng 155 * @brief Disables an spp server socket and releases related resources. 156 * @attention This is a synchronous API. 157 * @param [in] server_id The relative ID used to identify the current server 158 * socket, obtain the value by calling {@link spp_server_create}. 159 * @retval #ERRCODE_BT_SUCCESS Excute successfully. 160 * @retval #Other Error code. See @ref errcode_bt_t 161 * @par Dependency: 162 * @li bts_spp.h 163 * @see spp_server_create 164 * @else 165 * @brief 关闭Server（同时释放相关资源）。 166 * @attention 这是一个同步接口。 167 * @param [in] server_id 入参，调用接口 {@link spp_server_create} 创建Server成功后得到的Server ID。 168 * @retval #ERRCODE_BT_SUCCESS 执行成功。 169 * @retval #Other 错误码。参考 @ref errcode_bt_t 170 * @par 依赖: 171 * @li bts_spp.h 172 * @see spp_server_create 173 * @endif 174 */ 175 int spp_server_close(int server_id); 176 177 /** 178 * @if Eng 179 * @brief Connects to a remote device over the socket. 180 * @attention This is a synchronous API. 181 * @param [in] socket_para The params to create a client socket and connect to a remote device. 182 * @retval SPP_INVALID_ID Connect fail. 183 * @retval others Return a client ID if accept success. 184 * @par Dependency: 185 * @li bts_spp.h 186 * @see spp_disconnect | is_spp_connected | spp_get_remote_addr | spp_read | spp_write 187 * @else 188 * @brief 连接远端设备。 189 * @attention 这是一个同步接口。 190 * @param [in] socket_para 入参，用于创建Client socket并连接远端设备的参数。 191 * @retval SPP_INVALID_ID 连接失败。 192 * @retval others 连接成功，返回有效Client ID。 193 * @par 依赖: 194 * @li bts_spp.h 195 * @see spp_disconnect | is_spp_connected | spp_get_remote_addr | spp_read | spp_write 196 * @endif 197 */ 198 int spp_connect(spp_create_socket_para_t *socket_para, const bd_addr_t *bd_addr); 199 200 /** 201 * @if Eng 202 * @brief Disables a connection and releases related resources. 203 * @attention This is a synchronous API. 204 * @param [in] client_id The relative ID used to identify the current client socket. 205 * @retval #ERRCODE_BT_SUCCESS Excute successfully. 206 * @retval #Other Error code. See @ref errcode_bt_t 207 * @par Dependency: 208 * @li bts_spp.h 209 * @see spp_server_accept | spp_connect | is_spp_connected 210 * @else 211 * @brief 断开连接（同时释放相关资源）。 212 * @attention 这是一个同步接口。 213 * @param [in] client_id 入参，用来指定当前操作Client的ID。 214 * @retval #ERRCODE_BT_SUCCESS 执行成功。 215 * @retval #Other 错误码。参考 @ref errcode_bt_t 216 * @par 依赖: 217 * @li bts_spp.h 218 * @see spp_server_accept | spp_connect | is_spp_connected 219 * @endif 220 */ 221 int spp_disconnect(int client_id); 222 223 /** 224 * @if Eng 225 * @brief Get the connection status of this socket. 226 * @attention NULL. 227 * @param [in] client_id The relative ID used to identify the current client socket. 228 * @retval true connected. 229 * @retval false disconnected. 230 * @par Dependency: 231 * @li bts_spp.h 232 * @see spp_server_accept | spp_connect | spp_disconnect 233 * @else 234 * @brief 获取指定SPP socket的连接状态。 235 * @attention NULL. 236 * @param [in] client_id 入参，用来指定当前操作Client的ID。 237 * @retval true 连接。 238 * @retval false 未连接。 239 * @par 依赖: 240 * @li bts_spp.h 241 * @see spp_server_accept | spp_connect | spp_disconnect 242 * @endif 243 */ 244 bool is_spp_connected(int client_id); 245 246 /** 247 * @if Eng 248 * @brief Spp get remote device's address. 249 * @attention NULL. 250 * @param [in] client_id The relative ID used to identify the current client socket. 251 * @param [out] remote_addr Remote device's address, memory allocated by caller. 252 * @retval #ERRCODE_BT_SUCCESS Excute successfully. 253 * @retval #Other Error code. See @ref errcode_bt_t 254 * @par Dependency: 255 * @li bts_spp.h 256 * @see spp_server_accept | spp_connect | is_spp_connected 257 * @else 258 * @brief 获取SPP socket对应远端设备的地址。 259 * @attention NULL. 260 * @param [in] client_id 入参，用来指定当前操作Client的ID。 261 * @param [out] remote_addr 出参，远端设备的地址。 262 * @retval #ERRCODE_BT_SUCCESS 执行成功。 263 * @retval #Other 错误码。参考 @ref errcode_bt_t 264 * @par 依赖: 265 * @li bts_spp.h 266 * @see spp_server_accept | spp_connect | is_spp_connected 267 * @endif 268 */ 269 int spp_get_remote_addr(int client_id, bd_addr_t *remote_addr); 270 271 /** 272 * @if Eng 273 * @brief Client write data to socket. 274 * @attention NULL. 275 * @param [in] client_id The relative ID used to identify the current client socket. 276 * @param [in] data Indicate the data to be written. 277 * @param [in] len Indicates the length of the data to be written. 278 * @retval SPP_WRITE_FAILED The operation failed. 279 * @retval others The actual write length. 280 * @par Dependency: 281 * @li bts_spp.h 282 * @see spp_server_accept | spp_connect | spp_disconnect | is_spp_connected 283 * @else 284 * @brief 向SPP socket写入数据 285 * @attention NULL. 286 * @param [in] client_id 入参，用来指定当前操作Client的ID。 287 * @param [in] data 入参，存储待写入数据的buf。 288 * @param [in] len 入参，待写入数据的长度。 289 * @retval SPP_WRITE_FAILED 操作失败。 290 * @retval others 操作成功，返回实际写入长度，单位字节。 291 * @par 依赖: 292 * @li bts_spp.h 293 * @see spp_server_accept | spp_connect | spp_disconnect | is_spp_connected 294 * @endif 295 */ 296 int spp_write(int client_id, const char *data, const unsigned int len); 297 298 /** 299 * @if Eng 300 * @brief Callback function for connection event. 301 * @par Description: When registered, this callback reports connection event to upper layer application. 302 * @param [in] client_id The relative ID used to identify the current client socket. 303 * @param [in] state Connect state of spp. See {@link profile_connect_state_t} 304 * @retval #void No return value. 305 * @par Dependency: 306 * @li bts_spp.h 307 * @see spp_client_callbacks_t 308 * @else 309 * @brief 连接变化事件回调函数。 310 * @par 说明: 注册该回调函数之后，bluetooth调用该回调函数将连接事件上报给上层。 311 * @param [in] client_id 入参，用来指定当前操作Client的ID。 312 * @param [in] state spp的连接状态。见 {@link profile_connect_state_t} 313 * @retval #void 无返回值。 314 * @par 依赖: 315 * @li bts_spp.h 316 * @see spp_callbacks_t 317 * @endif 318 */ 319 typedef void (*spp_conn_state_changed_callback)(uint8_t client_id, profile_connect_state_t state); 320 321 /** 322 * @if Eng 323 * @brief Callback function for data reception. 324 * @par Description: When registered, this callback reports received data to upper layer application. 325 * @param [in] client_id The relative ID used to identify the current client socket. 326 * @param [in] data Received data. 327 * @param [in] data_len Length of data. 328 * @retval #void No return value. 329 * @par Dependency: 330 * @li bts_spp.h 331 * @see spp_client_callbacks_t 332 * @else 333 * @brief 接收到数据回调函数。 334 * @par 说明: 注册该回调函数之后，bluetooth调用该回调函数将接收到的数据上报给上层。 335 * @param [in] client_id 入参，用来指定当前操作Client的ID。 336 * @param [in] data 接收到的数据。 337 * @param [in] data_len 数据长度。 338 * @retval #void 无返回值。 339 * @par 依赖: 340 * @li bts_spp.h 341 * @see spp_callbacks_t 342 * @endif 343 */ 344 typedef void (*spp_receive_data_callback)(uint8_t client_id, uint8_t *data, uint32_t data_len); 345 346 /** 347 * @if Eng 348 * @brief Struct of SPP callback functions. 349 * @else 350 * @brief SPP回调函数接口定义。 351 * @endif 352 */ 353 typedef struct { 354 spp_receive_data_callback receive_data_cb; 355 spp_conn_state_changed_callback conn_state_changed_cb; 356 } spp_callbacks_t; 357 358 /** 359 * @if Eng 360 * @brief Register callback functions for PBAP. 361 * @par Description: Register callback functions for PBAP. 362 * @attention 1. This function is called in bts context,should not be blocked or do long time waiting. 363 * @attention 2. The memories of <devices> are requested and freed by the bts automatically. 364 * @param [in] func A poniter of the Callback funcs.See @ref spp_client_callbacks_t 365 * @retval #ERRCODE_BT_SUCCESS Excute successfully. 366 * @retval #Other Error code. See @ref errcode_bt_t 367 * @par Dependency: 368 * @li bts_pbap.h 369 * @see spp_callbacks_t 370 * @else 371 * @brief 注册PBAP回调函数。 372 * @par 说明: 注册上层应用的回调。 373 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 374 * @attention 2. <devices>由bts申请内存，也由bts释放，回调中不应释放。 375 * @param [in] func 指向回调函数接口定义的指针。见 @ref spp_callbacks_t 376 * @retval #ERRCODE_BT_SUCCESS 执行成功。 377 * @retval #Other 错误码。参考 @ref errcode_bt_t 378 * @par 依赖: 379 * @li bts_pbap.h 380 * @see spp_callbacks_t 381 * @endif 382 */ 383 int spp_register_callbacks(spp_callbacks_t *func); 384 385 /** 386 * @} 387 */ 388 389 #ifdef __cplusplus 390 } 391 #endif 392 #endif 393