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