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