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