1/******************************************************************************
2 *
3 *  Copyright (C) 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 */
60enum {
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};
89typedef 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*/
99typedef void(tPAN_CONN_STATE_CB)(uint16_t handle, BD_ADDR 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*/
108typedef void(tPAN_BRIDGE_REQ_CB)(BD_ADDR 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*/
121typedef void(tPAN_DATA_IND_CB)(uint16_t handle, BD_ADDR src, BD_ADDR dst,
122                               uint16_t protocol, uint8_t* p_data, uint16_t len,
123                               bool ext, bool forward);
124
125/* Data buffer received indication callback prototype. Parameters are
126 *              Source BD/Ethernet Address
127 *              Dest BD/Ethernet address
128 *              Protocol
129 *              pointer to the data buffer
130 *              ext is flag to indicate whether it has aby extension headers
131 *              Flag used to indicate to forward on LAN
132 *                      false - Use it for internal stack
133 *                      true  - Send it across the ethernet as well
134*/
135typedef void(tPAN_DATA_BUF_IND_CB)(uint16_t handle, BD_ADDR src, BD_ADDR dst,
136                                   uint16_t protocol, BT_HDR* p_buf, bool ext,
137                                   bool forward);
138
139/* Flow control callback for TX data. Parameters are
140 *              Handle to the connection
141 *              Event  flow status
142*/
143typedef void(tPAN_TX_DATA_FLOW_CB)(uint16_t handle, tPAN_RESULT event);
144
145/* Filters received indication callback prototype. Parameters are
146 *              Handle to the connection
147 *              true if the cb is called for indication
148 *              Ignore this if it is indication, otherwise it is the result
149 *                      for the filter set operation performed by the local
150 *                      device
151 *              Number of protocol filters present
152 *              Pointer to the filters start. Filters are present in pairs
153 *                      of start of the range and end of the range.
154 *                      They will be present in big endian order. First
155 *                      two bytes will be starting of the first range and
156 *                      next two bytes will be ending of the range.
157*/
158typedef void(tPAN_FILTER_IND_CB)(uint16_t handle, bool indication,
159                                 tBNEP_RESULT result, uint16_t num_filters,
160                                 uint8_t* p_filters);
161
162/* Multicast Filters received indication callback prototype. Parameters are
163 *              Handle to the connection
164 *              true if the cb is called for indication
165 *              Ignore this if it is indication, otherwise it is the result
166 *                      for the filter set operation performed by the local
167 *                      device
168 *              Number of multicast filters present
169 *              Pointer to the filters start. Filters are present in pairs
170 *                      of start of the range and end of the range.
171 *                      First six bytes will be starting of the first range and
172 *                      next six bytes will be ending of the range.
173*/
174typedef void(tPAN_MFILTER_IND_CB)(uint16_t handle, bool indication,
175                                  tBNEP_RESULT result, uint16_t num_mfilters,
176                                  uint8_t* p_mfilters);
177
178/* This structure is used to register with PAN profile
179 * It is passed as a parameter to PAN_Register call.
180*/
181typedef struct {
182  tPAN_CONN_STATE_CB* pan_conn_state_cb; /* Connection state callback */
183  tPAN_BRIDGE_REQ_CB* pan_bridge_req_cb; /* Bridge request callback */
184  tPAN_DATA_IND_CB* pan_data_ind_cb;     /* Data indication callback */
185  tPAN_DATA_BUF_IND_CB*
186      pan_data_buf_ind_cb; /* Data buffer indication callback */
187  tPAN_FILTER_IND_CB*
188      pan_pfilt_ind_cb; /* protocol filter indication callback */
189  tPAN_MFILTER_IND_CB*
190      pan_mfilt_ind_cb; /* multicast filter indication callback */
191  tPAN_TX_DATA_FLOW_CB* pan_tx_data_flow_cb; /* data flow callback */
192  char* user_service_name;                   /* Service name for PANU role */
193  char* gn_service_name;                     /* Service name for GN role */
194  char* nap_service_name;                    /* Service name for NAP role */
195
196} tPAN_REGISTER;
197
198/*****************************************************************************
199 *  External Function Declarations
200 ****************************************************************************/
201
202/*******************************************************************************
203 *
204 * Function         PAN_Register
205 *
206 * Description      This function is called by the application to register
207 *                  its callbacks with PAN profile. The application then
208 *                  should set the PAN role explicitly.
209 *
210 * Parameters:      p_register - contains all callback function pointers
211 *
212 *
213 * Returns          none
214 *
215 ******************************************************************************/
216extern void PAN_Register(tPAN_REGISTER* p_register);
217
218/*******************************************************************************
219 *
220 * Function         PAN_Deregister
221 *
222 * Description      This function is called by the application to de-register
223 *                  its callbacks with PAN profile. This will make the PAN to
224 *                  become inactive. This will deregister PAN services from SDP
225 *                  and close all active connections
226 *
227 * Returns          none
228 *
229 ******************************************************************************/
230extern void PAN_Deregister(void);
231
232/*******************************************************************************
233 *
234 * Function         PAN_SetRole
235 *
236 * Description      This function is called by the application to set the PAN
237 *                  profile role. This should be called after PAN_Register.
238 *                  This can be called any time to change the PAN role
239 *
240 * Parameters:      role        - is bit map of roles to be active
241 *                                      PAN_ROLE_CLIENT is for PANU role
242 *                                      PAN_ROLE_GN_SERVER is for GN role
243 *                                      PAN_ROLE_NAP_SERVER is for NAP role
244 *                  sec_mask    - Security mask for different roles
245 *                                      It is array of uint8_t. The bytes
246 *                                      represent the security for roles PANU,
247 *                                      GN and NAP in order
248 *
249 *                  p_user_name - Service name for PANU role
250 *                  p_gn_name   - Service name for GN role
251 *                  p_nap_name  - Service name for NAP role
252 *                                  Can be NULL if user wants it to be default
253 *
254 * Returns          PAN_SUCCESS     - if the role is set successfully
255 *                  PAN_FAILURE     - if the role is not valid
256 *
257 ******************************************************************************/
258extern tPAN_RESULT PAN_SetRole(uint8_t role, uint8_t* sec_mask,
259                               const char* p_user_name, const char* p_gn_name,
260                               const char* p_nap_name);
261
262/*******************************************************************************
263 *
264 * Function         PAN_Connect
265 *
266 * Description      This function is called by the application to initiate a
267 *                  connection to the remote device
268 *
269 * Parameters:      rem_bda     - BD Addr of the remote device
270 *                  src_role    - Role of the local device for the connection
271 *                  dst_role    - Role of the remote device for the connection
272 *                                      PAN_ROLE_CLIENT is for PANU role
273 *                                      PAN_ROLE_GN_SERVER is for GN role
274 *                                      PAN_ROLE_NAP_SERVER is for NAP role
275 *                  *handle     - Pointer for returning Handle to the connection
276 *
277 * Returns          PAN_SUCCESS - if the connection is initiated successfully
278 *                  PAN_NO_RESOURCES - resources are not sufficent
279 *                  PAN_FAILURE      - if the connection cannot be initiated
280 *                                     this can be because of the combination of
281 *                                     src and dst roles may not be valid or
282 *                                     allowed at that point of time
283 *
284 ******************************************************************************/
285extern tPAN_RESULT PAN_Connect(BD_ADDR rem_bda, uint8_t src_role,
286                               uint8_t dst_role, uint16_t* handle);
287
288/*******************************************************************************
289 *
290 * Function         PAN_Disconnect
291 *
292 * Description      This is used to disconnect the connection
293 *
294 * Parameters:      handle           - handle for the connection
295 *
296 * Returns          PAN_SUCCESS      - if the connection is closed successfully
297 *                  PAN_FAILURE      - if the connection is not found or
298 *                                           there is an error in disconnecting
299 *
300 ******************************************************************************/
301extern tPAN_RESULT PAN_Disconnect(uint16_t handle);
302
303/*******************************************************************************
304 *
305 * Function         PAN_Write
306 *
307 * Description      This sends data over the PAN connections. If this is called
308 *                  on GN or NAP side and the packet is multicast or broadcast
309 *                  it will be sent on all the links. Otherwise the correct link
310 *                  is found based on the destination address and forwarded on
311 *                  it. If the return value is not PAN_SUCCESS the application
312 *                  should take care of releasing the message buffer
313 *
314 * Parameters:      dst      - MAC or BD Addr of the destination device
315 *                  src      - MAC or BD Addr of the source who sent this packet
316 *                  protocol - protocol of the ethernet packet like IP or ARP
317 *                  p_data   - pointer to the data
318 *                  len      - length of the data
319 *                  ext      - to indicate that extension headers present
320 *
321 * Returns          PAN_SUCCESS       - if the data is sent successfully
322 *                  PAN_FAILURE       - if the connection is not found or
323 *                                           there is an error in sending data
324 *
325 ******************************************************************************/
326extern tPAN_RESULT PAN_Write(uint16_t handle, BD_ADDR dst, BD_ADDR src,
327                             uint16_t protocol, uint8_t* p_data, uint16_t len,
328                             bool ext);
329
330/*******************************************************************************
331 *
332 * Function         PAN_WriteBuf
333 *
334 * Description      This sends data over the PAN connections. If this is called
335 *                  on GN or NAP side and the packet is multicast or broadcast
336 *                  it will be sent on all the links. Otherwise the correct link
337 *                  is found based on the destination address and forwarded on
338 *                  it. If the return value is not PAN_SUCCESS the application
339 *                  should take care of releasing the message buffer
340 *
341 * Parameters:      dst      - MAC or BD Addr of the destination device
342 *                  src      - MAC or BD Addr of the source who sent this packet
343 *                  protocol - protocol of the ethernet packet like IP or ARP
344 *                  p_buf    - pointer to the data buffer
345 *                  ext      - to indicate that extension headers present
346 *
347 * Returns          PAN_SUCCESS       - if the data is sent successfully
348 *                  PAN_FAILURE       - if the connection is not found or
349 *                                           there is an error in sending data
350 *
351 ******************************************************************************/
352extern tPAN_RESULT PAN_WriteBuf(uint16_t handle, BD_ADDR dst, BD_ADDR src,
353                                uint16_t protocol, BT_HDR* p_buf, bool ext);
354
355/*******************************************************************************
356 *
357 * Function         PAN_SetProtocolFilters
358 *
359 * Description      This function is used to set protocol filters on the peer
360 *
361 * Parameters:      handle      - handle for the connection
362 *                  num_filters - number of protocol filter ranges
363 *                  start       - array of starting protocol numbers
364 *                  end         - array of ending protocol numbers
365 *
366 *
367 * Returns          PAN_SUCCESS     if protocol filters are set successfully
368 *                  PAN_FAILURE     if connection not found or error in setting
369 *
370 ******************************************************************************/
371extern tPAN_RESULT PAN_SetProtocolFilters(uint16_t handle, uint16_t num_filters,
372                                          uint16_t* p_start_array,
373                                          uint16_t* p_end_array);
374
375/*******************************************************************************
376 *
377 * Function         PAN_SetMulticastFilters
378 *
379 * Description      This function is used to set multicast filters on the peer
380 *
381 * Parameters:      handle      - handle for the connection
382 *                  num_filters - number of multicast filter ranges
383 *                  p_start_array - Pointer to sequence of beginings of all
384 *                                         multicast address ranges
385 *                  p_end_array   - Pointer to sequence of ends of all
386 *                                         multicast address ranges
387 *
388 *
389 * Returns          PAN_SUCCESS     if multicast filters are set successfully
390 *                  PAN_FAILURE     if connection not found or error in setting
391 *
392 ******************************************************************************/
393extern tBNEP_RESULT PAN_SetMulticastFilters(uint16_t handle,
394                                            uint16_t num_mcast_filters,
395                                            uint8_t* p_start_array,
396                                            uint8_t* p_end_array);
397
398/*******************************************************************************
399 *
400 * Function         PAN_SetTraceLevel
401 *
402 * Description      This function sets the trace level for PAN. If called with
403 *                  a value of 0xFF, it simply reads the current trace level.
404 *
405 * Returns          the new (current) trace level
406 *
407 ******************************************************************************/
408extern uint8_t PAN_SetTraceLevel(uint8_t new_level);
409
410/*******************************************************************************
411 *
412 * Function         PAN_Init
413 *
414 * Description      This function initializes the PAN unit. It should be called
415 *                  before accessing any other APIs to initialize the control
416 *                  block.
417 *
418 * Returns          void
419 *
420 ******************************************************************************/
421extern void PAN_Init(void);
422
423#endif /* PAN_API_H */
424