1 /******************************************************************************
2 *
3 * Copyright 2001-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 PAN API definitions
22 *
23 ******************************************************************************/
24 #ifndef PAN_API_H
25 #define PAN_API_H
26
27 #include <bluetooth/log.h>
28
29 #include <cstdint>
30
31 #include "bnep_api.h"
32 #include "macros.h"
33 #include "stack/include/bt_hdr.h"
34 #include "types/raw_address.h"
35
36 /*****************************************************************************
37 * Constants
38 ****************************************************************************/
39
40 /* Define the minimum offset needed in a GKI buffer for
41 * sending PAN packets. Note, we are currently not sending
42 * extension headers, but may in the future, so allow
43 * space for them
44 */
45 #define PAN_MINIMUM_OFFSET BNEP_MINIMUM_OFFSET
46
47 /*
48 * The handle is passed from BNEP to PAN. The same handle is used
49 * between PAN and application as well
50 */
51 #define PAN_INVALID_HANDLE BNEP_INVALID_HANDLE
52
53 /* Bit map for PAN roles */
54 #define PAN_ROLE_CLIENT 0x01 /* PANU role */
55 #define PAN_ROLE_GROUP 0x02 /* Adhoc network group role */
56 #define PAN_ROLE_NAP_SERVER 0x04 /* NAP role */
57 typedef uint8_t tPAN_ROLE;
58
pan_role_to_text(const tPAN_ROLE & role)59 inline const std::string pan_role_to_text(const tPAN_ROLE& role) {
60 return std::format("{:c}{:c}{:c}[0x{:x}]", (role & PAN_ROLE_CLIENT) ? 'C' : '.',
61 (role & PAN_ROLE_GROUP) ? 'G' : '.', (role & PAN_ROLE_NAP_SERVER) ? 'N' : '.',
62 role);
63 }
64
65 /*****************************************************************************
66 * Type Definitions
67 ****************************************************************************/
68
69 /* Define the result codes from PAN */
70 typedef enum : uint8_t {
71 PAN_SUCCESS, /* Success */
72 PAN_DISCONNECTED = BNEP_CONN_DISCONNECTED, /* Connection terminated */
73 PAN_CONN_FAILED = BNEP_CONN_FAILED, /* Connection failed */
74 PAN_NO_RESOURCES = BNEP_NO_RESOURCES, /* No resources */
75 PAN_MTU_EXCEEDED = BNEP_MTU_EXCEEDED, /* Attempt to write long data */
76 PAN_INVALID_OFFSET = BNEP_INVALID_OFFSET, /* Insufficient offset in GKI buffer */
77 PAN_CONN_FAILED_CFG = BNEP_CONN_FAILED_CFG, /* Connection failed cos of config */
78 PAN_INVALID_SRC_ROLE = BNEP_CONN_FAILED_SRC_UUID, /* Connection failed wrong source UUID */
79 PAN_INVALID_DST_ROLE = BNEP_CONN_FAILED_DST_UUID, /* Connection failed wrong destination UUID */
80 PAN_CONN_FAILED_UUID_SIZE = BNEP_CONN_FAILED_UUID_SIZE, /* Connection failed wrong size UUID */
81 PAN_Q_SIZE_EXCEEDED = BNEP_Q_SIZE_EXCEEDED, /* Too many buffers to dest */
82 PAN_TOO_MANY_FILTERS = BNEP_TOO_MANY_FILTERS, /* Too many local filters specified */
83 PAN_SET_FILTER_FAIL = BNEP_SET_FILTER_FAIL, /* Set Filter failed */
84 PAN_WRONG_HANDLE = BNEP_WRONG_HANDLE, /* Wrong handle for the connection */
85 PAN_WRONG_STATE = BNEP_WRONG_STATE, /* Connection is in wrong state */
86 PAN_SECURITY_FAIL = BNEP_SECURITY_FAIL, /* Failed because of security */
87 PAN_IGNORE_CMD = BNEP_IGNORE_CMD, /* To ignore the rcvd command */
88 PAN_TX_FLOW_ON = BNEP_TX_FLOW_ON, /* tx data flow enabled */
89 PAN_TX_FLOW_OFF = BNEP_TX_FLOW_OFF, /* tx data flow disabled */
90 PAN_FAILURE = 19, /* Failure */
91 PAN_HOTSPOT_DISABLED = 20, /* Hotspot disabled */
92 } tPAN_RESULT;
93
pan_result_text(const tPAN_RESULT & result)94 inline const std::string pan_result_text(const tPAN_RESULT& result) {
95 switch (result) {
96 CASE_RETURN_TEXT(PAN_SUCCESS);
97 CASE_RETURN_TEXT(PAN_DISCONNECTED);
98 CASE_RETURN_TEXT(PAN_CONN_FAILED);
99 CASE_RETURN_TEXT(PAN_NO_RESOURCES);
100 CASE_RETURN_TEXT(PAN_MTU_EXCEEDED);
101 CASE_RETURN_TEXT(PAN_INVALID_OFFSET);
102 CASE_RETURN_TEXT(PAN_CONN_FAILED_CFG);
103 CASE_RETURN_TEXT(PAN_INVALID_SRC_ROLE);
104 CASE_RETURN_TEXT(PAN_INVALID_DST_ROLE);
105 CASE_RETURN_TEXT(PAN_CONN_FAILED_UUID_SIZE);
106 CASE_RETURN_TEXT(PAN_Q_SIZE_EXCEEDED);
107 CASE_RETURN_TEXT(PAN_TOO_MANY_FILTERS);
108 CASE_RETURN_TEXT(PAN_SET_FILTER_FAIL);
109 CASE_RETURN_TEXT(PAN_WRONG_HANDLE);
110 CASE_RETURN_TEXT(PAN_WRONG_STATE);
111 CASE_RETURN_TEXT(PAN_SECURITY_FAIL);
112 CASE_RETURN_TEXT(PAN_IGNORE_CMD);
113 CASE_RETURN_TEXT(PAN_TX_FLOW_ON);
114 CASE_RETURN_TEXT(PAN_TX_FLOW_OFF);
115 CASE_RETURN_TEXT(PAN_FAILURE);
116 CASE_RETURN_TEXT(PAN_HOTSPOT_DISABLED);
117 default:
118 return std::format("UNKNOWN[{}]", static_cast<uint8_t>(result));
119 }
120 }
121
122 /*****************************************************************
123 * Callback Function Prototypes
124 ****************************************************************/
125
126 /* This is call back function used to report connection status
127 * to the application. The second parameter true means
128 * to create the bridge and false means to remove it.
129 */
130 typedef void(tPAN_CONN_STATE_CB)(uint16_t handle, const RawAddress& bd_addr, tPAN_RESULT state,
131 bool is_role_change, uint8_t src_role, uint8_t dst_role);
132
133 /* This is call back function used to create bridge for the
134 * Connected device. The parameter "state" indicates
135 * whether to create the bridge or remove it. true means
136 * to create the bridge and false means to remove it.
137 */
138 typedef void(tPAN_BRIDGE_REQ_CB)(const RawAddress& bd_addr, bool state);
139
140 /* Data received indication callback prototype. Parameters are
141 * Source BD/Ethernet Address
142 * Dest BD/Ethernet address
143 * Protocol
144 * Address of buffer (or data if non-GKI)
145 * Length of data (non-GKI)
146 * ext is flag to indicate whether it has aby extension headers
147 * Flag used to indicate to forward on LAN
148 * false - Use it for internal stack
149 * true - Send it across the ethernet as well
150 */
151 typedef void(tPAN_DATA_IND_CB)(uint16_t handle, const RawAddress& src, const RawAddress& dst,
152 uint16_t protocol, uint8_t* p_data, uint16_t len, bool ext,
153 bool forward);
154
155 /* Data buffer received indication callback prototype. Parameters are
156 * Source BD/Ethernet Address
157 * Dest BD/Ethernet address
158 * Protocol
159 * pointer to the data buffer
160 * ext is flag to indicate whether it has aby extension headers
161 * Flag used to indicate to forward on LAN
162 * false - Use it for internal stack
163 * true - Send it across the ethernet as well
164 */
165 typedef void(tPAN_DATA_BUF_IND_CB)(uint16_t handle, const RawAddress& src, const RawAddress& dst,
166 uint16_t protocol, BT_HDR* p_buf, bool ext, bool forward);
167
168 /* Flow control callback for TX data. Parameters are
169 * Handle to the connection
170 * Event flow status
171 */
172 typedef void(tPAN_TX_DATA_FLOW_CB)(uint16_t handle, tPAN_RESULT event);
173
174 /* Filters received indication callback prototype. Parameters are
175 * Handle to the connection
176 * true if the cb is called for indication
177 * Ignore this if it is indication, otherwise it is the result
178 * for the filter set operation performed by the local
179 * device
180 * Number of protocol filters present
181 * Pointer to the filters start. Filters are present in pairs
182 * of start of the range and end of the range.
183 * They will be present in big endian order. First
184 * two bytes will be starting of the first range and
185 * next two bytes will be ending of the range.
186 */
187 typedef void(tPAN_FILTER_IND_CB)(uint16_t handle, bool indication, tPAN_RESULT result,
188 uint16_t num_filters, uint8_t* p_filters);
189
190 /* Multicast Filters received indication callback prototype. Parameters are
191 * Handle to the connection
192 * true if the cb is called for indication
193 * Ignore this if it is indication, otherwise it is the result
194 * for the filter set operation performed by the local
195 * device
196 * Number of multicast filters present
197 * Pointer to the filters start. Filters are present in pairs
198 * of start of the range and end of the range.
199 * First six bytes will be starting of the first range and
200 * next six bytes will be ending of the range.
201 */
202 typedef void(tPAN_MFILTER_IND_CB)(uint16_t handle, bool indication, tPAN_RESULT result,
203 uint16_t num_mfilters, uint8_t* p_mfilters);
204
205 /* This structure is used to register with PAN profile
206 * It is passed as a parameter to PAN_Register call.
207 */
208 typedef struct {
209 tPAN_CONN_STATE_CB* pan_conn_state_cb; /* Connection state callback */
210 tPAN_BRIDGE_REQ_CB* pan_bridge_req_cb; /* Bridge request callback */
211 tPAN_DATA_IND_CB* pan_data_ind_cb; /* Data indication callback */
212 tPAN_DATA_BUF_IND_CB* pan_data_buf_ind_cb; /* Data buffer indication callback */
213 tPAN_FILTER_IND_CB* pan_pfilt_ind_cb; /* protocol filter indication callback */
214 tPAN_MFILTER_IND_CB* pan_mfilt_ind_cb; /* multicast filter indication callback */
215 tPAN_TX_DATA_FLOW_CB* pan_tx_data_flow_cb; /* data flow callback */
216 } tPAN_REGISTER;
217
218 /*****************************************************************************
219 * External Function Declarations
220 ****************************************************************************/
221
222 /*******************************************************************************
223 *
224 * Function PAN_Register
225 *
226 * Description This function is called by the application to register
227 * its callbacks with PAN profile. The application then
228 * should set the PAN role explicitly.
229 *
230 * Parameters: p_register - contains all callback function pointers
231 *
232 *
233 * Returns none
234 *
235 ******************************************************************************/
236 void PAN_Register(tPAN_REGISTER* p_register);
237
238 /*******************************************************************************
239 *
240 * Function PAN_Deregister
241 *
242 * Description This function is called by the application to de-register
243 * its callbacks with PAN profile. This will make the PAN to
244 * become inactive. This will deregister PAN services from SDP
245 * and close all active connections
246 *
247 * Returns none
248 *
249 ******************************************************************************/
250 void PAN_Deregister(void);
251
252 /*******************************************************************************
253 *
254 * Function PAN_SetRole
255 *
256 * Description This function is called by the application to set the PAN
257 * profile role. This should be called after PAN_Register.
258 * This can be called any time to change the PAN role
259 *
260 * Parameters: role - is bit map of roles to be active
261 * PAN_ROLE_CLIENT is for PANU role
262 * PAN_ROLE_NAP_SERVER is for NAP role
263 * sec_mask - Security mask for different roles
264 * It is array of uint8_t. The bytes
265 * represent the security for roles PANU,
266 * GN and NAP in order
267 *
268 * p_user_name - Service name for PANU role
269 * p_nap_name - Service name for NAP role
270 * Can be NULL if user wants it to be default
271 *
272 * Returns PAN_SUCCESS - if the role is set successfully
273 * PAN_FAILURE - if the role is not valid
274 *
275 ******************************************************************************/
276 tPAN_RESULT PAN_SetRole(uint8_t role, std::string user_name, std::string nap_name);
277
278 /*******************************************************************************
279 *
280 * Function PAN_Connect
281 *
282 * Description This function is called by the application to initiate a
283 * connection to the remote device
284 *
285 * Parameters: rem_bda - BD Addr of the remote device
286 * src_role - Role of the local device for the connection
287 * dst_role - Role of the remote device for the connection
288 * PAN_ROLE_CLIENT is for PANU role
289 * PAN_ROLE_NAP_SERVER is for NAP role
290 * *handle - Pointer for returning Handle to the connection
291 *
292 * Returns PAN_SUCCESS - if the connection is initiated successfully
293 * PAN_NO_RESOURCES - resources are not sufficient
294 * PAN_FAILURE - if the connection cannot be initiated
295 * this can be because of the combination of
296 * src and dst roles may not be valid or
297 * allowed at that point of time
298 *
299 ******************************************************************************/
300 tPAN_RESULT PAN_Connect(const RawAddress& rem_bda, tPAN_ROLE src_role, tPAN_ROLE dst_role,
301 uint16_t* handle);
302
303 /*******************************************************************************
304 *
305 * Function PAN_Disconnect
306 *
307 * Description This is used to disconnect the connection
308 *
309 * Parameters: handle - handle for the connection
310 *
311 * Returns PAN_SUCCESS - if the connection is closed successfully
312 * PAN_FAILURE - if the connection is not found or
313 * there is an error in disconnecting
314 *
315 ******************************************************************************/
316 tPAN_RESULT PAN_Disconnect(uint16_t handle);
317
318 /*******************************************************************************
319 *
320 * Function PAN_Write
321 *
322 * Description This sends data over the PAN connections. If this is called
323 * on GN or NAP side and the packet is multicast or broadcast
324 * it will be sent on all the links. Otherwise the correct link
325 * is found based on the destination address and forwarded on
326 * it. If the return value is not PAN_SUCCESS the application
327 * should take care of releasing the message buffer
328 *
329 * Parameters: dst - MAC or BD Addr of the destination device
330 * src - MAC or BD Addr of the source who sent this packet
331 * protocol - protocol of the ethernet packet like IP or ARP
332 * p_data - pointer to the data
333 * len - length of the data
334 * ext - to indicate that extension headers present
335 *
336 * Returns PAN_SUCCESS - if the data is sent successfully
337 * PAN_FAILURE - if the connection is not found or
338 * there is an error in sending data
339 *
340 ******************************************************************************/
341 tPAN_RESULT PAN_Write(uint16_t handle, const RawAddress& dst, const RawAddress& src,
342 uint16_t protocol, uint8_t* p_data, uint16_t len, bool ext);
343
344 /*******************************************************************************
345 *
346 * Function PAN_WriteBuf
347 *
348 * Description This sends data over the PAN connections. If this is called
349 * on GN or NAP side and the packet is multicast or broadcast
350 * it will be sent on all the links. Otherwise the correct link
351 * is found based on the destination address and forwarded on
352 * it. If the return value is not PAN_SUCCESS the application
353 * should take care of releasing the message buffer
354 *
355 * Parameters: dst - MAC or BD Addr of the destination device
356 * src - MAC or BD Addr of the source who sent this packet
357 * protocol - protocol of the ethernet packet like IP or ARP
358 * p_buf - pointer to the data buffer
359 * ext - to indicate that extension headers present
360 *
361 * Returns PAN_SUCCESS - if the data is sent successfully
362 * PAN_FAILURE - if the connection is not found or
363 * there is an error in sending data
364 *
365 ******************************************************************************/
366 tPAN_RESULT PAN_WriteBuf(uint16_t handle, const RawAddress& dst, const RawAddress& src,
367 uint16_t protocol, BT_HDR* p_buf, bool ext);
368
369 /*******************************************************************************
370 *
371 * Function PAN_SetProtocolFilters
372 *
373 * Description This function is used to set protocol filters on the peer
374 *
375 * Parameters: handle - handle for the connection
376 * num_filters - number of protocol filter ranges
377 * start - array of starting protocol numbers
378 * end - array of ending protocol numbers
379 *
380 *
381 * Returns PAN_SUCCESS if protocol filters are set successfully
382 * PAN_FAILURE if connection not found or error in setting
383 *
384 ******************************************************************************/
385 tPAN_RESULT PAN_SetProtocolFilters(uint16_t handle, uint16_t num_filters, uint16_t* p_start_array,
386 uint16_t* p_end_array);
387
388 /*******************************************************************************
389 *
390 * Function PAN_SetMulticastFilters
391 *
392 * Description This function is used to set multicast filters on the peer
393 *
394 * Parameters: handle - handle for the connection
395 * num_filters - number of multicast filter ranges
396 * p_start_array - Pointer to sequence of beginings of all
397 * multicast address ranges
398 * p_end_array - Pointer to sequence of ends of all
399 * multicast address ranges
400 *
401 *
402 * Returns PAN_SUCCESS if multicast filters are set successfully
403 * PAN_FAILURE if connection not found or error in setting
404 *
405 ******************************************************************************/
406 tPAN_RESULT PAN_SetMulticastFilters(uint16_t handle, uint16_t num_mcast_filters,
407 uint8_t* p_start_array, uint8_t* p_end_array);
408
409 /*******************************************************************************
410 *
411 * Function PAN_Init
412 *
413 * Description This function initializes the PAN unit. It should be called
414 * before accessing any other APIs to initialize the control
415 * block.
416 *
417 * Returns void
418 *
419 ******************************************************************************/
420 void PAN_Init(void);
421
422 void PAN_Dumpsys(int fd);
423
424 namespace std {
425 template <>
426 struct formatter<tPAN_RESULT> : enum_formatter<tPAN_RESULT> {};
427 } // namespace std
428
429 #endif /* PAN_API_H */
430