nfa_snep_api.h revision f8a4ca325ef137a94869b34d36095ba7d08816a3
1/***************************************************************************** 2** 3** Name: nfa_snep_api.h 4** 5** Description: This is the public interface file for NFA SNEP, Broadcom's 6** NFC application layer for mobile phones. 7** 8** Copyright (c) 2010-2011, Broadcom Corp., All Rights Reserved. 9** Broadcom Bluetooth Core. Proprietary and confidential. 10** 11*****************************************************************************/ 12#ifndef NFA_SNEP_API_H 13#define NFA_SNEP_API_H 14 15#include "nfa_api.h" 16 17/***************************************************************************** 18** Constants and data types 19*****************************************************************************/ 20#define NFA_SNEP_VERSION 0x10 /* SNEP Version 1.0 */ 21 22#define NFA_SNEP_REQ_CODE_CONTINUE 0x00 /* send remaining fragments */ 23#define NFA_SNEP_REQ_CODE_GET 0x01 /* return an NDEF message */ 24#define NFA_SNEP_REQ_CODE_PUT 0x02 /* accept an NDEF message */ 25#define NFA_SNEP_REQ_CODE_REJECT 0x7F /* do not send remaining fragments */ 26 27#define tNFA_SNEP_REQ_CODE UINT8 28 29#define NFA_SNEP_RESP_CODE_CONTINUE 0x80 /* continue send remaining fragments */ 30#define NFA_SNEP_RESP_CODE_SUCCESS 0x81 /* the operation succeeded */ 31#define NFA_SNEP_RESP_CODE_NOT_FOUND 0xC0 /* resource not found */ 32#define NFA_SNEP_RESP_CODE_EXCESS_DATA 0xC1 /* resource exceeds data size limit */ 33#define NFA_SNEP_RESP_CODE_BAD_REQ 0xC2 /* malformed request not understood */ 34#define NFA_SNEP_RESP_CODE_NOT_IMPLM 0xE0 /* unsupported functionality requested */ 35#define NFA_SNEP_RESP_CODE_UNSUPP_VER 0xE1 /* unsupported protocol version */ 36#define NFA_SNEP_RESP_CODE_REJECT 0xFF /* do not send remaining fragments */ 37 38#define tNFA_SNEP_RESP_CODE UINT8 39 40/* NFA SNEP callback events */ 41#define NFA_SNEP_REG_EVT 0x00 /* Server/client Registeration Status */ 42#define NFA_SNEP_ACTIVATED_EVT 0x01 /* LLCP link has been activated, client only */ 43#define NFA_SNEP_DEACTIVATED_EVT 0x02 /* LLCP link has been deactivated, client only */ 44#define NFA_SNEP_CONNECTED_EVT 0x03 /* Data link has been created */ 45#define NFA_SNEP_GET_REQ_EVT 0x04 /* GET request from client */ 46#define NFA_SNEP_PUT_REQ_EVT 0x05 /* PUT request from client */ 47#define NFA_SNEP_GET_RESP_EVT 0x06 /* GET response from server */ 48#define NFA_SNEP_PUT_RESP_EVT 0x07 /* PUT response from server */ 49#define NFA_SNEP_DISC_EVT 0x08 /* Failed to connect or disconnected */ 50 51#define NFA_SNEP_ALLOC_BUFF_EVT 0x09 /* Request to allocate a buffer for NDEF*/ 52#define NFA_SNEP_GET_RESP_CMPL_EVT 0x0A /* GET response sent to client */ 53 54#define NFA_SNEP_DEFAULT_SERVER_STARTED_EVT 0x0B /* SNEP default server is started */ 55#define NFA_SNEP_DEFAULT_SERVER_STOPPED_EVT 0x0C /* SNEP default server is stopped */ 56 57typedef UINT8 tNFA_SNEP_EVT; 58 59#define NFA_SNEP_ANY_SAP LLCP_INVALID_SAP 60 61/* Data for NFA_SNEP_REG_EVT */ 62typedef struct 63{ 64 tNFA_STATUS status; 65 tNFA_HANDLE reg_handle; /* handle for registered server/client */ 66 char service_name[LLCP_MAX_SN_LEN + 1]; /* only for server */ 67} tNFA_SNEP_REG; 68 69/* Data for NFA_SNEP_ACTIVATED_EVT */ 70typedef struct 71{ 72 tNFA_HANDLE client_handle; /* handle for registered client */ 73} tNFA_SNEP_ACTIVATED; 74 75/* Data for NFA_SNEP_DEACTIVATED_EVT */ 76typedef tNFA_SNEP_ACTIVATED tNFA_SNEP_DEACTIVATED; 77 78/* Data for NFA_SNEP_CONNECTED_EVT */ 79/* 80** for server, new handle will be assigned for conn_handle 81** for client, handle used in NFA_SnepConnect () is returned in conn_handle 82*/ 83typedef struct 84{ 85 tNFA_HANDLE reg_handle; /* server/client handle */ 86 tNFA_HANDLE conn_handle; /* handle for data link connection */ 87} tNFA_SNEP_CONNECT; 88 89/* Data for NFA_SNEP_GET_REQ_EVT */ 90typedef struct 91{ 92 tNFA_HANDLE conn_handle; /* handle for data link connection */ 93 UINT32 acceptable_length; /* acceptable length from client */ 94 UINT32 ndef_length; /* NDEF message length */ 95 UINT8 *p_ndef; /* NDEF message */ 96} tNFA_SNEP_GET_REQ; 97 98/* Data for NFA_SNEP_PUT_REQ_EVT */ 99typedef struct 100{ 101 tNFA_HANDLE conn_handle; /* handle for data link connection */ 102 UINT32 ndef_length; /* NDEF message length */ 103 UINT8 *p_ndef; /* NDEF message */ 104} tNFA_SNEP_PUT_REQ; 105 106/* Data for NFA_SNEP_GET_RESP_EVT */ 107typedef struct 108{ 109 tNFA_HANDLE conn_handle; /* handle for data link connection */ 110 tNFA_SNEP_RESP_CODE resp_code; /* response code from server */ 111 UINT32 ndef_length; /* NDEF message length */ 112 UINT8 *p_ndef; /* NDEF message */ 113} tNFA_SNEP_GET_RESP; 114 115/* Data for NFA_SNEP_PUT_RESP_EVT */ 116typedef struct 117{ 118 tNFA_HANDLE conn_handle; /* handle for data link connection */ 119 tNFA_SNEP_RESP_CODE resp_code; /* response code from server */ 120} tNFA_SNEP_PUT_RESP; 121 122/* Data for NFA_SNEP_DISC_EVT */ 123typedef struct 124{ 125 tNFA_HANDLE conn_handle; /* handle for data link connection */ 126 /* client_handle if connection failed */ 127} tNFA_SNEP_DISC; 128 129/* Data for NFA_SNEP_ALLOC_BUFF_EVT */ 130typedef struct 131{ 132 tNFA_HANDLE conn_handle; /* handle for data link connection */ 133 tNFA_SNEP_REQ_CODE req_code; /* NFA_SNEP_REQ_CODE_GET or NFA_SNEP_REQ_CODE_PUT */ 134 tNFA_SNEP_RESP_CODE resp_code; /* Response code if cannot allocate buffer */ 135 UINT32 ndef_length; /* NDEF message length */ 136 UINT8 *p_buff; /* buffer for NDEF message */ 137} tNFA_SNEP_ALLOC; 138 139/* Data for NFA_SNEP_GET_RESP_CMPL_EVT */ 140typedef struct 141{ 142 tNFA_HANDLE conn_handle; /* handle for data link connection */ 143 UINT8 *p_buff; /* buffer for NDEF message */ 144} tNFA_SNEP_GET_RESP_CMPL; 145 146/* Union of all SNEP callback structures */ 147typedef union 148{ 149 tNFA_SNEP_REG reg; /* NFA_SNEP_REG_EVT */ 150 tNFA_SNEP_ACTIVATED activated; /* NFA_SNEP_ACTIVATED_EVT */ 151 tNFA_SNEP_DEACTIVATED deactivated; /* NFA_SNEP_DEACTIVATED_EVT */ 152 tNFA_SNEP_CONNECT connect; /* NFA_SNEP_CONNECTED_EVT */ 153 tNFA_SNEP_GET_REQ get_req; /* NFA_SNEP_GET_REQ_EVT */ 154 tNFA_SNEP_PUT_REQ put_req; /* NFA_SNEP_PUT_REQ_EVT */ 155 tNFA_SNEP_GET_RESP get_resp; /* NFA_SNEP_GET_RESP_EVT */ 156 tNFA_SNEP_PUT_RESP put_resp; /* NFA_SNEP_PUT_RESP_EVT */ 157 tNFA_SNEP_DISC disc; /* NFA_SNEP_DISC_EVT */ 158 tNFA_SNEP_ALLOC alloc; /* NFA_SNEP_ALLOC_BUFF_EVT */ 159 tNFA_SNEP_GET_RESP_CMPL get_resp_cmpl; /* NFA_SNEP_GET_RESP_CMPL_EVT */ 160} tNFA_SNEP_EVT_DATA; 161 162/* NFA SNEP callback */ 163typedef void (tNFA_SNEP_CBACK) (tNFA_SNEP_EVT event, tNFA_SNEP_EVT_DATA *p_data); 164 165/***************************************************************************** 166** External Function Declarations 167*****************************************************************************/ 168#ifdef __cplusplus 169extern "C" 170{ 171#endif 172 173/******************************************************************************* 174** 175** Function NFA_SnepStartDefaultServer 176** 177** Description This function is called to listen to SAP, 0x04 as SNEP default 178** server ("urn:nfc:sn:snep") on LLCP. 179** 180** NFA_SNEP_DEFAULT_SERVER_STARTED_EVT without data will be returned. 181** 182** Note: If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT 183** should happen before calling this function 184** 185** Returns NFA_STATUS_OK if successfully initiated 186** NFA_STATUS_FAILED otherwise 187** 188*******************************************************************************/ 189NFC_API extern tNFA_STATUS NFA_SnepStartDefaultServer (tNFA_SNEP_CBACK *p_cback); 190 191/******************************************************************************* 192** 193** Function NFA_SnepStopDefaultServer 194** 195** Description This function is called to stop SNEP default server on LLCP. 196** 197** NFA_SNEP_DEFAULT_SERVER_STOPPED_EVT without data will be returned. 198** 199** Note: If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT 200** should happen before calling this function 201** 202** Returns NFA_STATUS_OK if successfully initiated 203** NFA_STATUS_FAILED otherwise 204** 205*******************************************************************************/ 206NFC_API extern tNFA_STATUS NFA_SnepStopDefaultServer (tNFA_SNEP_CBACK *p_cback); 207 208/******************************************************************************* 209** 210** Function NFA_SnepRegisterServer 211** 212** Description This function is called to listen to a SAP as SNEP server. 213** 214** If server_sap is set to NFA_SNEP_ANY_SAP, then NFA will allocate 215** a SAP between LLCP_LOWER_BOUND_SDP_SAP and LLCP_UPPER_BOUND_SDP_SAP 216** 217** NFC Forum default SNEP server ("urn:nfc:sn:snep") may be launched 218** by NFA_SnepStartDefaultServer (). 219** 220** NFA_SNEP_REG_EVT will be returned with status, handle and service name. 221** 222** Note: If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT 223** should happen before calling this function 224** 225** Returns NFA_STATUS_OK if successfully initiated 226** NFA_STATUS_INVALID_PARAM if p_service_name or p_cback is NULL 227** NFA_STATUS_FAILED otherwise 228** 229*******************************************************************************/ 230NFC_API extern tNFA_STATUS NFA_SnepRegisterServer (UINT8 server_sap, 231 char *p_service_name, 232 tNFA_SNEP_CBACK *p_cback); 233 234/******************************************************************************* 235** 236** Function NFA_SnepRegisterClient 237** 238** Description This function is called to register SNEP client. 239** NFA_SNEP_REG_EVT will be returned with status, handle 240** and zero-length service name. 241** 242** Returns NFA_STATUS_OK if successfully initiated 243** NFA_STATUS_INVALID_PARAM if p_cback is NULL 244** NFA_STATUS_FAILED otherwise 245** 246*******************************************************************************/ 247NFC_API extern tNFA_STATUS NFA_SnepRegisterClient (tNFA_SNEP_CBACK *p_cback); 248 249/******************************************************************************* 250** 251** Function NFA_SnepDeregister 252** 253** Description This function is called to stop listening as SNEP server 254** or SNEP client. Application shall use reg_handle returned in 255** NFA_SNEP_REG_EVT. 256** 257** Note: If this function is called to de-register a SNEP server and RF 258** discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT 259** should happen before calling this function 260** 261** Returns NFA_STATUS_OK if successfully initiated 262** NFA_STATUS_BAD_HANDLE if handle is not valid 263** NFA_STATUS_FAILED otherwise 264** 265*******************************************************************************/ 266NFC_API extern tNFA_STATUS NFA_SnepDeregister (tNFA_HANDLE reg_handle); 267 268/******************************************************************************* 269** 270** Function NFA_SnepConnect 271** 272** Description This function is called by client to create data link connection 273** to SNEP server on peer device. 274** 275** Client handle and service name of server to connect shall be provided. 276** A conn_handle will be returned in NFA_SNEP_CONNECTED_EVT, if 277** successfully connected. Otherwise NFA_SNEP_DISC_EVT will be returned. 278** 279** Returns NFA_STATUS_OK if successfully initiated 280** NFA_STATUS_BAD_HANDLE if handle is not valid 281** NFA_STATUS_INVALID_PARAM if p_service_name or p_cback is NULL 282** NFA_STATUS_FAILED otherwise 283** 284*******************************************************************************/ 285NFC_API extern tNFA_STATUS NFA_SnepConnect (tNFA_HANDLE client_handle, 286 char *p_service_name); 287 288/******************************************************************************* 289** 290** Function NFA_SnepGet 291** 292** Description This function is called by client to send GET request. 293** 294** Application shall allocate a buffer and put NDEF message with 295** desired record type to get from server. NDEF message from server 296** will be returned in the same buffer with NFA_SNEP_GET_RESP_EVT. 297** The size of buffer will be used as "Acceptable Length". 298** 299** NFA_SNEP_GET_RESP_EVT or NFA_SNEP_DISC_EVT will be returned 300** through registered p_cback. Application may free the buffer 301** after receiving these events. 302** 303** 304** Returns NFA_STATUS_OK if successfully initiated 305** NFA_STATUS_BAD_HANDLE if handle is not valid 306** NFA_STATUS_FAILED otherwise 307** 308*******************************************************************************/ 309NFC_API extern tNFA_STATUS NFA_SnepGet (tNFA_HANDLE conn_handle, 310 UINT32 buff_length, 311 UINT32 ndef_length, 312 UINT8 *p_ndef_buff); 313 314/******************************************************************************* 315** 316** Function NFA_SnepPut 317** 318** Description This function is called by client to send PUT request. 319** 320** Application shall allocate a buffer and put desired NDEF message 321** to send to server. 322** 323** NFA_SNEP_PUT_RESP_EVT or NFA_SNEP_DISC_EVT will be returned 324** through p_cback. Application may free the buffer after receiving 325** these events. 326** 327** Returns NFA_STATUS_OK if successfully initiated 328** NFA_STATUS_BAD_HANDLE if handle is not valid 329** NFA_STATUS_INVALID_PARAM if p_service_name or p_cback is NULL 330** NFA_STATUS_FAILED otherwise 331** 332*******************************************************************************/ 333NFC_API extern tNFA_STATUS NFA_SnepPut (tNFA_HANDLE conn_handle, 334 UINT32 ndef_length, 335 UINT8 *p_ndef_buff); 336 337/******************************************************************************* 338** 339** Function NFA_SnepGetResponse 340** 341** Description This function is called by server to send response of GET request. 342** 343** When server application receives NFA_SNEP_ALLOC_BUFF_EVT, 344** it shall allocate a buffer for incoming NDEF message and 345** pass the pointer within callback context. This buffer will be 346** returned with NFA_SNEP_GET_REQ_EVT after receiving complete 347** NDEF message. If buffer is not allocated, NFA_SNEP_RESP_CODE_NOT_FOUND 348** (Note:There is no proper response code for this case) 349** or NFA_SNEP_RESP_CODE_REJECT will be sent to client. 350** 351** Server application shall provide conn_handle which is received in 352** NFA_SNEP_GET_REQ_EVT. 353** 354** Server application shall allocate a buffer and put NDEF message if 355** response code is NFA_SNEP_RESP_CODE_SUCCESS. Otherwise, ndef_length 356** shall be set to zero. 357** 358** NFA_SNEP_GET_RESP_CMPL_EVT or NFA_SNEP_DISC_EVT will be returned 359** through registered callback function. Application may free 360** the buffer after receiving these events. 361** 362** Returns NFA_STATUS_OK if successfully initiated 363** NFA_STATUS_BAD_HANDLE if handle is not valid 364** NFA_STATUS_FAILED otherwise 365** 366*******************************************************************************/ 367NFC_API extern tNFA_STATUS NFA_SnepGetResponse (tNFA_HANDLE conn_handle, 368 tNFA_SNEP_RESP_CODE resp_code, 369 UINT32 ndef_length, 370 UINT8 *p_ndef_buff); 371 372/******************************************************************************* 373** 374** Function NFA_SnepPutResponse 375** 376** Description This function is called by server to send response of PUT request. 377** 378** When server application receives NFA_SNEP_ALLOC_BUFF_EVT, 379** it shall allocate a buffer for incoming NDEF message and 380** pass the pointer within callback context. This buffer will be 381** returned with NFA_SNEP_PUT_REQ_EVT after receiving complete 382** NDEF message. If buffer is not allocated, NFA_SNEP_RESP_CODE_REJECT 383** will be sent to client or NFA will discard request and send 384** NFA_SNEP_RESP_CODE_SUCCESS (Note:There is no proper response code for 385** this case). 386** 387** Server application shall provide conn_handle which is received in 388** NFA_SNEP_PUT_REQ_EVT. 389** 390** NFA_SNEP_DISC_EVT will be returned through registered callback 391** function when client disconnects data link connection. 392** 393** Returns NFA_STATUS_OK if successfully initiated 394** NFA_STATUS_BAD_HANDLE if handle is not valid 395** NFA_STATUS_FAILED otherwise 396** 397*******************************************************************************/ 398NFC_API extern tNFA_STATUS NFA_SnepPutResponse (tNFA_HANDLE conn_handle, 399 tNFA_SNEP_RESP_CODE resp_code); 400 401/******************************************************************************* 402** 403** Function NFA_SnepDisconnect 404** 405** Description This function is called to disconnect data link connection. 406** discard any pending data if flush is set to TRUE 407** 408** Client application shall provide conn_handle in NFA_SNEP_GET_RESP_EVT 409** or NFA_SNEP_PUT_RESP_EVT. 410** 411** Server application shall provide conn_handle in NFA_SNEP_GET_REQ_EVT 412** or NFA_SNEP_PUT_REQ_EVT. 413** 414** NFA_SNEP_DISC_EVT will be returned 415** 416** Returns NFA_STATUS_OK if successfully initiated 417** NFA_STATUS_BAD_HANDLE if handle is not valid 418** NFA_STATUS_FAILED otherwise 419** 420*******************************************************************************/ 421NFC_API extern tNFA_STATUS NFA_SnepDisconnect (tNFA_HANDLE conn_handle, 422 BOOLEAN flush); 423 424/******************************************************************************* 425** 426** Function NFA_SnepSetTraceLevel 427** 428** Description This function sets the trace level for SNEP. If called with 429** a value of 0xFF, it simply returns the current trace level. 430** 431** Returns The new or current trace level 432** 433*******************************************************************************/ 434NFC_API extern UINT8 NFA_SnepSetTraceLevel (UINT8 new_level); 435 436#ifdef __cplusplus 437} 438#endif 439 440#endif /* NFA_P2P_API_H */ 441 442