nfa_hci_api.h revision f8a4ca325ef137a94869b34d36095ba7d08816a3
1/***************************************************************************** 2** 3** Name: nfa_hci_api.h 4** 5** Description: This is the public interface file for NFA HCI, Broadcom's 6** NFC application layer for mobile phones. 7** 8** Copyright (c) 2010, Broadcom Corp., All Rights Reserved. 9** Broadcom Bluetooth Core. Proprietary and confidential. 10** 11*****************************************************************************/ 12#ifndef NFA_HCI_API_H 13#define NFA_HCI_API_H 14 15#include "nfa_api.h" 16 17/***************************************************************************** 18** Constants and data types 19*****************************************************************************/ 20 21/* NFA HCI Debug constants */ 22#define NFA_HCI_DEBUG_DISPLAY_CB 0 23#define NFA_HCI_DEBUG_SIM_HCI_EVENT 1 24#define NFA_HCI_DEBUG_ENABLE_LOOPBACK 101 25#define NFA_HCI_DEBUG_DISABLE_LOOPBACK 102 26 27/* NFA HCI callback events */ 28#define NFA_HCI_REGISTER_EVT 0x00 /* Application registered */ 29#define NFA_HCI_DEREGISTER_EVT 0x01 /* Application deregistered */ 30#define NFA_HCI_GET_GATE_PIPE_LIST_EVT 0x02 /* Retrieved gates,pipes assoc. to application */ 31#define NFA_HCI_ALLOCATE_GATE_EVT 0x03 /* A generic gate allocated to the application */ 32#define NFA_HCI_DEALLOCATE_GATE_EVT 0x04 /* A generic gate is released */ 33#define NFA_HCI_CREATE_PIPE_EVT 0x05 /* Pipe is created */ 34#define NFA_HCI_OPEN_PIPE_EVT 0x06 /* Pipe is opened / could not open */ 35#define NFA_HCI_CLOSE_PIPE_EVT 0x07 /* Pipe is closed / could not close */ 36#define NFA_HCI_DELETE_PIPE_EVT 0x08 /* Pipe is deleted */ 37#define NFA_HCI_HOST_LIST_EVT 0x09 /* Received list of Host from Host controller */ 38#define NFA_HCI_INIT_EVT 0x0A /* HCI subsytem initialized */ 39#define NFA_HCI_EXIT_EVT 0x0B /* HCI subsytem exited */ 40#define NFA_HCI_RSP_RCVD_EVT 0x0C /* Response recvd to cmd sent on app owned pipe */ 41#define NFA_HCI_RSP_SENT_EVT 0x0D /* Response sent on app owned pipe */ 42#define NFA_HCI_CMD_SENT_EVT 0x0E /* Command sent on app owned pipe */ 43#define NFA_HCI_EVENT_SENT_EVT 0x0F /* Event sent on app owned pipe */ 44#define NFA_HCI_CMD_RCVD_EVT 0x10 /* Command received on app owned pipe */ 45#define NFA_HCI_EVENT_RCVD_EVT 0x11 /* Event received on app owned pipe */ 46#define NFA_HCI_GET_REG_CMD_EVT 0x12 /* Registry read command sent */ 47#define NFA_HCI_SET_REG_CMD_EVT 0x13 /* Registry write command sent */ 48#define NFA_HCI_GET_REG_RSP_EVT 0x14 /* Received response to read registry command */ 49#define NFA_HCI_SET_REG_RSP_EVT 0x15 /* Received response to write registry command */ 50 51typedef UINT8 tNFA_HCI_EVT; 52 53#define NFA_MAX_HCI_APP_NAME_LEN 0x10 /* Max application name length */ 54#define NFA_MAX_HCI_CMD_LEN 255 /* Max HCI command length */ 55#define NFA_MAX_HCI_RSP_LEN 255 /* Max HCI event length */ 56#define NFA_MAX_HCI_EVENT_LEN 260 /* Max HCI event length */ 57#define NFA_MAX_HCI_DATA_LEN 260 /* Max HCI data length */ 58 59/* NFA HCI PIPE states */ 60#define NFA_HCI_PIPE_CLOSED 0x00 /* Pipe is closed */ 61#define NFA_HCI_PIPE_OPENED 0x01 /* Pipe is opened */ 62 63typedef UINT8 tNFA_HCI_PIPE_STATE; 64/* Dynamic pipe control block */ 65typedef struct 66{ 67 UINT8 pipe_id; /* Pipe ID */ 68 tNFA_HCI_PIPE_STATE pipe_state; /* State of the Pipe */ 69 UINT8 local_gate; /* local gate id */ 70 UINT8 dest_host; /* Peer host to which this pipe is connected */ 71 UINT8 dest_gate; /* Peer gate to which this pipe is connected */ 72} tNFA_HCI_PIPE_INFO; 73 74/* Data for NFA_HCI_REGISTER_EVT */ 75typedef struct 76{ 77 tNFA_STATUS status; 78 tNFA_HANDLE hci_handle; 79 UINT8 num_pipes; 80 UINT8 num_gates; 81} tNFA_HCI_REGISTER; 82 83/* Data for NFA_HCI_DEREGISTER_EVT */ 84typedef struct 85{ 86 tNFA_STATUS status; 87} tNFA_HCI_DEREGISTER; 88 89/* Data for NFA_HCI_GET_GATE_PIPE_LIST_EVT */ 90typedef struct 91{ 92 tNFA_STATUS status; 93 UINT8 num_pipes; 94 tNFA_HCI_PIPE_INFO pipe[NFA_HCI_MAX_PIPE_CB]; 95 UINT8 num_gates; 96 UINT8 gate[NFA_HCI_MAX_GATE_CB]; 97 98} tNFA_HCI_GET_GATE_PIPE_LIST; 99 100/* Data for NFA_HCI_ALLOCATE_GATE_EVT */ 101typedef struct 102{ 103 tNFA_STATUS status; 104 UINT8 gate; 105} tNFA_HCI_ALLOCATE_GATE; 106 107/* Data for NFA_HCI_DEALLOCATE_GATE_EVT */ 108typedef struct 109{ 110 tNFA_STATUS status; 111 UINT8 gate; 112} tNFA_HCI_DEALLOCATE_GATE; 113 114/* Data for NFA_HCI_CREATE_PIPE_EVT */ 115typedef struct 116{ 117 tNFA_STATUS status; 118 UINT8 pipe; 119 UINT8 source_gate; 120 UINT8 dest_host; 121 UINT8 dest_gate; 122} tNFA_HCI_CREATE_PIPE; 123 124/* Data for NFA_HCI_OPEN_PIPE_EVT */ 125typedef struct 126{ 127 tNFA_STATUS status; 128 UINT8 pipe; 129}tNFA_HCI_OPEN_PIPE; 130 131/* Data for NFA_HCI_CLOSE_PIPE_EVT */ 132typedef struct 133{ 134 tNFA_STATUS status; 135 UINT8 pipe; 136}tNFA_HCI_CLOSE_PIPE; 137 138/* Data for NFA_HCI_DELETE_PIPE_EVT */ 139typedef struct 140{ 141 tNFA_STATUS status; 142 UINT8 pipe; 143} tNFA_HCI_DELETE_PIPE; 144 145/* Data for NFA_HCI_HOST_LIST_EVT */ 146typedef struct 147{ 148 tNFA_STATUS status; 149 UINT8 num_hosts; 150 UINT8 host[NFA_HCI_MAX_HOST_IN_NETWORK]; 151} tNFA_HCI_HOST_LIST; 152 153/* Data for NFA_HCI_RSP_RCVD_EVT */ 154typedef struct 155{ 156 tNFA_STATUS status; 157 UINT8 pipe; 158 UINT8 rsp_code; 159 UINT16 rsp_len; 160 UINT8 rsp_data[NFA_MAX_HCI_RSP_LEN]; 161} tNFA_HCI_RSP_RCVD; 162 163/* Data for NFA_HCI_EVENT_RCVD_EVT */ 164typedef struct 165{ 166 tNFA_STATUS status; 167 UINT8 pipe; 168 UINT8 evt_code; 169 UINT16 evt_len; 170 UINT8 *p_evt_buf; 171} tNFA_HCI_EVENT_RCVD; 172 173/* Data for NFA_HCI_CMD_RCVD_EVT */ 174typedef struct 175{ 176 tNFA_STATUS status; 177 UINT8 pipe; 178 UINT8 cmd_code; 179 UINT16 cmd_len; 180 UINT8 cmd_data[NFA_MAX_HCI_CMD_LEN]; 181} tNFA_HCI_CMD_RCVD; 182 183/* Data for NFA_HCI_INIT_EVT */ 184typedef struct 185{ 186 tNFA_STATUS status; 187} tNFA_HCI_INIT; 188 189/* Data for NFA_HCI_EXIT_EVT */ 190typedef struct 191{ 192 tNFA_STATUS status; 193} tNFA_HCI_EXIT; 194 195/* Data for NFA_HCI_RSP_SENT_EVT */ 196typedef struct 197{ 198 tNFA_STATUS status; 199} tNFA_HCI_RSP_SENT; 200 201/* Data for NFA_HCI_CMD_SENT_EVT */ 202typedef struct 203{ 204 tNFA_STATUS status; 205} tNFA_HCI_CMD_SENT; 206 207/* Data for NFA_HCI_EVENT_SENT_EVT */ 208typedef struct 209{ 210 tNFA_STATUS status; 211} tNFA_HCI_EVENT_SENT; 212 213/* data type for all registry-related events */ 214typedef struct 215{ 216 tNFA_STATUS status; 217 UINT8 pipe; 218 UINT8 index; 219 UINT8 data_len; 220 UINT8 reg_data[NFA_MAX_HCI_DATA_LEN]; 221} tNFA_HCI_REGISTRY; 222 223 224/* Union of all hci callback structures */ 225typedef union 226{ 227 tNFA_HCI_REGISTER hci_register; /* NFA_HCI_REGISTER_EVT */ 228 tNFA_HCI_DEREGISTER hci_deregister; /* NFA_HCI_DEREGISTER_EVT */ 229 tNFA_HCI_GET_GATE_PIPE_LIST gates_pipes; /* NFA_HCI_GET_GATE_PIPE_LIST_EVT */ 230 tNFA_HCI_ALLOCATE_GATE allocated; /* NFA_HCI_ALLOCATE_GATE_EVT */ 231 tNFA_HCI_DEALLOCATE_GATE deallocated; /* NFA_HCI_DEALLOCATE_GATE_EVT */ 232 tNFA_HCI_CREATE_PIPE created; /* NFA_HCI_CREATE_PIPE_EVT */ 233 tNFA_HCI_OPEN_PIPE opened; /* NFA_HCI_OPEN_PIPE_EVT */ 234 tNFA_HCI_CLOSE_PIPE closed; /* NFA_HCI_CLOSE_PIPE_EVT */ 235 tNFA_HCI_DELETE_PIPE deleted; /* NFA_HCI_DELETE_PIPE_EVT */ 236 tNFA_HCI_HOST_LIST hosts; /* NFA_HCI_HOST_LIST_EVT */ 237 tNFA_HCI_RSP_RCVD rsp_rcvd; /* NFA_HCI_RSP_RCVD_EVT */ 238 tNFA_HCI_RSP_SENT rsp_sent; /* NFA_HCI_RSP_SENT_EVT */ 239 tNFA_HCI_CMD_SENT cmd_sent; /* NFA_HCI_CMD_SENT_EVT */ 240 tNFA_HCI_EVENT_SENT evt_sent; /* NFA_HCI_EVENT_SENT_EVT */ 241 tNFA_HCI_CMD_RCVD cmd_rcvd; /* NFA_HCI_CMD_RCVD_EVT */ 242 tNFA_HCI_EVENT_RCVD rcvd_evt; /* NFA_HCI_EVENT_RCVD_EVT */ 243 tNFA_STATUS status; /* status of api command request */ 244 tNFA_HCI_REGISTRY registry; /* all registry-related events */ 245 tNFA_HCI_INIT hci_init; /* NFA_HCI_INIT_EVT */ 246 tNFA_HCI_EXIT hci_exit; /* NFA_HCI_EXIT_EVT */ 247} tNFA_HCI_EVT_DATA; 248 249/* NFA HCI callback */ 250typedef void (tNFA_HCI_CBACK) (tNFA_HCI_EVT event, tNFA_HCI_EVT_DATA *p_data); 251 252/***************************************************************************** 253** External Function Declarations 254*****************************************************************************/ 255#ifdef __cplusplus 256extern "C" 257{ 258#endif 259 260 261/******************************************************************************* 262** 263** Function NFA_HciRegister 264** 265** Description This function will register an application with hci and 266** returns an application handle and provides a mechanism to 267** register a callback with HCI to receive NFA HCI event 268** notification. When the application is registered 269** (or if an error occurs), the app will be notified with 270** NFA_HCI_REGISTER_EVT. Previous session information including 271** allocated gates, created pipes and pipes states will be 272** returned as part of tNFA_HCI_REGISTER data. 273** 274** Returns NFA_STATUS_OK if successfully initiated 275** NFA_STATUS_FAILED otherwise 276** 277*******************************************************************************/ 278NFC_API extern tNFA_STATUS NFA_HciRegister (char *p_app_name, tNFA_HCI_CBACK *p_cback, BOOLEAN b_send_conn_evts, UINT16 buf_size, UINT8 *p_evt_buf); 279 280/******************************************************************************* 281** 282** Function NFA_HciDeregister 283** 284** Description This function is called to deregister an application 285** from HCI.However pipe states will not be affected by this 286** function call. 287** 288** Returns NFA_STATUS_OK if the application is deregistered successfully 289** NFA_STATUS_BAD_HANDLE if handle is not valid 290** NFA_STATUS_FAILED otherwise 291 292*******************************************************************************/ 293NFC_API extern tNFA_STATUS NFA_HciDeregister (char *p_app_name); 294 295/******************************************************************************* 296** 297** Function NFA_HciGetGateAndPipeList 298** 299** Description This function will return the list of gates allocated by 300** the application and list of pipes created on each of those 301** gates. 302** 303** Returns NFA_STATUS_OK if successfully initiated 304** NFA_STATUS_FAILED otherwise 305** 306*******************************************************************************/ 307NFC_API extern tNFA_STATUS NFA_HciGetGateAndPipeList (tNFA_HANDLE hci_handle); 308 309/******************************************************************************* 310** 311** Function NFA_HciAllocGate 312** 313** Description This function will allocate an available generic gate for 314** the app to provide an entry point for a particular service 315** to other host or to establish communication with other host. 316** When the generic gate is allocated (or if an error occurs), 317** the app will be notified with NFA_HCI_ALLOCATE_GATE_EVT with 318** the gate id. The allocated Gate information will be stored in 319** non volatile memory. 320** 321** Returns NFA_STATUS_OK if this API started 322** NFA_STATUS_BAD_HANDLE if handle is not valid 323** NFA_STATUS_FAILED if no generic gate is available 324** 325*******************************************************************************/ 326NFC_API extern tNFA_STATUS NFA_HciAllocGate (tNFA_HANDLE hci_handle); 327 328/******************************************************************************* 329** 330** Function NFA_HciDeallocGate 331** 332** Description This function will release the specified gate that was 333** previously allocated to the application. When the generic 334** gate is released (or if an error occurs), the app will be 335** notified with NFA_HCI_DEALLOCATE_GATE_EVT with the gate id. 336** The allocated Gate information will be deleted from non 337** volatile memory and all the associated pipes are deleted 338** by informing host controller. 339** 340** Returns NFA_STATUS_OK if successfully initiated 341** NFA_STATUS_BAD_HANDLE if handle is not valid 342** NFA_STATUS_FAILED otherwise 343** 344*******************************************************************************/ 345NFC_API extern tNFA_STATUS NFA_HciDeallocGate (tNFA_HANDLE conn_handle, UINT8 gate); 346 347/******************************************************************************* 348** 349** Function NFA_HciCreatePipe 350** 351** Description This function is called to create a dynamic pipe with the 352** specified host. When the dynamic pipe is created (or 353** if an error occurs), the app will be notified with 354** NFA_HCI_CREATE_PIPE_EVT with the pipe id. If a pipe exists 355** between the two gates passed as argument and if it was 356** created earlier by the calling application then the pipe 357** id of the existing pipe will be returned and a new pipe 358** will not be created. After successful creation of pipe, 359** registry entry will be created for the dynamic pipe and 360** all information related to the pipe will be stored in non 361** volatile memory. 362** 363** Returns NFA_STATUS_OK if successfully initiated 364** NFA_STATUS_BAD_HANDLE if handle is not valid 365** NFA_STATUS_FAILED otherwise 366** 367*******************************************************************************/ 368NFC_API extern tNFA_STATUS NFA_HciCreatePipe (tNFA_HANDLE hci_handle, 369 UINT8 source_gate_id, 370 UINT8 dest_host, 371 UINT8 dest_gate); 372 373/******************************************************************************* 374** 375** Function NFA_HciDeletePipe 376** 377** Description This function is called to delete a particular dynamic pipe. 378** When the dynamic pipe is deleted (or if an error occurs), 379** the app will be notified with NFA_HCI_DELETE_PIPE_EVT with 380** the pipe id. After successful deletion of pipe, registry 381** entry will be deleted for the dynamic pipe and all 382** information related to the pipe will be deleted from non 383** volatile memory. 384** 385** Returns NFA_STATUS_OK if successfully initiated 386** NFA_STATUS_BAD_HANDLE if handle is not valid 387** NFA_STATUS_FAILED otherwise 388** 389*******************************************************************************/ 390NFC_API extern tNFA_STATUS NFA_HciDeletePipe (tNFA_HANDLE hci_handle, UINT8 pipe); 391 392/******************************************************************************* 393** 394** Function NFA_HciOpenPipe 395** 396** Description This function is called to open a dynamic pipe. 397** When the dynamic pipe is opened (or 398** if an error occurs), the app will be notified with 399** NFA_HCI_OPEN_PIPE_EVT with the pipe id. 400** 401** Returns NFA_STATUS_OK if successfully initiated 402** NFA_STATUS_FAILED otherwise 403** 404*******************************************************************************/ 405NFC_API extern tNFA_STATUS NFA_HciOpenPipe (tNFA_HANDLE hci_handle, UINT8 pipe); 406 407/******************************************************************************* 408** 409** Function NFA_HciClosePipe 410** 411** Description This function is called to close a dynamic pipe. 412** When the dynamic pipe is closed (or 413** if an error occurs), the app will be notified with 414** NFA_HCI_CLOSE_PIPE_EVT with the pipe id. 415** 416** Returns NFA_STATUS_OK if successfully initiated 417** NFA_STATUS_FAILED otherwise 418** 419*******************************************************************************/ 420NFC_API extern tNFA_STATUS NFA_HciClosePipe (tNFA_HANDLE hci_handle, UINT8 pipe); 421 422/******************************************************************************* 423** 424** Function NFA_HciGetHostList 425** 426** Description This function will request the host controller to return the 427** list of hosts that are present in the host network. When 428** host controller responds with the host list (or if an error 429** occurs), the app will be notified with NFA_HCI_HOST_LIST_EVT 430** 431** Returns NFA_STATUS_OK if successfully initiated 432** NFA_STATUS_BAD_HANDLE if handle is not valid 433** NFA_STATUS_FAILED otherwise 434** 435*******************************************************************************/ 436NFC_API extern tNFA_STATUS NFA_HciGetHostList (tNFA_HANDLE hci_handle); 437 438/******************************************************************************* 439** 440** Function NFA_HciGetRegistry 441** 442** Description This function requests a peer host to return the desired 443** registry field value for the gate that the pipe is on. 444** 445** When the peer host responds with the registry value, or if an 446** error occurs, the app is notified with NFA_HCI_GET_REGISTRY_EVT 447** 448** Returns NFA_STATUS_OK if successfully initiated 449** NFA_STATUS_BAD_HANDLE if handle is not valid 450** NFA_STATUS_FAILED otherwise 451** 452*******************************************************************************/ 453NFC_API extern tNFA_STATUS NFA_HciGetRegistry (tNFA_HANDLE hci_handle, UINT8 pipe, UINT8 reg_inx); 454 455/******************************************************************************* 456** 457** Function NFA_HciSetRegistry 458** 459** Description This function requests a peer host to set the desired 460** registry field value for the gate that the pipe is on. 461** 462** When the peer host responds, or if an error occurs, the app 463** is notified with NFA_HCI_SET_REGISTRY_EVT 464** 465** Returns NFA_STATUS_OK if successfully initiated 466** NFA_STATUS_BAD_HANDLE if handle is not valid 467** NFA_STATUS_FAILED otherwise 468** 469*******************************************************************************/ 470NFC_API extern tNFA_STATUS NFA_HciSetRegistry (tNFA_HANDLE hci_handle, 471 UINT8 pipe, 472 UINT8 reg_inx, 473 UINT8 data_size, 474 UINT8 *p_data); 475 476/******************************************************************************* 477** 478** Function NFA_HciSendCommand 479** 480** Description This function is called to send an command through a particular 481** dynamic pipe. 482** 483** Returns NFA_STATUS_OK if successfully initiated 484** NFA_STATUS_BAD_HANDLE if handle is not valid 485** NFA_STATUS_FAILED otherwise 486** 487*******************************************************************************/ 488NFC_API extern tNFA_STATUS NFA_HciSendCommand (tNFA_HANDLE hci_handle, 489 UINT8 pipe, 490 UINT8 cmd_code, 491 UINT16 cmd_size, 492 UINT8 *p_data); 493 494/******************************************************************************* 495** 496** Function NFA_HciSendEvent 497** 498** Description This function is called to send an event through a particular 499** dynamic pipe. 500** 501** Returns NFA_STATUS_OK if successfully initiated 502** NFA_STATUS_BAD_HANDLE if handle is not valid 503** NFA_STATUS_FAILED otherwise 504** 505*******************************************************************************/ 506NFC_API extern tNFA_STATUS NFA_HciSendEvent (tNFA_HANDLE hci_handle, 507 UINT8 pipe, 508 UINT8 evt_code, 509 UINT16 evt_size, 510 UINT8 *p_data); 511 512 513/******************************************************************************* 514** 515** Function NFA_HciSendResponse 516** 517** Description This function sends a response. Typically this is to reply 518** to a Get Param or a Set Param command 519** 520** Returns NFA_STATUS_OK if successfully initiated 521** NFA_STATUS_FAILED otherwise 522** 523*******************************************************************************/ 524NFC_API extern tNFA_STATUS NFA_HciSendResponse (tNFA_HANDLE hci_handle, 525 UINT8 pipe, 526 UINT8 response, 527 UINT8 data_size, 528 UINT8 *p_data); 529 530/******************************************************************************* 531** 532** Function NFA_HciDebug 533** 534** Description Debug function. 535** 536*******************************************************************************/ 537NFC_API extern void NFA_HciDebug (UINT8 action, UINT8 size, UINT8 *p_data); 538 539#ifdef __cplusplus 540} 541#endif 542 543#endif /* NFA_P2P_API_H */ 544 545