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