nfa_cho_api.h revision e9629bad30a9f478b336ab46b8e6e02f7f87af46
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 Connection Handover,
23 *  Broadcom's NFC application layer for mobile phones.
24 *
25 ******************************************************************************/
26#ifndef NFA_CHO_API_H
27#define NFA_CHO_API_H
28
29#include "nfa_api.h"
30#include "ndef_utils.h"
31
32/*****************************************************************************
33**  Constants and data types
34*****************************************************************************/
35
36/* Handover version */
37#define NFA_CHO_VERSION             0x12    /* version 1.2 */
38#define NFA_CHO_GET_MAJOR_VERSION(x) ((UINT8)(x) >> 4)
39#define NFA_CHO_GET_MINOR_VERSION(x) ((UINT8)(x) & 0x0F)
40
41/*
42** NFA Connection Handover callback events
43*/
44#define NFA_CHO_REG_EVT             0x00    /* Registered                       */
45#define NFA_CHO_ACTIVATED_EVT       0x01    /* LLCP link activated              */
46#define NFA_CHO_DEACTIVATED_EVT     0x02    /* LLCP link deactivated            */
47#define NFA_CHO_CONNECTED_EVT       0x03    /* data link connected              */
48#define NFA_CHO_DISCONNECTED_EVT    0x04    /* data link disconnected           */
49#define NFA_CHO_REQUEST_EVT         0x05    /* AC information in "Hr" record    */
50#define NFA_CHO_SELECT_EVT          0x06    /* AC information in "Hs" record    */
51#define NFA_CHO_SEL_ERR_EVT         0x07    /* Received select with error       */
52#define NFA_CHO_TX_FAIL_EVT         0x08    /* Cannot send message to peer      */
53
54typedef UINT8 tNFA_CHO_EVT;
55
56/*
57** Data for NFA_CHO_ACTIVATED_EVT
58*/
59typedef struct
60{
61    BOOLEAN         is_initiator;   /* TRUE if local LLCP is initiator */
62} tNFA_CHO_ACTIVATED;
63
64/* NFA Connection Handover Carrier Power State */
65#define NFA_CHO_CPS_INACTIVE        0x00    /* Carrier is currently off         */
66#define NFA_CHO_CPS_ACTIVE          0x01    /* Carrier is currently on          */
67#define NFA_CHO_CPS_ACTIVATING      0x02    /* Activating carrier               */
68#define NFA_CHO_CPS_UNKNOWN         0x03    /* Unknown                          */
69
70typedef UINT8 tNFA_CHO_CPS;
71
72/* Data for Alternative Carrier Information */
73typedef struct
74{
75    tNFA_CHO_CPS        cps;            /* carrier power state                      */
76    UINT8               num_aux_data;   /* number of Auxiliary NDEF records         */
77} tNFA_CHO_AC_INFO;
78
79/* Device Role of Handover */
80#define NFA_CHO_ROLE_REQUESTER  0
81#define NFA_CHO_ROLE_SELECTOR   1
82#define NFA_CHO_ROLE_UNDECIDED  2
83
84typedef UINT8 tNFA_CHO_ROLE_TYPE;
85
86/*
87** Data for NFA_CHO_CONNECTED_EVT
88*/
89typedef struct
90{
91    tNFA_CHO_ROLE_TYPE  initial_role;   /* NFA_CHO_ROLE_REQUESTER if local initiated */
92                                        /* NFA_CHO_ROLE_SELECTOR if remote initiated */
93} tNFA_CHO_CONNECTED;
94
95/* Disconnected reason */
96#define NFA_CHO_DISC_REASON_API_REQUEST         0
97#define NFA_CHO_DISC_REASON_ALEADY_CONNECTED    1
98#define NFA_CHO_DISC_REASON_CONNECTION_FAIL     2
99#define NFA_CHO_DISC_REASON_PEER_REQUEST        3
100#define NFA_CHO_DISC_REASON_LINK_DEACTIVATED    4
101#define NFA_CHO_DISC_REASON_TIMEOUT             5
102#define NFA_CHO_DISC_REASON_UNKNOWN_MSG         6
103#define NFA_CHO_DISC_REASON_INVALID_MSG         7
104#define NFA_CHO_DISC_REASON_SEMANTIC_ERROR      8
105#define NFA_CHO_DISC_REASON_INTERNAL_ERROR      9
106
107typedef UINT8 tNFA_CHO_DISC_REASON;
108
109/*
110** Data for NFA_CHO_DISCONNECTED_EVT
111*/
112typedef struct
113{
114    tNFA_CHO_DISC_REASON    reason;     /* disconnected reason */
115} tNFA_CHO_DISCONNECTED;
116
117/* Reference ID */
118typedef struct
119{
120    UINT8               ref_len;
121    UINT8               ref_name[NFA_CHO_MAX_REF_NAME_LEN];
122} tNFA_CHO_REF_ID;
123
124/* Alternative Carrier records including carrier power state, carrier data reference and aux data reference */
125typedef struct
126{
127    tNFA_CHO_CPS        cps;                                      /* carrier power state    */
128    tNFA_CHO_REF_ID     carrier_data_ref;                         /* carrier data reference */
129    UINT8               aux_data_ref_count;                       /* number of aux data     */
130    tNFA_CHO_REF_ID     aux_data_ref[NFA_CHO_MAX_AUX_DATA_COUNT]; /* aux data reference     */
131} tNFA_CHO_AC_REC;
132
133/*
134** Data for NFA_CHO_REQUEST_EVT
135** Application may receive it while waiting for NFA_CHO_SELECT_EVT because of handover collision.
136*/
137typedef struct
138{
139    tNFA_STATUS         status;
140    UINT8               num_ac_rec;                     /* number of Alternative Carrier records*/
141    tNFA_CHO_AC_REC     ac_rec[NFA_CHO_MAX_AC_INFO];    /* Alternative Carrier records          */
142    UINT8               *p_ref_ndef;                    /* pointer of NDEF including AC records */
143    UINT32              ref_ndef_len;                   /* length of NDEF                       */
144} tNFA_CHO_REQUEST;
145
146/*
147** Data for NFA_CHO_SELECT_EVT
148*/
149typedef struct
150{
151    tNFA_STATUS         status;
152    UINT8               num_ac_rec;                     /* number of Alternative Carrier records*/
153    tNFA_CHO_AC_REC     ac_rec[NFA_CHO_MAX_AC_INFO];    /* Alternative Carrier records          */
154    UINT8               *p_ref_ndef;                    /* pointer of NDEF including AC records */
155    UINT32              ref_ndef_len;                   /* length of NDEF                       */
156} tNFA_CHO_SELECT;
157
158/* Error reason */
159#define NFA_CHO_ERROR_TEMP_MEM  0x01
160#define NFA_CHO_ERROR_PERM_MEM  0x02
161#define NFA_CHO_ERROR_CARRIER   0x03
162
163/*
164** Data for NFA_CHO_SEL_ERR_EVT
165*/
166typedef struct
167{
168    UINT8               error_reason;   /* Error reason          */
169    UINT32              error_data;     /* Error Data per reason */
170} tNFA_CHO_SEL_ERR;
171
172/* Union of all Connection Handover callback structures */
173typedef union
174{
175    tNFA_STATUS             status;         /* NFA_CHO_REG_EVT          */
176                                            /* NFA_CHO_DEACTIVATED_EVT  */
177                                            /* NFA_CHO_TX_FAIL_EVT      */
178    tNFA_CHO_ACTIVATED      activated;      /* NFA_CHO_ACTIVATED_EVT    */
179    tNFA_CHO_CONNECTED      connected;      /* NFA_CHO_CONNECTED_EVT    */
180    tNFA_CHO_DISCONNECTED   disconnected;   /* NFA_CHO_DISCONNECTED_EVT */
181    tNFA_CHO_SELECT         select;         /* NFA_CHO_SELECT_EVT       */
182    tNFA_CHO_REQUEST        request;        /* NFA_CHO_REQUEST_EVT      */
183    tNFA_CHO_SEL_ERR        sel_err;        /* NFA_CHO_SEL_ERR_EVT      */
184} tNFA_CHO_EVT_DATA;
185
186/* NFA Connection Handover callback */
187typedef void (tNFA_CHO_CBACK) (tNFA_CHO_EVT event, tNFA_CHO_EVT_DATA *p_data);
188
189/*****************************************************************************
190**  External Function Declarations
191*****************************************************************************/
192#ifdef __cplusplus
193extern "C"
194{
195#endif
196
197/*******************************************************************************
198**
199** Function         NFA_ChoRegister
200**
201** Description      This function is called to register callback function to receive
202**                  connection handover events.
203**
204**                  On this registration, "urn:nfc:sn:handover" server will be
205**                  registered on LLCP if enable_server is TRUE.
206**
207**                  The result of the registration is reported with NFA_CHO_REG_EVT.
208**
209** Note:            If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT
210**                  should happen before calling this function
211**
212** Returns          NFA_STATUS_OK if successfully initiated
213**                  NFA_STATUS_FAILED otherwise
214**
215*******************************************************************************/
216NFC_API extern tNFA_STATUS NFA_ChoRegister (BOOLEAN        enable_server,
217                                            tNFA_CHO_CBACK *p_cback);
218
219/*******************************************************************************
220**
221** Function         NFA_ChoDeregister
222**
223** Description      This function is called to deregister callback function from NFA
224**                  Connection Handover Application.
225**
226**                  If this is the valid deregistration, NFA Connection Handover
227**                  Application will close the service with "urn:nfc:sn:handover"
228**                  on LLCP and deregister NDEF type handler if any.
229**
230** Note:            If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT
231**                  should happen before calling this function
232**
233** Returns          NFA_STATUS_OK if successfully initiated
234**                  NFA_STATUS_FAILED otherwise
235**
236*******************************************************************************/
237NFC_API extern tNFA_STATUS NFA_ChoDeregister (void);
238
239/*******************************************************************************
240**
241** Function         NFA_ChoConnect
242**
243** Description      This function is called to create data link connection to
244**                  Connection Handover server on peer device.
245**
246**                  It must be called after receiving NFA_CHO_ACTIVATED_EVT.
247**                  NFA_CHO_CONNECTED_EVT will be returned if successful.
248**                  Otherwise, NFA_CHO_DISCONNECTED_EVT will be returned.
249**
250** Returns          NFA_STATUS_OK if successfully initiated
251**                  NFA_STATUS_FAILED otherwise
252**
253*******************************************************************************/
254NFC_API extern tNFA_STATUS NFA_ChoConnect (void);
255
256/*******************************************************************************
257**
258** Function         NFA_ChoDisconnect
259**
260** Description      This function is called to disconnect data link connection with
261**                  Connection Handover server on peer device.
262**
263**                  NFA_CHO_DISCONNECTED_EVT will be returned.
264**
265** Returns          NFA_STATUS_OK if successfully initiated
266**                  NFA_STATUS_FAILED otherwise
267**
268*******************************************************************************/
269NFC_API extern tNFA_STATUS NFA_ChoDisconnect (void);
270
271/*******************************************************************************
272**
273** Function         NFA_ChoSendHr
274**
275** Description      This function is called to send Handover Request Message with
276**                  Handover Carrier records or Alternative Carrier records.
277**
278**                  It must be called after receiving NFA_CHO_CONNECTED_EVT.
279**
280**                  NDEF may include one or more Handover Carrier records or Alternative
281**                  Carrier records with auxiliary data.
282**                  The records in NDEF must be matched with tNFA_CHO_AC_INFO in order.
283**                  Payload ID must be unique and Payload ID length must be less than
284**                  or equal to NFA_CHO_MAX_REF_NAME_LEN.
285**
286**                  The alternative carrier information of Handover Select record
287**                  will be sent to application by NFA_CHO_SELECT_EVT. Application
288**                  may receive NFA_CHO_REQUEST_EVT because of handover collision.
289**
290** Returns          NFA_STATUS_OK if successfully initiated
291**                  NFA_STATUS_FAILED otherwise
292**
293*******************************************************************************/
294NFC_API extern tNFA_STATUS NFA_ChoSendHr (UINT8             num_ac_info,
295                                          tNFA_CHO_AC_INFO *p_ac_info,
296                                          UINT8            *p_ndef,
297                                          UINT32            ndef_len);
298
299/*******************************************************************************
300**
301** Function         NFA_ChoSendHs
302**
303** Description      This function is called to send Handover Select message with
304**                  Alternative Carrier records as response to Handover Request
305**                  message.
306**
307**                  NDEF may include one or more Alternative Carrier records with
308**                  auxiliary data.
309**                  The records in NDEF must be matched with tNFA_CHO_AC_INFO in order.
310**                  Payload ID must be unique and Payload ID length must be less than
311**                  or equal to NFA_CHO_MAX_REF_NAME_LEN.
312**
313** Returns          NFA_STATUS_OK if successfully initiated
314**                  NFA_STATUS_FAILED otherwise
315**
316*******************************************************************************/
317NFC_API extern tNFA_STATUS NFA_ChoSendHs (UINT8             num_ac_info,
318                                          tNFA_CHO_AC_INFO *p_ac_info,
319                                          UINT8            *p_ndef,
320                                          UINT32            ndef_len);
321
322/*******************************************************************************
323**
324** Function         NFA_ChoSendSelectError
325**
326** Description      This function is called to send Error record to indicate failure
327**                  to process the most recently received Handover Request message.
328**
329**                  error_reason : NFA_CHO_ERROR_TEMP_MEM
330**                                 NFA_CHO_ERROR_PERM_MEM
331**                                 NFA_CHO_ERROR_CARRIER
332**
333** Returns          NFA_STATUS_OK if successfully initiated
334**                  NFA_STATUS_FAILED otherwise
335**
336*******************************************************************************/
337NFC_API extern tNFA_STATUS NFA_ChoSendSelectError (UINT8  error_reason,
338                                                   UINT32 error_data);
339
340/*******************************************************************************
341**
342** Function         NFA_ChoSetTraceLevel
343**
344** Description      This function sets the trace level for CHO.  If called with
345**                  a value of 0xFF, it simply returns the current trace level.
346**
347** Returns          The new or current trace level
348**
349*******************************************************************************/
350NFC_API extern UINT8 NFA_ChoSetTraceLevel (UINT8 new_level);
351
352#if (defined (NFA_CHO_TEST_INCLUDED) && (NFA_CHO_TEST_INCLUDED == TRUE))
353
354#define NFA_CHO_TEST_VERSION    0x01
355#define NFA_CHO_TEST_RANDOM     0x02
356/*******************************************************************************
357**
358** Function         NFA_ChoSetTestParam
359**
360** Description      This function is called to set test parameters.
361**
362*******************************************************************************/
363NFC_API extern void NFA_ChoSetTestParam (UINT8  test_enable,
364                                         UINT8  test_version,
365                                         UINT16 test_random_number);
366#endif
367
368#ifdef __cplusplus
369}
370#endif
371
372#endif /* NFA_CHO_API_H */
373
374