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