1 /****************************************************************************** 2 * 3 * Copyright 2001-2012 Broadcom Corporation 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at: 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 ******************************************************************************/ 18 19 /****************************************************************************** 20 * 21 * this file contains the PAN API definitions 22 * 23 ******************************************************************************/ 24 #ifndef PAN_API_H 25 #define PAN_API_H 26 27 #include "bnep_api.h" 28 29 /***************************************************************************** 30 * Constants 31 ****************************************************************************/ 32 33 /* Define the minimum offset needed in a GKI buffer for 34 * sending PAN packets. Note, we are currently not sending 35 * extension headers, but may in the future, so allow 36 * space for them 37 */ 38 #define PAN_MINIMUM_OFFSET BNEP_MINIMUM_OFFSET 39 40 /* 41 * The handle is passed from BNEP to PAN. The same handle is used 42 * between PAN and application as well 43 */ 44 #define PAN_INVALID_HANDLE BNEP_INVALID_HANDLE 45 46 /* Bit map for PAN roles */ 47 #define PAN_ROLE_CLIENT 0x01 /* PANU role */ 48 #define PAN_ROLE_NAP_SERVER 0x04 /* NAP role */ 49 50 /* Bitmap to indicate the usage of the Data */ 51 #define PAN_DATA_TO_HOST 0x01 52 #define PAN_DATA_TO_LAN 0x02 53 54 /***************************************************************************** 55 * Type Definitions 56 ****************************************************************************/ 57 58 /* Define the result codes from PAN */ 59 enum { 60 PAN_SUCCESS, /* Success */ 61 PAN_DISCONNECTED = BNEP_CONN_DISCONNECTED, /* Connection terminated */ 62 PAN_CONN_FAILED = BNEP_CONN_FAILED, /* Connection failed */ 63 PAN_NO_RESOURCES = BNEP_NO_RESOURCES, /* No resources */ 64 PAN_MTU_EXCEDED = BNEP_MTU_EXCEDED, /* Attempt to write long data */ 65 PAN_INVALID_OFFSET = 66 BNEP_INVALID_OFFSET, /* Insufficient offset in GKI buffer */ 67 PAN_CONN_FAILED_CFG = 68 BNEP_CONN_FAILED_CFG, /* Connection failed cos of config */ 69 PAN_INVALID_SRC_ROLE = 70 BNEP_CONN_FAILED_SRC_UUID, /* Connection failed wrong source UUID */ 71 PAN_INVALID_DST_ROLE = 72 BNEP_CONN_FAILED_DST_UUID, /* Connection failed wrong destination UUID */ 73 PAN_CONN_FAILED_UUID_SIZE = 74 BNEP_CONN_FAILED_UUID_SIZE, /* Connection failed wrong size UUID */ 75 PAN_Q_SIZE_EXCEEDED = BNEP_Q_SIZE_EXCEEDED, /* Too many buffers to dest */ 76 PAN_TOO_MANY_FILTERS = 77 BNEP_TOO_MANY_FILTERS, /* Too many local filters specified */ 78 PAN_SET_FILTER_FAIL = BNEP_SET_FILTER_FAIL, /* Set Filter failed */ 79 PAN_WRONG_HANDLE = BNEP_WRONG_HANDLE, /* Wrong handle for the connection */ 80 PAN_WRONG_STATE = BNEP_WRONG_STATE, /* Connection is in wrong state */ 81 PAN_SECURITY_FAIL = BNEP_SECURITY_FAIL, /* Failed because of security */ 82 PAN_IGNORE_CMD = BNEP_IGNORE_CMD, /* To ignore the rcvd command */ 83 PAN_TX_FLOW_ON = BNEP_TX_FLOW_ON, /* tx data flow enabled */ 84 PAN_TX_FLOW_OFF = BNEP_TX_FLOW_OFF, /* tx data flow disabled */ 85 PAN_FAILURE /* Failure */ 86 87 }; 88 typedef uint8_t tPAN_RESULT; 89 90 /***************************************************************** 91 * Callback Function Prototypes 92 ****************************************************************/ 93 94 /* This is call back function used to report connection status 95 * to the application. The second parameter true means 96 * to create the bridge and false means to remove it. 97 */ 98 typedef void(tPAN_CONN_STATE_CB)(uint16_t handle, const RawAddress& bd_addr, 99 tPAN_RESULT state, bool is_role_change, 100 uint8_t src_role, uint8_t dst_role); 101 102 /* This is call back function used to create bridge for the 103 * Connected device. The parameter "state" indicates 104 * whether to create the bridge or remove it. true means 105 * to create the bridge and false means to remove it. 106 */ 107 typedef void(tPAN_BRIDGE_REQ_CB)(const RawAddress& bd_addr, bool state); 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_t handle, const RawAddress& src, 121 const RawAddress& dst, uint16_t protocol, 122 uint8_t* p_data, uint16_t len, bool ext, 123 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 */ 135 typedef void(tPAN_DATA_BUF_IND_CB)(uint16_t handle, const RawAddress& src, 136 const RawAddress& dst, uint16_t protocol, 137 BT_HDR* p_buf, bool ext, bool forward); 138 139 /* Flow control callback for TX data. Parameters are 140 * Handle to the connection 141 * Event flow status 142 */ 143 typedef 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 */ 158 typedef 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 */ 174 typedef 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 */ 181 typedef 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 ******************************************************************************/ 216 extern 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 ******************************************************************************/ 230 extern 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_NAP_SERVER is for NAP role 243 * sec_mask - Security mask for different roles 244 * It is array of uint8_t. The bytes 245 * represent the security for roles PANU, 246 * GN and NAP in order 247 * 248 * p_user_name - Service name for PANU role 249 * p_nap_name - Service name for NAP role 250 * Can be NULL if user wants it to be default 251 * 252 * Returns PAN_SUCCESS - if the role is set successfully 253 * PAN_FAILURE - if the role is not valid 254 * 255 ******************************************************************************/ 256 extern tPAN_RESULT PAN_SetRole(uint8_t role, const char* p_user_name, 257 const char* p_nap_name); 258 259 /******************************************************************************* 260 * 261 * Function PAN_Connect 262 * 263 * Description This function is called by the application to initiate a 264 * connection to the remote device 265 * 266 * Parameters: rem_bda - BD Addr of the remote device 267 * src_role - Role of the local device for the connection 268 * dst_role - Role of the remote device for the connection 269 * PAN_ROLE_CLIENT is for PANU role 270 * PAN_ROLE_NAP_SERVER is for NAP role 271 * *handle - Pointer for returning Handle to the connection 272 * 273 * Returns PAN_SUCCESS - if the connection is initiated successfully 274 * PAN_NO_RESOURCES - resources are not sufficent 275 * PAN_FAILURE - if the connection cannot be initiated 276 * this can be because of the combination of 277 * src and dst roles may not be valid or 278 * allowed at that point of time 279 * 280 ******************************************************************************/ 281 extern tPAN_RESULT PAN_Connect(const RawAddress& rem_bda, uint8_t src_role, 282 uint8_t dst_role, uint16_t* handle); 283 284 /******************************************************************************* 285 * 286 * Function PAN_Disconnect 287 * 288 * Description This is used to disconnect the connection 289 * 290 * Parameters: handle - handle for the connection 291 * 292 * Returns PAN_SUCCESS - if the connection is closed successfully 293 * PAN_FAILURE - if the connection is not found or 294 * there is an error in disconnecting 295 * 296 ******************************************************************************/ 297 extern tPAN_RESULT PAN_Disconnect(uint16_t handle); 298 299 /******************************************************************************* 300 * 301 * Function PAN_Write 302 * 303 * Description This sends data over the PAN connections. If this is called 304 * on GN or NAP side and the packet is multicast or broadcast 305 * it will be sent on all the links. Otherwise the correct link 306 * is found based on the destination address and forwarded on 307 * it. If the return value is not PAN_SUCCESS the application 308 * should take care of releasing the message buffer 309 * 310 * Parameters: dst - MAC or BD Addr of the destination device 311 * src - MAC or BD Addr of the source who sent this packet 312 * protocol - protocol of the ethernet packet like IP or ARP 313 * p_data - pointer to the data 314 * len - length of the data 315 * ext - to indicate that extension headers present 316 * 317 * Returns PAN_SUCCESS - if the data is sent successfully 318 * PAN_FAILURE - if the connection is not found or 319 * there is an error in sending data 320 * 321 ******************************************************************************/ 322 extern tPAN_RESULT PAN_Write(uint16_t handle, const RawAddress& dst, 323 const RawAddress& src, uint16_t protocol, 324 uint8_t* p_data, uint16_t len, bool ext); 325 326 /******************************************************************************* 327 * 328 * Function PAN_WriteBuf 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 334 * it. If the return value is not PAN_SUCCESS the application 335 * should 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_buf - pointer to the data buffer 341 * ext - to indicate that extension headers present 342 * 343 * Returns PAN_SUCCESS - if the data is sent successfully 344 * PAN_FAILURE - if the connection is not found or 345 * there is an error in sending data 346 * 347 ******************************************************************************/ 348 extern tPAN_RESULT PAN_WriteBuf(uint16_t handle, const RawAddress& dst, 349 const RawAddress& src, uint16_t protocol, 350 BT_HDR* p_buf, bool ext); 351 352 /******************************************************************************* 353 * 354 * Function PAN_SetProtocolFilters 355 * 356 * Description This function is used to set protocol filters on the peer 357 * 358 * Parameters: handle - handle for the connection 359 * num_filters - number of protocol filter ranges 360 * start - array of starting protocol numbers 361 * end - array of ending protocol numbers 362 * 363 * 364 * Returns PAN_SUCCESS if protocol filters are set successfully 365 * PAN_FAILURE if connection not found or error in setting 366 * 367 ******************************************************************************/ 368 extern tPAN_RESULT PAN_SetProtocolFilters(uint16_t handle, uint16_t num_filters, 369 uint16_t* p_start_array, 370 uint16_t* p_end_array); 371 372 /******************************************************************************* 373 * 374 * Function PAN_SetMulticastFilters 375 * 376 * Description This function is used to set multicast filters on the peer 377 * 378 * Parameters: handle - handle for the connection 379 * num_filters - number of multicast filter ranges 380 * p_start_array - Pointer to sequence of beginings of all 381 * multicast address ranges 382 * p_end_array - Pointer to sequence of ends of all 383 * multicast address ranges 384 * 385 * 386 * Returns PAN_SUCCESS if multicast filters are set successfully 387 * PAN_FAILURE if connection not found or error in setting 388 * 389 ******************************************************************************/ 390 extern tBNEP_RESULT PAN_SetMulticastFilters(uint16_t handle, 391 uint16_t num_mcast_filters, 392 uint8_t* p_start_array, 393 uint8_t* p_end_array); 394 395 /******************************************************************************* 396 * 397 * Function PAN_SetTraceLevel 398 * 399 * Description This function sets the trace level for PAN. If called with 400 * a value of 0xFF, it simply reads the current trace level. 401 * 402 * Returns the new (current) trace level 403 * 404 ******************************************************************************/ 405 extern uint8_t PAN_SetTraceLevel(uint8_t new_level); 406 407 /******************************************************************************* 408 * 409 * Function PAN_Init 410 * 411 * Description This function initializes the PAN unit. It should be called 412 * before accessing any other APIs to initialize the control 413 * block. 414 * 415 * Returns void 416 * 417 ******************************************************************************/ 418 extern void PAN_Init(void); 419 420 #endif /* PAN_API_H */ 421