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