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