Home | History | Annotate | Download | only in include
      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 */
     62 enum
     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 };
     86 typedef 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 */
     97 typedef 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 */
    106 typedef 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 */
    120 typedef 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 */
    140 typedef 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 */
    153 typedef 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 */
    169 typedef 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 */
    189 typedef 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 */
    201 typedef 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
    221 extern "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 *******************************************************************************/
    239 PAN_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 *******************************************************************************/
    254 PAN_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 *******************************************************************************/
    280 PAN_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 *******************************************************************************/
    309 PAN_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 *******************************************************************************/
    324 PAN_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 *******************************************************************************/
    349 PAN_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 *******************************************************************************/
    379 PAN_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 *******************************************************************************/
    402 PAN_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 *******************************************************************************/
    425 PAN_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 *******************************************************************************/
    440 PAN_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 *******************************************************************************/
    453 PAN_API extern void PAN_Init (void);
    454 
    455 #ifdef __cplusplus
    456 }
    457 #endif
    458 
    459 #endif  /* PAN_API_H */
    460