1 /******************************************************************************
2 *
3 * Copyright 1999-2012 Broadcom Corporation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at:
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 ******************************************************************************/
18
19 /******************************************************************************
20 *
21 * this file contains the PORT API definitions
22 *
23 ******************************************************************************/
24 #ifndef PORT_API_H
25 #define PORT_API_H
26
27 #include <hardware/bt_sock.h>
28
29 #include <cstdint>
30
31 #include "include/macros.h"
32 #include "internal_include/bt_target.h"
33 #include "types/raw_address.h"
34
35 /*****************************************************************************
36 * Constants and Types
37 ****************************************************************************/
38
39 /*
40 * Define port settings structure send from the application in the
41 * set settings request, or to the application in the set settings indication.
42 */
43 struct PortSettings {
44 #define PORT_BAUD_RATE_9600 0x03
45
46 uint8_t baud_rate;
47
48 #define PORT_8_BITS 0x03
49
50 uint8_t byte_size;
51
52 #define PORT_ONESTOPBIT 0x00
53 uint8_t stop_bits;
54
55 #define PORT_PARITY_NO 0x00
56 uint8_t parity;
57
58 #define PORT_ODD_PARITY 0x00
59
60 uint8_t parity_type;
61
62 #define PORT_FC_OFF 0x00
63 #define PORT_FC_CTS_ON_INPUT 0x04
64 #define PORT_FC_CTS_ON_OUTPUT 0x08
65
66 uint8_t fc_type;
67
68 uint8_t rx_char1;
69
70 #define PORT_XON_DC1 0x11
71 uint8_t xon_char;
72
73 #define PORT_XOFF_DC3 0x13
74 uint8_t xoff_char;
75 };
76
77 /*
78 * Define the callback function prototypes. Parameters are specific
79 * to each event and are described bellow
80 */
81 typedef int(tPORT_DATA_CALLBACK)(uint16_t port_handle, void* p_data, uint16_t len);
82
83 #define DATA_CO_CALLBACK_TYPE_INCOMING 1
84 #define DATA_CO_CALLBACK_TYPE_OUTGOING_SIZE 2
85 #define DATA_CO_CALLBACK_TYPE_OUTGOING 3
86 typedef int(tPORT_DATA_CO_CALLBACK)(uint16_t port_handle, uint8_t* p_buf, uint16_t len, int type);
87
88 typedef void(tPORT_CALLBACK)(uint32_t code, uint16_t port_handle);
89
90 /*
91 * Define events that registered application can receive in the callback
92 */
93
94 #define PORT_EV_RXCHAR 0x00000001 /* Any Character received */
95 #define PORT_EV_RXFLAG 0x00000002 /* Received certain character */
96 #define PORT_EV_TXEMPTY 0x00000004 /* Transmitt Queue Empty */
97 #define PORT_EV_CTS 0x00000008 /* CTS changed state */
98 #define PORT_EV_DSR 0x00000010 /* DSR changed state */
99 #define PORT_EV_RLSD 0x00000020 /* RLSD changed state */
100 #define PORT_EV_BREAK 0x00000040 /* BREAK received */
101 #define PORT_EV_ERR 0x00000080 /* Line status error occurred */
102 #define PORT_EV_RING 0x00000100 /* Ring signal detected */
103 #define PORT_EV_CTSS 0x00000400 /* CTS state */
104 #define PORT_EV_DSRS 0x00000800 /* DSR state */
105 #define PORT_EV_RLSDS 0x00001000 /* RLSD state */
106 #define PORT_EV_OVERRUN 0x00002000 /* receiver buffer overrun */
107 #define PORT_EV_TXCHAR 0x00004000 /* Any character transmitted */
108
109 /* RFCOMM connection established */
110 #define PORT_EV_CONNECTED 0x00000200
111 /* Unable to establish connection or disconnected */
112 #define PORT_EV_CONNECT_ERR 0x00008000
113 /* data flow enabled flag changed by remote */
114 #define PORT_EV_FC 0x00010000
115 /* data flow enable status true = enabled */
116 #define PORT_EV_FCS 0x00020000
117
118 /*
119 * Define port result codes
120 */
121 typedef enum {
122 PORT_SUCCESS = 0,
123 PORT_UNKNOWN_ERROR = 1,
124 PORT_ALREADY_OPENED = 2,
125 PORT_CMD_PENDING = 3,
126 PORT_APP_NOT_REGISTERED = 4,
127 PORT_NO_MEM = 5,
128 PORT_NO_RESOURCES = 6,
129 PORT_BAD_BD_ADDR = 7,
130 PORT_BAD_HANDLE = 9,
131 PORT_NOT_OPENED = 10,
132 PORT_LINE_ERR = 11,
133 PORT_START_FAILED = 12,
134 PORT_PAR_NEG_FAILED = 13,
135 PORT_PORT_NEG_FAILED = 14,
136 PORT_SEC_FAILED = 15,
137 PORT_PEER_CONNECTION_FAILED = 16,
138 PORT_PEER_FAILED = 17,
139 PORT_PEER_TIMEOUT = 18,
140 PORT_CLOSED = 19,
141 PORT_TX_FULL = 20,
142 PORT_LOCAL_CLOSED = 21,
143 PORT_LOCAL_TIMEOUT = 22,
144 PORT_TX_QUEUE_DISABLED = 23,
145 PORT_PAGE_TIMEOUT = 24,
146 PORT_INVALID_SCN = 25,
147 PORT_ERR_MAX = 26,
148 } tPORT_RESULT;
149
port_result_text(const tPORT_RESULT & result)150 inline std::string port_result_text(const tPORT_RESULT& result) {
151 switch (result) {
152 CASE_RETURN_STRING(PORT_SUCCESS);
153 CASE_RETURN_STRING(PORT_UNKNOWN_ERROR);
154 CASE_RETURN_STRING(PORT_ALREADY_OPENED);
155 CASE_RETURN_STRING(PORT_CMD_PENDING);
156 CASE_RETURN_STRING(PORT_APP_NOT_REGISTERED);
157 CASE_RETURN_STRING(PORT_NO_MEM);
158 CASE_RETURN_STRING(PORT_NO_RESOURCES);
159 CASE_RETURN_STRING(PORT_BAD_BD_ADDR);
160 CASE_RETURN_STRING(PORT_BAD_HANDLE);
161 CASE_RETURN_STRING(PORT_NOT_OPENED);
162 CASE_RETURN_STRING(PORT_LINE_ERR);
163 CASE_RETURN_STRING(PORT_START_FAILED);
164 CASE_RETURN_STRING(PORT_PAR_NEG_FAILED);
165 CASE_RETURN_STRING(PORT_PORT_NEG_FAILED);
166 CASE_RETURN_STRING(PORT_SEC_FAILED);
167 CASE_RETURN_STRING(PORT_PEER_CONNECTION_FAILED);
168 CASE_RETURN_STRING(PORT_PEER_FAILED);
169 CASE_RETURN_STRING(PORT_PEER_TIMEOUT);
170 CASE_RETURN_STRING(PORT_CLOSED);
171 CASE_RETURN_STRING(PORT_TX_FULL);
172 CASE_RETURN_STRING(PORT_LOCAL_CLOSED);
173 CASE_RETURN_STRING(PORT_LOCAL_TIMEOUT);
174 CASE_RETURN_STRING(PORT_TX_QUEUE_DISABLED);
175 CASE_RETURN_STRING(PORT_PAGE_TIMEOUT);
176 CASE_RETURN_STRING(PORT_INVALID_SCN);
177 CASE_RETURN_STRING(PORT_ERR_MAX);
178 default:
179 break;
180 }
181 RETURN_UNKNOWN_TYPE_STRING(tPORT_RESULT, result);
182 }
183
184 /* Define a structure to hold the configuration parameters. Since the
185 * parameters are optional, for each parameter there is a boolean to
186 * use to signify its presence or absence.
187 */
188 struct RfcommCfgInfo {
189 bool init_credit_present;
190 uint16_t init_credit;
191 bool rx_mtu_present;
192 uint16_t rx_mtu;
193 btsock_data_path_t data_path{BTSOCK_DATA_PATH_NO_OFFLOAD};
194 };
195
196 namespace std {
197 template <>
198 struct formatter<tPORT_RESULT> : enum_formatter<tPORT_RESULT> {};
199 } // namespace std
200
201 typedef void(tPORT_MGMT_CALLBACK)(const tPORT_RESULT code, uint16_t port_handle);
202
203 /*****************************************************************************
204 * External Function Declarations
205 ****************************************************************************/
206
207 /*******************************************************************************
208 *
209 * Function RFCOMM_CreateConnectionWithSecurity
210 *
211 * Description RFCOMM_CreateConnectionWithSecurity is used from the application to
212 * establish a serial port connection to the peer device,
213 * or allow RFCOMM to accept a connection from the peer
214 * application.
215 *
216 * Parameters: scn - Service Channel Number as registered with
217 * the SDP (server) or obtained using SDP from
218 * the peer device (client).
219 * is_server - true if requesting application is a server
220 * mtu - Maximum frame size the application can accept
221 * bd_addr - address of the peer (client)
222 * mask - specifies events to be enabled. A value
223 * of zero disables all events.
224 * p_handle - OUT pointer to the handle.
225 * p_mgmt_callback - pointer to callback function to receive
226 * connection up/down events.
227 * sec_mask - bitmask of BTM_SEC_* values indicating the
228 * minimum security requirements for this
229 * cfg - optional configurations for the connection
230 * Notes:
231 *
232 * Server can call this function with the same scn parameter multiple times if
233 * it is ready to accept multiple simulteneous connections.
234 *
235 * DLCI for the connection is (scn * 2 + 1) if client originates connection on
236 * existing none initiator multiplexer channel. Otherwise it is (scn * 2).
237 * For the server DLCI can be changed later if client will be calling it using
238 * (scn * 2 + 1) dlci.
239 *
240 ******************************************************************************/
241 [[nodiscard]] int RFCOMM_CreateConnectionWithSecurity(uint16_t uuid, uint8_t scn, bool is_server,
242 uint16_t mtu, const RawAddress& bd_addr,
243 uint16_t* p_handle,
244 tPORT_MGMT_CALLBACK* p_mgmt_callback,
245 uint16_t sec_mask, RfcommCfgInfo cfg);
246
247 /*******************************************************************************
248 *
249 * Function RFCOMM_ControlReqFromBTSOCK
250 *
251 * Description Send control parameters to the peer.
252 * So far only for qualification use.
253 * RFCOMM layer starts the control request only when it is the
254 * client. This API allows the host to start the control
255 * request while it works as a RFCOMM server.
256 *
257 * Parameters: dlci - the DLCI to send the MSC command
258 * bd_addr - bd_addr of the peer
259 * modem_signal - [DTR/DSR | RTS/CTS | RI | DCD]
260 * break_signal - 0-3 s in steps of 200 ms
261 * discard_buffers - 0 for do not discard, 1 for discard
262 * break_signal_seq - ASAP or in sequence
263 * fc - true when the device is unable to accept
264 * frames
265 *
266 ******************************************************************************/
267 [[nodiscard]] int RFCOMM_ControlReqFromBTSOCK(uint8_t dlci, const RawAddress& bd_addr,
268 uint8_t modem_signal, uint8_t break_signal,
269 uint8_t discard_buffers, uint8_t break_signal_seq,
270 bool fc);
271
272 /*******************************************************************************
273 *
274 * Function RFCOMM_RemoveConnection
275 *
276 * Description This function is called to close the specified connection.
277 *
278 * Parameters: handle - Handle of the port returned in the Open
279 *
280 ******************************************************************************/
281 [[nodiscard]] int RFCOMM_RemoveConnection(uint16_t handle);
282
283 /*******************************************************************************
284 *
285 * Function RFCOMM_RemoveServer
286 *
287 * Description This function is called to close the server port.
288 *
289 * Parameters: handle - Handle returned in the RFCOMM_CreateConnection
290 *
291 ******************************************************************************/
292 [[nodiscard]] int RFCOMM_RemoveServer(uint16_t handle);
293
294 /*******************************************************************************
295 *
296 * Function PORT_SetEventMaskAndCallback
297 *
298 * Description Set event callback the specified connection.
299 *
300 * Parameters: handle - Handle of the port returned in the Open
301 * mask - specifies events to be enabled. A value
302 * of zero disables all events.
303 * p_callback - address of the callback function which should
304 * be called from the RFCOMM when an event
305 * specified in the mask occurs.
306 *
307 ******************************************************************************/
308 [[nodiscard]] int PORT_SetEventMaskAndCallback(uint16_t port_handle, uint32_t mask,
309 tPORT_CALLBACK* p_port_cb);
310
311 /*******************************************************************************
312 *
313 * Function PORT_ClearKeepHandleFlag
314 *
315 * Description Called to clear the keep handle flag, which will cause
316 * not to keep the port handle open when closed
317 *
318 * Parameters: handle - Handle returned in the RFCOMM_CreateConnection
319 *
320 ******************************************************************************/
321 [[nodiscard]] int PORT_ClearKeepHandleFlag(uint16_t port_handle);
322
323 [[nodiscard]] int PORT_SetDataCOCallback(uint16_t port_handle, tPORT_DATA_CO_CALLBACK* p_port_cb);
324 /*******************************************************************************
325 *
326 * Function PORT_CheckConnection
327 *
328 * Description This function returns PORT_SUCCESS if connection referenced
329 * by handle is up and running
330 *
331 * Parameters: handle - Handle of the port returned in the Open
332 * bd_addr - OUT bd_addr of the peer
333 * p_lcid - OUT L2CAP's LCID
334 *
335 ******************************************************************************/
336 [[nodiscard]] int PORT_CheckConnection(uint16_t handle, RawAddress* bd_addr, uint16_t* p_lcid);
337
338 /*******************************************************************************
339 *
340 * Function PORT_IsCollisionDetected
341 *
342 * Description This function returns true if there is already an incoming
343 * RFCOMM connection in progress for this device
344 *
345 * Parameters: true if any connection opening is found
346 * bd_addr - bd_addr of the peer
347 *
348 ******************************************************************************/
349 [[nodiscard]] bool PORT_IsCollisionDetected(RawAddress bd_addr);
350
351 /*******************************************************************************
352 *
353 * Function PORT_SetAppUid
354 *
355 * Description This function sets app_uid in port structure
356 *
357 * Parameters: handle - Handle returned in the RFCOMM_CreateConnection
358 * app_uid - Uid of app that requested the socket
359 *
360 ******************************************************************************/
361 [[nodiscard]] int PORT_SetAppUid(uint16_t handle, uint32_t app_uid);
362
363 /*******************************************************************************
364 *
365 * Function PORT_SetSdpDuration
366 *
367 * Description This function saves calculated sdp duration (in
368 * milliseconds) to port structure
369 *
370 * Parameters: handle - Handle returned in RFCOMM_CreateConnection
371 * sdp_duration_ms - Time spent doing sdp
372 *
373 ******************************************************************************/
374 [[nodiscard]] int PORT_SetSdpDuration(uint16_t handle, uint64_t sdp_duration_ms);
375
376 /*******************************************************************************
377 *
378 * Function PORT_SetState
379 *
380 * Description This function configures connection according to the
381 * specifications in the PortSettings structure.
382 *
383 * Parameters: handle - Handle returned in the RFCOMM_CreateConnection
384 * p_settings - Pointer to a PortSettings structure containing
385 * configuration information for the connection.
386 *
387 ******************************************************************************/
388 [[nodiscard]] int PORT_SetSettings(uint16_t handle, PortSettings* p_settings);
389
390 /*******************************************************************************
391 *
392 * Function PORT_GetSettings
393 *
394 * Description This function is called to fill PortSettings structure
395 * with the current control settings for the port
396 *
397 * Parameters: handle - Handle returned in the RFCOMM_CreateConnection
398 * p_settings - Pointer to a PortSettings structure in which
399 * configuration information is returned.
400 *
401 ******************************************************************************/
402 [[nodiscard]] int PORT_GetSettings(uint16_t handle, PortSettings* p_settings);
403
404 /*******************************************************************************
405 *
406 * Function PORT_FlowControl_MaxCredit
407 *
408 * Description This function directs a specified connection to pass
409 * flow control message to the peer device. Enable flag passed
410 * shows if port can accept more data. It also sends max credit
411 * when data flow enabled
412 *
413 * Parameters: handle - Handle returned in the RFCOMM_CreateConnection
414 * enable - enables data flow
415 *
416 ******************************************************************************/
417 [[nodiscard]] int PORT_FlowControl_MaxCredit(uint16_t handle, bool enable);
418
419 #define PORT_DTRDSR_ON 0x01
420 #define PORT_CTSRTS_ON 0x02
421 #define PORT_RING_ON 0x04
422 #define PORT_DCD_ON 0x08
423
424 /*
425 * Define default initial local modem signals state after connection established
426 */
427 #define PORT_OBEX_DEFAULT_SIGNAL_STATE (PORT_DTRDSR_ON | PORT_CTSRTS_ON | PORT_DCD_ON)
428 #define PORT_SPP_DEFAULT_SIGNAL_STATE (PORT_DTRDSR_ON | PORT_CTSRTS_ON | PORT_DCD_ON)
429 #define PORT_PPP_DEFAULT_SIGNAL_STATE (PORT_DTRDSR_ON | PORT_CTSRTS_ON | PORT_DCD_ON)
430 #define PORT_DUN_DEFAULT_SIGNAL_STATE (PORT_DTRDSR_ON | PORT_CTSRTS_ON)
431
432 #define PORT_ERR_BREAK 0x01 /* Break condition occurred on the peer device */
433 #define PORT_ERR_OVERRUN 0x02 /* Overrun is reported by peer device */
434 #define PORT_ERR_FRAME 0x04 /* Framing error reported by peer device */
435 #define PORT_ERR_RXOVER 0x08 /* Input queue overflow occurred */
436 #define PORT_ERR_TXFULL 0x10 /* Output queue overflow occurred */
437
438 /*******************************************************************************
439 *
440 * Function PORT_ReadData
441 *
442 * Description Normally application will call this function after receiving
443 * PORT_EVT_RXCHAR event.
444 *
445 * Parameters: handle - Handle returned in the RFCOMM_CreateConnection
446 * callback.
447 * p_data - Data area
448 * max_len - Byte count requested
449 * p_len - Byte count received
450 *
451 ******************************************************************************/
452 [[nodiscard]] int PORT_ReadData(uint16_t handle, char* p_data, uint16_t max_len, uint16_t* p_len);
453
454 /*******************************************************************************
455 *
456 * Function PORT_WriteData
457 *
458 * Description This function is called from the legacy application to
459 * send data.
460 *
461 * Parameters: handle - Handle returned in the RFCOMM_CreateConnection
462 * p_data - Data area
463 * max_len - Byte count to write
464 * p_len - Bytes written
465 *
466 ******************************************************************************/
467 [[nodiscard]] int PORT_WriteData(uint16_t handle, const char* p_data, uint16_t max_len,
468 uint16_t* p_len);
469
470 /*******************************************************************************
471 *
472 * Function PORT_WriteDataCO
473 *
474 * Description Normally not GKI aware application will call this function
475 * to send data to the port by callout functions.
476 *
477 * Parameters: handle - Handle returned in the RFCOMM_CreateConnection
478 *
479 ******************************************************************************/
480 [[nodiscard]] int PORT_WriteDataCO(uint16_t handle, int* p_len);
481
482 /*******************************************************************************
483 *
484 * Function RFCOMM_Init
485 *
486 * Description This function is called to initialize RFCOMM layer
487 *
488 ******************************************************************************/
489 void RFCOMM_Init(void);
490
491 /*******************************************************************************
492 *
493 * Function PORT_GetResultString
494 *
495 * Description This function returns the human-readable string for a given
496 * result code.
497 *
498 * Returns a pointer to the human-readable string for the given
499 * result. Note that the string returned must not be freed.
500 *
501 ******************************************************************************/
502 [[nodiscard]] const char* PORT_GetResultString(const uint8_t result_code);
503
504 /*******************************************************************************
505 *
506 * Function PORT_GetSecurityMask
507 *
508 * Description This function returns the security bitmask for a port.
509 *
510 * Returns the security bitmask.
511 *
512 ******************************************************************************/
513 [[nodiscard]] int PORT_GetSecurityMask(uint16_t handle, uint16_t* sec_mask);
514
515 /*******************************************************************************
516 *
517 * Function PORT_GetChannelInfo
518 *
519 * Description This function is called to get RFCOMM channel information
520 * by the handle of the port. All OUT parameters must NOT be nullptr.
521 *
522 * Parameters: handle - Handle of the port returned in the Open
523 * local_mtu - OUT local L2CAP MTU
524 * remote_mtu - OUT remote L2CAP MTU
525 * local_credit - OUT local RFCOMM credit
526 * remote_credit - OUT remote RFCOMM credit
527 * local_cid - OUT local L2CAP CID
528 * remote_cid - OUT remote L2CAP CID
529 * dlci - OUT dlci
530 * max_frame_size- OUT max frame size for RFCOMM
531 * acl_handle - OUT ACL handle
532 * mux_initiator - OUT is initiator of the RFCOMM multiplexer control channel
533 *
534 ******************************************************************************/
535 [[nodiscard]] int PORT_GetChannelInfo(uint16_t handle, uint16_t* local_mtu, uint16_t* remote_mtu,
536 uint16_t* local_credit, uint16_t* remote_credit,
537 uint16_t* local_cid, uint16_t* remote_cid, uint16_t* dlci,
538 uint16_t* max_frame_size, uint16_t* acl_handle,
539 bool* mux_initiator);
540
541 #endif /* PORT_API_H */
542