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