nfa_p2p_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 P2P, Broadcom's NFC
22 *  application layer for mobile phones.
23 *
24 ******************************************************************************/
25#ifndef NFA_P2P_API_H
26#define NFA_P2P_API_H
27
28#include "llcp_api.h"
29#include "nfa_api.h"
30
31/*****************************************************************************
32**  Constants and data types
33*****************************************************************************/
34
35/* NFA P2P Reason of disconnection */
36#define NFA_P2P_DISC_REASON_REMOTE_INITIATE	    0x00    /* remote initiated to disconnect  */
37#define NFA_P2P_DISC_REASON_LOCAL_INITITATE	    0x01    /* local initiated to disconnect   */
38#define NFA_P2P_DISC_REASON_NO_SERVICE	        0x02    /* no service bound in remote      */
39#define NFA_P2P_DISC_REASON_REMOTE_REJECT	    0x03    /* remote rejected connection      */
40#define NFA_P2P_DISC_REASON_FRAME_ERROR	        0x04    /* sending or receiving FRMR PDU   */
41#define NFA_P2P_DISC_REASON_LLCP_DEACTIVATED	0x05    /* LLCP link deactivated           */
42#define NFA_P2P_DISC_REASON_NO_RESOURCE	        0x06    /* Out of resource in local device */
43#define NFA_P2P_DISC_REASON_NO_INFORMATION	    0x80    /* Without information             */
44
45/* NFA P2P callback events */
46#define NFA_P2P_REG_SERVER_EVT      0x00    /* Server is registered                         */
47#define NFA_P2P_REG_CLIENT_EVT      0x01    /* Client is registered                         */
48#define NFA_P2P_ACTIVATED_EVT       0x02    /* LLCP Link has been activated                 */
49#define NFA_P2P_DEACTIVATED_EVT	    0x03    /* LLCP Link has been deactivated               */
50#define NFA_P2P_CONN_REQ_EVT        0x04    /* Data link connection request from peer       */
51#define NFA_P2P_CONNECTED_EVT       0x05    /* Data link connection has been established    */
52#define NFA_P2P_DISC_EVT            0x06    /* Data link connection has been disconnected   */
53#define NFA_P2P_DATA_EVT            0x07    /* Data received from peer                      */
54#define NFA_P2P_CONGEST_EVT         0x08    /* Status indication of outgoing data           */
55#define NFA_P2P_LINK_INFO_EVT       0x09    /* link MIU and Well-Known Service list         */
56#define NFA_P2P_SDP_EVT	            0x0A    /* Remote SAP of SDP result                     */
57
58typedef UINT8 tNFA_P2P_EVT;
59
60/* NFA allocates a SAP for server */
61#define NFA_P2P_ANY_SAP         LLCP_INVALID_SAP
62#define NFA_P2P_INVALID_SAP     LLCP_INVALID_SAP
63
64/* Recommanded MIU's for connection-oriented */
65#define NFA_P2P_MIU_1           (NCI_NFC_DEP_MAX_DATA - LLCP_PDU_HEADER_SIZE - LLCP_SEQUENCE_SIZE)
66#define NFA_P2P_MIU_2           (2*NCI_NFC_DEP_MAX_DATA - LLCP_PDU_HEADER_SIZE - LLCP_SEQUENCE_SIZE)
67#define NFA_P2P_MIU_3           (3*NCI_NFC_DEP_MAX_DATA - LLCP_PDU_HEADER_SIZE - LLCP_SEQUENCE_SIZE)
68#define NFA_P2P_MIU_8           (8*NCI_NFC_DEP_MAX_DATA - LLCP_PDU_HEADER_SIZE - LLCP_SEQUENCE_SIZE)
69
70#define NFA_P2P_LLINK_TYPE      LLCP_LINK_TYPE_LOGICAL_DATA_LINK
71#define NFA_P2P_DLINK_TYPE      LLCP_LINK_TYPE_DATA_LINK_CONNECTION
72typedef UINT8 tNFA_P2P_LINK_TYPE;
73
74/* Data for NFA_P2P_REG_SERVER_EVT */
75typedef struct
76{
77    tNFA_HANDLE     server_handle;     /* NFA_HANDLE_INVALID if failed */
78    char            service_name[LLCP_MAX_SN_LEN + 1];
79    UINT8           server_sap;
80} tNFA_P2P_REG_SERVER;
81
82/* Data for NFA_P2P_REG_CLIENT_EVT */
83typedef struct
84{
85    tNFA_HANDLE     client_handle;     /* NFA_HANDLE_INVALID if failed */
86} tNFA_P2P_REG_CLIENT;
87
88/* Data for NFA_P2P_ACTIVATED_EVT */
89typedef struct
90{
91    tNFA_HANDLE     handle;
92    UINT16          local_link_miu;
93    UINT16          remote_link_miu;
94} tNFA_P2P_ACTIVATED;
95
96/* Data for NFA_P2P_DEACTIVATED_EVT */
97typedef struct
98{
99    tNFA_HANDLE     handle;
100} tNFA_P2P_DEACTIVATED;
101
102/* Data for NFA_P2P_CONN_REQ_EVT */
103typedef struct
104{
105    tNFA_HANDLE     server_handle;
106    tNFA_HANDLE     conn_handle;
107    UINT8           remote_sap;
108    UINT16          remote_miu;
109    UINT8           remote_rw;
110} tNFA_P2P_CONN_REQ;
111
112/* Data for NFA_P2P_CONNECTED_EVT */
113typedef struct
114{
115    tNFA_HANDLE     client_handle;
116    tNFA_HANDLE     conn_handle;
117    UINT8           remote_sap;
118    UINT16          remote_miu;
119    UINT8           remote_rw;
120} tNFA_P2P_CONN;
121
122/* Data for NFA_P2P_DISC_EVT */
123typedef struct
124{
125    tNFA_HANDLE     handle;
126    UINT8           reason;
127} tNFA_P2P_DISC;
128
129/* Data for NFA_P2P_DATA_EVT */
130typedef struct
131{
132    tNFA_HANDLE     handle;
133    UINT8           remote_sap;
134    tNFA_P2P_LINK_TYPE link_type;
135} tNFA_P2P_DATA;
136
137/* Data for NFA_P2P_CONGEST_EVT */
138typedef struct
139{
140    tNFA_HANDLE     handle;
141    BOOLEAN         is_congested;
142    tNFA_P2P_LINK_TYPE link_type;
143} tNFA_P2P_CONGEST;
144
145/* Data for NFA_P2P_LINK_INFO_EVT */
146typedef struct
147{
148    tNFA_HANDLE     handle;
149    UINT16          wks;            /* well-known service */
150    UINT16          local_link_miu;
151    UINT16          remote_link_miu;
152} tNFA_P2P_LINK_INFO;
153
154/* Data for NFA_P2P_SDP_EVT */
155typedef struct
156{
157    tNFA_HANDLE     handle;
158    UINT8           remote_sap;     /* 0x00 if failed */
159} tNFA_P2P_SDP;
160
161/* Union of all P2P callback structures */
162typedef union
163{
164    tNFA_P2P_REG_SERVER     reg_server;     /* NFA_P2P_REG_SERVER_EVT   */
165    tNFA_P2P_REG_CLIENT     reg_client;     /* NFA_P2P_REG_CLIENT_EVT   */
166    tNFA_P2P_ACTIVATED      activated;      /* NFA_P2P_ACTIVATED_EVT    */
167    tNFA_P2P_DEACTIVATED    deactivated;    /* NFA_P2P_DEACTIVATED_EVT  */
168    tNFA_P2P_CONN_REQ       conn_req;       /* NFA_P2P_CONN_REQ_EVT     */
169    tNFA_P2P_CONN           connected;      /* NFA_P2P_CONNECTED_EVT    */
170    tNFA_P2P_DISC           disc;           /* NFA_P2P_DISC_EVT         */
171    tNFA_P2P_DATA           data;           /* NFA_P2P_DATA_EVT         */
172    tNFA_P2P_CONGEST        congest;        /* NFA_P2P_CONGEST_EVT      */
173    tNFA_P2P_LINK_INFO      link_info;      /* NFA_P2P_LINK_INFO_EVT    */
174    tNFA_P2P_SDP            sdp;            /* NFA_P2P_SDP_EVT          */
175} tNFA_P2P_EVT_DATA;
176
177/* NFA P2P callback */
178typedef void (tNFA_P2P_CBACK)(tNFA_P2P_EVT event, tNFA_P2P_EVT_DATA *p_data);
179
180/*****************************************************************************
181**  External Function Declarations
182*****************************************************************************/
183#ifdef __cplusplus
184extern "C"
185{
186#endif
187
188/*******************************************************************************
189**
190** Function         NFA_P2pRegisterServer
191**
192** Description      This function is called to listen to a SAP as server on LLCP.
193**
194**                  NFA_P2P_REG_SERVER_EVT will be returned with status and handle.
195**
196**                  If server_sap is set to NFA_P2P_ANY_SAP, then NFA will allocate
197**                  a SAP between LLCP_LOWER_BOUND_SDP_SAP and LLCP_UPPER_BOUND_SDP_SAP
198**                  Otherwise, server_sap must be between (LLCP_SDP_SAP + 1) and
199**                  LLCP_UPPER_BOUND_SDP_SAP
200**
201**                  link_type : NFA_P2P_LLINK_TYPE and/or NFA_P2P_DLINK_TYPE
202**
203** Note:            If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT
204**                  should happen before calling this function
205**
206** Returns          NFA_STATUS_OK if successfully initiated
207**                  NFA_STATUS_FAILED otherwise
208**
209*******************************************************************************/
210NFC_API extern tNFA_STATUS NFA_P2pRegisterServer (UINT8              server_sap,
211                                                  tNFA_P2P_LINK_TYPE link_type,
212                                                  char              *p_service_name,
213                                                  tNFA_P2P_CBACK    *p_cback);
214
215/*******************************************************************************
216**
217** Function         NFA_P2pRegisterClient
218**
219** Description      This function is called to register a client service on LLCP.
220**
221**                  NFA_P2P_REG_CLIENT_EVT will be returned with status and handle.
222**
223**                  link_type : NFA_P2P_LLINK_TYPE and/or NFA_P2P_DLINK_TYPE
224**
225** Returns          NFA_STATUS_OK if successfully initiated
226**                  NFA_STATUS_FAILED otherwise
227**
228*******************************************************************************/
229NFC_API extern tNFA_STATUS NFA_P2pRegisterClient (tNFA_P2P_LINK_TYPE link_type,
230                                                  tNFA_P2P_CBACK *p_cback);
231
232/*******************************************************************************
233**
234** Function         NFA_P2pDeregister
235**
236** Description      This function is called to stop listening to a SAP as server
237**                  or stop client service on LLCP.
238**
239** Note:            If this function is called to de-register a server and RF discovery
240**                  is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT
241**                  should happen before calling this function
242**
243** Returns          NFA_STATUS_OK if successfully initiated
244**                  NFA_STATUS_BAD_HANDLE if handle is not valid
245**                  NFA_STATUS_FAILED otherwise
246**
247*******************************************************************************/
248NFC_API extern tNFA_STATUS NFA_P2pDeregister (tNFA_HANDLE handle);
249
250/*******************************************************************************
251**
252** Function         NFA_P2pAcceptConn
253**
254** Description      This function is called to accept a request of data link
255**                  connection to a listening SAP on LLCP after receiving
256**                  NFA_P2P_CONN_REQ_EVT.
257**
258** Returns          NFA_STATUS_OK if successfully initiated
259**                  NFA_STATUS_BAD_HANDLE if handle is not valid
260**                  NFA_STATUS_FAILED otherwise
261**
262*******************************************************************************/
263NFC_API extern tNFA_STATUS NFA_P2pAcceptConn (tNFA_HANDLE conn_handle,
264                                              UINT16      miu,
265                                              UINT8       rw);
266
267/*******************************************************************************
268**
269** Function         NFA_P2pRejectConn
270**
271** Description      This function is called to reject a request of data link
272**                  connection to a listening SAP on LLCP after receiving
273**                  NFA_P2P_CONN_REQ_EVT.
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*******************************************************************************/
280NFC_API extern tNFA_STATUS NFA_P2pRejectConn (tNFA_HANDLE conn_handle);
281
282/*******************************************************************************
283**
284** Function         NFA_P2pDisconnect
285**
286** Description      This function is called to disconnect an existing or
287**                  connecting data link connection.
288**
289**                  discard any pending data on data link connection if flush is set to TRUE
290**
291**                  NFA_P2P_DISC_EVT will be returned after data link connection is disconnected
292**
293** Returns          NFA_STATUS_OK if successfully initiated
294**                  NFA_STATUS_BAD_HANDLE if handle is not valid
295**                  NFA_STATUS_FAILED otherwise
296**
297*******************************************************************************/
298NFC_API extern tNFA_STATUS NFA_P2pDisconnect (tNFA_HANDLE conn_handle,
299                                              BOOLEAN     flush);
300
301/*******************************************************************************
302**
303** Function         NFA_P2pConnectByName
304**
305** Description      This function is called to create a connection-oriented transport
306**                  by a service name.
307**                  NFA_P2P_CONNECTED_EVT if success
308**                  NFA_P2P_DISC_EVT if failed
309**
310** Returns          NFA_STATUS_OK if successfully initiated
311**                  NFA_STATUS_BAD_HANDLE if client is not registered
312**                  NFA_STATUS_FAILED otherwise
313**
314*******************************************************************************/
315NFC_API extern tNFA_STATUS NFA_P2pConnectByName (tNFA_HANDLE client_handle,
316                                                 char       *p_service_name,
317                                                 UINT16      miu,
318                                                 UINT8       rw);
319
320/*******************************************************************************
321**
322** Function         NFA_P2pConnectBySap
323**
324** Description      This function is called to create a connection-oriented transport
325**                  by a SAP.
326**                  NFA_P2P_CONNECTED_EVT if success
327**                  NFA_P2P_DISC_EVT if failed
328**
329** Returns          NFA_STATUS_OK if successfully initiated
330**                  NFA_STATUS_BAD_HANDLE if client is not registered
331**                  NFA_STATUS_FAILED otherwise
332**
333*******************************************************************************/
334NFC_API extern tNFA_STATUS NFA_P2pConnectBySap (tNFA_HANDLE client_handle,
335                                                UINT8       dsap,
336                                                UINT16      miu,
337                                                UINT8       rw);
338
339/*******************************************************************************
340**
341** Function         NFA_P2pSendUI
342**
343** Description      This function is called to send data on connectionless
344**                  transport.
345**
346** Returns          NFA_STATUS_OK if successfully initiated
347**                  NFA_STATUS_BAD_HANDLE if handle is not valid
348**                  NFA_STATUS_BAD_LENGTH if data length is more than remote link MIU
349**                  NFA_STATUS_CONGESTED  if congested
350**                  NFA_STATUS_FAILED otherwise
351**
352*******************************************************************************/
353NFC_API extern tNFA_STATUS NFA_P2pSendUI (tNFA_HANDLE handle,
354                                          UINT8       dsap,
355                                          UINT16      length,
356                                          UINT8      *p_data);
357
358/*******************************************************************************
359**
360** Function         NFA_P2pReadUI
361**
362** Description      This function is called to read data on connectionless
363**                  transport when receiving NFA_P2P_DATA_EVT with NFA_P2P_LLINK_TYPE.
364**
365**                  - Remote SAP who sent UI PDU is returned.
366**                  - Information of UI PDU up to max_data_len is copied into p_data.
367**                  - If more information of UI PDU or more UI PDU in queue then more
368**                    is returned to TRUE.
369**                  - Information of next UI PDU is not concatenated.
370**
371** Returns          NFA_STATUS_OK if successfully initiated
372**                  NFA_STATUS_BAD_HANDLE if handle is not valid
373**
374*******************************************************************************/
375NFC_API extern tNFA_STATUS NFA_P2pReadUI (tNFA_HANDLE handle,
376                                          UINT32      max_data_len,
377                                          UINT8       *p_remote_sap,
378                                          UINT32      *p_data_len,
379                                          UINT8       *p_data,
380                                          BOOLEAN     *p_more);
381
382/*******************************************************************************
383**
384** Function         NFA_P2pFlushUI
385**
386** Description      This function is called to flush data on connectionless
387**                  transport.
388**
389** Returns          NFA_STATUS_OK if successfully initiated
390**                  NFA_STATUS_BAD_HANDLE if handle is not valid
391**
392*******************************************************************************/
393NFC_API extern tNFA_STATUS NFA_P2pFlushUI (tNFA_HANDLE handle,
394                                           UINT32      *p_length);
395
396/*******************************************************************************
397**
398** Function         NFA_P2pSendData
399**
400** Description      This function is called to send data on connection-oriented
401**                  transport.
402**
403** Returns          NFA_STATUS_OK if successfully initiated
404**                  NFA_STATUS_BAD_HANDLE if handle is not valid
405**                  NFA_STATUS_BAD_LENGTH if data length is more than remote MIU
406**                  NFA_STATUS_CONGESTED  if congested
407**                  NFA_STATUS_FAILED otherwise
408**
409*******************************************************************************/
410NFC_API extern tNFA_STATUS NFA_P2pSendData (tNFA_HANDLE conn_handle,
411                                            UINT16      length,
412                                            UINT8      *p_data);
413
414/*******************************************************************************
415**
416** Function         NFA_P2pReadData
417**
418** Description      This function is called to read data on connection-oriented
419**                  transport when receiving NFA_P2P_DATA_EVT with NFA_P2P_DLINK_TYPE.
420**
421**                  - Information of I PDU is copied into p_data up to max_data_len.
422**                  - If more information of I PDU or more I PDU in queue, then more
423**                    is returned to TRUE.
424**                  - Information of next I PDU is not concatenated.
425**
426** Returns          NFA_STATUS_OK if successfully initiated
427**                  NFA_STATUS_BAD_HANDLE if handle is not valid
428**
429*******************************************************************************/
430NFC_API extern tNFA_STATUS NFA_P2pReadData (tNFA_HANDLE handle,
431                                            UINT32      max_data_len,
432                                            UINT32      *p_data_len,
433                                            UINT8       *p_data,
434                                            BOOLEAN     *p_more);
435
436/*******************************************************************************
437**
438** Function         NFA_P2pFlushData
439**
440** Description      This function is called to flush data on connection-oriented
441**                  transport.
442**
443** Returns          NFA_STATUS_OK if successfully initiated
444**                  NFA_STATUS_BAD_HANDLE if handle is not valid
445**
446*******************************************************************************/
447NFC_API extern tNFA_STATUS NFA_P2pFlushData (tNFA_HANDLE handle,
448                                             UINT32      *p_length);
449
450/*******************************************************************************
451**
452** Function         NFA_P2pSetLocalBusy
453**
454** Description      This function is called to stop or resume incoming data on
455**                  connection-oriented transport.
456**
457** Returns          NFA_STATUS_OK if successfully initiated
458**                  NFA_STATUS_BAD_HANDLE if handle is not valid
459**                  NFA_STATUS_FAILED otherwise
460**
461*******************************************************************************/
462NFC_API extern tNFA_STATUS NFA_P2pSetLocalBusy (tNFA_HANDLE conn_handle,
463                                                BOOLEAN     is_busy);
464
465/*******************************************************************************
466**
467** Function         NFA_P2pGetLinkInfo
468**
469** Description      This function is called to get local/remote link MIU and
470**                  Well-Known Service list encoded as a 16-bit field of connected LLCP.
471**                  NFA_P2P_LINK_INFO_EVT will be returned.
472**
473** Returns          NFA_STATUS_OK if successfully initiated
474**                  NFA_STATUS_BAD_HANDLE if server or client is not registered
475**                  NFA_STATUS_FAILED otherwise
476**
477*******************************************************************************/
478NFC_API extern tNFA_STATUS NFA_P2pGetLinkInfo (tNFA_HANDLE handle);
479
480/*******************************************************************************
481**
482** Function         NFA_P2pGetRemoteSap
483**
484** Description      This function is called to get SAP associated by service name
485**                  on connected remote LLCP.
486**                  NFA_P2P_SDP_EVT will be returned.
487**
488** Returns          NFA_STATUS_OK if successfully initiated
489**                  NFA_STATUS_BAD_HANDLE if server or client is not registered
490**                  NFA_STATUS_FAILED otherwise
491**
492*******************************************************************************/
493NFC_API extern tNFA_STATUS NFA_P2pGetRemoteSap (tNFA_HANDLE handle,
494                                                char       *p_service_name);
495
496/*******************************************************************************
497**
498** Function         NFA_P2pSetLLCPConfig
499**
500** Description      This function is called to change LLCP config parameters.
501**                  Application must call while LLCP is not activated.
502**
503**                  Parameters descriptions (default value)
504**                  - Local Link MIU (LLCP_MIU)
505**                  - Option parameter (LLCP_OPT_VALUE)
506**                  - Response Waiting Time Index (LLCP_WAITING_TIME)
507**                  - Local Link Timeout (LLCP_LTO_VALUE)
508**                  - Inactivity Timeout as initiator role (LLCP_INIT_INACTIVITY_TIMEOUT)
509**                  - Inactivity Timeout as target role (LLCP_TARGET_INACTIVITY_TIMEOUT)
510**                  - Delay SYMM response (LLCP_DELAY_RESP_TIME)
511**                  - Data link connection timeout (LLCP_DATA_LINK_CONNECTION_TOUT)
512**                  - Delay timeout to send first PDU as initiator (LLCP_DELAY_TIME_TO_SEND_FIRST_PDU)
513**
514** Returns          NFA_STATUS_OK if successfully initiated
515**                  NFA_STATUS_FAILED otherwise
516**
517*******************************************************************************/
518NFC_API extern tNFA_STATUS NFA_P2pSetLLCPConfig (UINT16 link_miu,
519                                                 UINT8  opt,
520                                                 UINT8  wt,
521                                                 UINT16 link_timeout,
522                                                 UINT16 inact_timeout_init,
523                                                 UINT16 inact_timeout_target,
524                                                 UINT16 symm_delay,
525                                                 UINT16 data_link_timeout,
526                                                 UINT16 delay_first_pdu_timeout);
527
528/*******************************************************************************
529**
530** Function         NFA_P2pGetLLCPConfig
531**
532** Description      This function is called to read LLCP config parameters.
533**
534**                  Parameters descriptions
535**                  - Local Link MIU
536**                  - Option parameter
537**                  - Response Waiting Time Index
538**                  - Local Link Timeout
539**                  - Inactivity Timeout as initiator role
540**                  - Inactivity Timeout as target role
541**                  - Delay SYMM response
542**                  - Data link connection timeout
543**                  - Delay timeout to send first PDU as initiator
544**
545** Returns          None
546**
547*******************************************************************************/
548NFC_API extern void NFA_P2pGetLLCPConfig (UINT16 *p_link_miu,
549                                          UINT8  *p_opt,
550                                          UINT8  *p_wt,
551                                          UINT16 *p_link_timeout,
552                                          UINT16 *p_inact_timeout_init,
553                                          UINT16 *p_inact_timeout_target,
554                                          UINT16 *p_symm_delay,
555                                          UINT16 *p_data_link_timeout,
556                                          UINT16 *p_delay_first_pdu_timeout);
557
558/*******************************************************************************
559**
560** Function         NFA_P2pSetTraceLevel
561**
562** Description      This function sets the trace level for P2P.  If called with
563**                  a value of 0xFF, it simply returns the current trace level.
564**
565** Returns          The new or current trace level
566**
567*******************************************************************************/
568NFC_API extern UINT8 NFA_P2pSetTraceLevel (UINT8 new_level);
569
570#ifdef __cplusplus
571}
572#endif
573
574#endif /* NFA_P2P_API_H */
575
576