pan_api.h revision d19e0785e662e640191a075eda07acce61c2aeda 
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#ifdef __cplusplus
30extern "C" {
31#endif
32
33/*****************************************************************************
34**  Constants
35*****************************************************************************/
36
37/* Define the minimum offset needed in a GKI buffer for
38** sending PAN packets. Note, we are currently not sending
39** extension headers, but may in the future, so allow
40** space for them
41*/
42#define PAN_MINIMUM_OFFSET          BNEP_MINIMUM_OFFSET
43
44
45/*
46** The handle is passed from BNEP to PAN. The same handle is used
47** between PAN and application as well
48*/
49#define PAN_INVALID_HANDLE          BNEP_INVALID_HANDLE
50
51/* Bit map for PAN roles */
52#define PAN_ROLE_CLIENT         0x01     /* PANU role */
53#define PAN_ROLE_GN_SERVER      0x02     /* GN role */
54#define PAN_ROLE_NAP_SERVER     0x04     /* NAP role */
55
56/* Bitmap to indicate the usage of the Data */
57#define PAN_DATA_TO_HOST        0x01
58#define PAN_DATA_TO_LAN         0x02
59
60
61/*****************************************************************************
62**  Type Definitions
63*****************************************************************************/
64
65/* Define the result codes from PAN */
66enum
67{
68    PAN_SUCCESS,                                                /* Success                           */
69    PAN_DISCONNECTED            = BNEP_CONN_DISCONNECTED,       /* Connection terminated   */
70    PAN_CONN_FAILED             = BNEP_CONN_FAILED,             /* Connection failed                 */
71    PAN_NO_RESOURCES            = BNEP_NO_RESOURCES,            /* No resources                      */
72    PAN_MTU_EXCEDED             = BNEP_MTU_EXCEDED,             /* Attempt to write long data        */
73    PAN_INVALID_OFFSET          = BNEP_INVALID_OFFSET,          /* Insufficient offset in GKI buffer */
74    PAN_CONN_FAILED_CFG         = BNEP_CONN_FAILED_CFG,         /* Connection failed cos of config   */
75    PAN_INVALID_SRC_ROLE        = BNEP_CONN_FAILED_SRC_UUID,    /* Connection failed wrong source UUID   */
76    PAN_INVALID_DST_ROLE        = BNEP_CONN_FAILED_DST_UUID,    /* Connection failed wrong destination UUID   */
77    PAN_CONN_FAILED_UUID_SIZE   = BNEP_CONN_FAILED_UUID_SIZE,   /* Connection failed wrong size UUID   */
78    PAN_Q_SIZE_EXCEEDED         = BNEP_Q_SIZE_EXCEEDED,         /* Too many buffers to dest          */
79    PAN_TOO_MANY_FILTERS        = BNEP_TOO_MANY_FILTERS,        /* Too many local filters specified  */
80    PAN_SET_FILTER_FAIL         = BNEP_SET_FILTER_FAIL,         /* Set Filter failed  */
81    PAN_WRONG_HANDLE            = BNEP_WRONG_HANDLE,            /* Wrong handle for the connection  */
82    PAN_WRONG_STATE             = BNEP_WRONG_STATE,             /* Connection is in wrong state */
83    PAN_SECURITY_FAIL           = BNEP_SECURITY_FAIL,           /* Failed because of security */
84    PAN_IGNORE_CMD              = BNEP_IGNORE_CMD,              /* To ignore the rcvd command */
85    PAN_TX_FLOW_ON              = BNEP_TX_FLOW_ON,              /* tx data flow enabled */
86    PAN_TX_FLOW_OFF	            = BNEP_TX_FLOW_OFF,             /* tx data flow disabled */
87    PAN_FAILURE                                                 /* Failure                      */
88
89};
90typedef uint8_t tPAN_RESULT;
91
92
93/*****************************************************************
94**       Callback Function Prototypes
95*****************************************************************/
96
97/* This is call back function used to report connection status
98**      to the application. The second parameter true means
99**      to create the bridge and false means to remove it.
100*/
101typedef void (tPAN_CONN_STATE_CB) (uint16_t handle, BD_ADDR bd_addr, tPAN_RESULT state, bool    is_role_change,
102                                        uint8_t src_role, uint8_t dst_role);
103
104
105/* This is call back function used to create bridge for the
106**      Connected device. The parameter "state" indicates
107**      whether to create the bridge or remove it. true means
108**      to create the bridge and false means to remove it.
109*/
110typedef void (tPAN_BRIDGE_REQ_CB) (BD_ADDR bd_addr, bool    state);
111
112
113/* Data received indication callback prototype. Parameters are
114**              Source BD/Ethernet Address
115**              Dest BD/Ethernet address
116**              Protocol
117**              Address of buffer (or data if non-GKI)
118**              Length of data (non-GKI)
119**              ext is flag to indicate whether it has aby extension headers
120**              Flag used to indicate to forward on LAN
121**                      false - Use it for internal stack
122**                      true  - Send it across the ethernet as well
123*/
124typedef void (tPAN_DATA_IND_CB) (uint16_t handle,
125                                 BD_ADDR src,
126                                 BD_ADDR dst,
127                                 uint16_t protocol,
128                                 uint8_t *p_data,
129                                 uint16_t len,
130                                 bool    ext,
131                                 bool    forward);
132
133
134/* Data buffer received indication callback prototype. Parameters are
135**              Source BD/Ethernet Address
136**              Dest BD/Ethernet address
137**              Protocol
138**              pointer to the data buffer
139**              ext is flag to indicate whether it has aby extension headers
140**              Flag used to indicate to forward on LAN
141**                      false - Use it for internal stack
142**                      true  - Send it across the ethernet as well
143*/
144typedef void (tPAN_DATA_BUF_IND_CB) (uint16_t handle,
145                                     BD_ADDR src,
146                                     BD_ADDR dst,
147                                     uint16_t protocol,
148                                     BT_HDR *p_buf,
149                                     bool    ext,
150                                     bool    forward);
151
152
153/* Flow control callback for TX data. Parameters are
154**              Handle to the connection
155**              Event  flow status
156*/
157typedef void (tPAN_TX_DATA_FLOW_CB) (uint16_t handle,
158                                     tPAN_RESULT  event);
159
160/* Filters received indication callback prototype. Parameters are
161**              Handle to the connection
162**              true if the cb is called for indication
163**              Ignore this if it is indication, otherwise it is the result
164**                      for the filter set operation performed by the local
165**                      device
166**              Number of protocol filters present
167**              Pointer to the filters start. Filters are present in pairs
168**                      of start of the range and end of the range.
169**                      They will be present in big endian order. First
170**                      two bytes will be starting of the first range and
171**                      next two bytes will be ending of the range.
172*/
173typedef void (tPAN_FILTER_IND_CB) (uint16_t handle,
174                                   bool    indication,
175                                   tBNEP_RESULT result,
176                                   uint16_t num_filters,
177                                   uint8_t *p_filters);
178
179
180
181/* Multicast Filters received indication callback prototype. Parameters are
182**              Handle to the connection
183**              true if the cb is called for indication
184**              Ignore this if it is indication, otherwise it is the result
185**                      for the filter set operation performed by the local
186**                      device
187**              Number of multicast filters present
188**              Pointer to the filters start. Filters are present in pairs
189**                      of start of the range and end of the range.
190**                      First six bytes will be starting of the first range and
191**                      next six bytes will be ending of the range.
192*/
193typedef void (tPAN_MFILTER_IND_CB) (uint16_t handle,
194                                    bool    indication,
195                                    tBNEP_RESULT result,
196                                    uint16_t num_mfilters,
197                                    uint8_t *p_mfilters);
198
199
200
201
202/* This structure is used to register with PAN profile
203** It is passed as a parameter to PAN_Register call.
204*/
205typedef struct
206{
207    tPAN_CONN_STATE_CB          *pan_conn_state_cb;     /* Connection state callback */
208    tPAN_BRIDGE_REQ_CB          *pan_bridge_req_cb;     /* Bridge request callback */
209    tPAN_DATA_IND_CB            *pan_data_ind_cb;       /* Data indication callback */
210    tPAN_DATA_BUF_IND_CB        *pan_data_buf_ind_cb;   /* Data buffer indication callback */
211    tPAN_FILTER_IND_CB          *pan_pfilt_ind_cb;      /* protocol filter indication callback */
212    tPAN_MFILTER_IND_CB         *pan_mfilt_ind_cb;      /* multicast filter indication callback */
213    tPAN_TX_DATA_FLOW_CB        *pan_tx_data_flow_cb;   /* data flow callback */
214    char                        *user_service_name;     /* Service name for PANU role */
215    char                        *gn_service_name;       /* Service name for GN role */
216    char                        *nap_service_name;      /* Service name for NAP role */
217
218} tPAN_REGISTER;
219
220
221/*****************************************************************************
222**  External Function Declarations
223*****************************************************************************/
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*******************************************************************************/
239extern 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*******************************************************************************/
254extern 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_t. 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*******************************************************************************/
280extern tPAN_RESULT PAN_SetRole (uint8_t role,
281                                uint8_t *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*******************************************************************************/
309extern tPAN_RESULT PAN_Connect (BD_ADDR rem_bda, uint8_t src_role, uint8_t dst_role, uint16_t *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*******************************************************************************/
324extern tPAN_RESULT PAN_Disconnect (uint16_t 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*******************************************************************************/
349extern tPAN_RESULT PAN_Write (uint16_t handle,
350                              BD_ADDR dst,
351                              BD_ADDR src,
352                              uint16_t protocol,
353                              uint8_t *p_data,
354                              uint16_t len,
355                              bool    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*******************************************************************************/
379extern tPAN_RESULT PAN_WriteBuf (uint16_t handle,
380                                 BD_ADDR dst,
381                                 BD_ADDR src,
382                                 uint16_t protocol,
383                                 BT_HDR *p_buf,
384                                 bool    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*******************************************************************************/
402extern tPAN_RESULT PAN_SetProtocolFilters (uint16_t handle,
403                                           uint16_t num_filters,
404                                           uint16_t *p_start_array,
405                                           uint16_t *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*******************************************************************************/
425extern tBNEP_RESULT PAN_SetMulticastFilters (uint16_t handle,
426                                             uint16_t num_mcast_filters,
427                                             uint8_t *p_start_array,
428                                             uint8_t *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*******************************************************************************/
440extern uint8_t PAN_SetTraceLevel (uint8_t 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*******************************************************************************/
453extern void PAN_Init (void);
454
455#ifdef __cplusplus
456}
457#endif
458
459#endif  /* PAN_API_H */
460