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