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 53 typedef UINT8 tNFA_CHO_EVT; 54 55 /* 56 ** Data for NFA_CHO_ACTIVATED_EVT 57 */ 58 typedef 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 69 typedef UINT8 tNFA_CHO_CPS; 70 71 /* Data for Alternative Carrier Information */ 72 typedef 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 83 typedef UINT8 tNFA_CHO_ROLE_TYPE; 84 85 /* 86 ** Data for NFA_CHO_CONNECTED_EVT 87 */ 88 typedef 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 106 typedef UINT8 tNFA_CHO_DISC_REASON; 107 108 /* 109 ** Data for NFA_CHO_DISCONNECTED_EVT 110 */ 111 typedef struct 112 { 113 tNFA_CHO_DISC_REASON reason; /* disconnected reason */ 114 } tNFA_CHO_DISCONNECTED; 115 116 /* Reference ID */ 117 typedef 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 */ 124 typedef 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 */ 136 typedef 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 */ 148 typedef 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 */ 165 typedef 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 */ 172 typedef 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 */ 186 typedef void (tNFA_CHO_CBACK) (tNFA_CHO_EVT event, tNFA_CHO_EVT_DATA *p_data); 187 188 /***************************************************************************** 189 ** External Function Declarations 190 *****************************************************************************/ 191 #ifdef __cplusplus 192 extern "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 *******************************************************************************/ 215 NFC_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 *******************************************************************************/ 236 NFC_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 *******************************************************************************/ 253 NFC_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 *******************************************************************************/ 268 NFC_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 *******************************************************************************/ 293 NFC_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 *******************************************************************************/ 316 NFC_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 *******************************************************************************/ 336 NFC_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 *******************************************************************************/ 349 NFC_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 *******************************************************************************/ 362 NFC_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