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 70 typedef UINT8 tNFA_SNEP_EVT; 71 72 #define NFA_SNEP_ANY_SAP LLCP_INVALID_SAP 73 74 /* Data for NFA_SNEP_REG_EVT */ 75 typedef 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 */ 83 typedef struct 84 { 85 tNFA_HANDLE client_handle; /* handle for registered client */ 86 } tNFA_SNEP_ACTIVATED; 87 88 /* Data for NFA_SNEP_DEACTIVATED_EVT */ 89 typedef 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 */ 96 typedef 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 */ 103 typedef 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 */ 112 typedef 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 */ 120 typedef 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 */ 129 typedef 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 */ 136 typedef 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 */ 143 typedef 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 */ 153 typedef 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 */ 160 typedef 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 */ 176 typedef void (tNFA_SNEP_CBACK) (tNFA_SNEP_EVT event, tNFA_SNEP_EVT_DATA *p_data); 177 178 /***************************************************************************** 179 ** External Function Declarations 180 *****************************************************************************/ 181 #ifdef __cplusplus 182 extern "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 *******************************************************************************/ 202 NFC_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 *******************************************************************************/ 219 NFC_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 *******************************************************************************/ 243 NFC_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 *******************************************************************************/ 260 NFC_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 *******************************************************************************/ 279 NFC_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 *******************************************************************************/ 298 NFC_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 *******************************************************************************/ 322 NFC_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 *******************************************************************************/ 346 NFC_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 *******************************************************************************/ 380 NFC_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 *******************************************************************************/ 411 NFC_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 *******************************************************************************/ 434 NFC_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 *******************************************************************************/ 447 NFC_API extern UINT8 NFA_SnepSetTraceLevel (UINT8 new_level); 448 449 #ifdef __cplusplus 450 } 451 #endif 452 453 #endif /* NFA_P2P_API_H */ 454 455
