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 54 typedef UINT8 tNFA_CHO_EVT; 55 56 /* 57 ** Data for NFA_CHO_ACTIVATED_EVT 58 */ 59 typedef 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 70 typedef UINT8 tNFA_CHO_CPS; 71 72 /* Data for Alternative Carrier Information */ 73 typedef 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 84 typedef UINT8 tNFA_CHO_ROLE_TYPE; 85 86 /* 87 ** Data for NFA_CHO_CONNECTED_EVT 88 */ 89 typedef 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 107 typedef UINT8 tNFA_CHO_DISC_REASON; 108 109 /* 110 ** Data for NFA_CHO_DISCONNECTED_EVT 111 */ 112 typedef struct 113 { 114 tNFA_CHO_DISC_REASON reason; /* disconnected reason */ 115 } tNFA_CHO_DISCONNECTED; 116 117 /* Reference ID */ 118 typedef 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 */ 125 typedef 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 */ 137 typedef 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 */ 149 typedef 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 */ 166 typedef 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 */ 173 typedef 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 */ 187 typedef void (tNFA_CHO_CBACK) (tNFA_CHO_EVT event, tNFA_CHO_EVT_DATA *p_data); 188 189 /***************************************************************************** 190 ** External Function Declarations 191 *****************************************************************************/ 192 #ifdef __cplusplus 193 extern "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 *******************************************************************************/ 216 NFC_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 *******************************************************************************/ 237 NFC_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 *******************************************************************************/ 254 NFC_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 *******************************************************************************/ 269 NFC_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 *******************************************************************************/ 294 NFC_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 *******************************************************************************/ 317 NFC_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 *******************************************************************************/ 337 NFC_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 *******************************************************************************/ 350 NFC_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 *******************************************************************************/ 363 NFC_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