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