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