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