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