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