/******************************************************************************
*
* Copyright (C) 2010-2014 Broadcom Corporation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
******************************************************************************/
/******************************************************************************
*
* This is the public interface file for NFA Connection Handover,
* Broadcom's NFC application layer for mobile phones.
*
******************************************************************************/
#ifndef NFA_CHO_API_H
#define NFA_CHO_API_H
#include "nfa_api.h"
#include "ndef_utils.h"
/*****************************************************************************
** Constants and data types
*****************************************************************************/
/* Handover version */
#define NFA_CHO_VERSION 0x12 /* version 1.2 */
#define NFA_CHO_GET_MAJOR_VERSION(x) ((UINT8)(x) >> 4)
#define NFA_CHO_GET_MINOR_VERSION(x) ((UINT8)(x) & 0x0F)
/*
** NFA Connection Handover callback events
*/
#define NFA_CHO_REG_EVT 0x00 /* Registered */
#define NFA_CHO_ACTIVATED_EVT 0x01 /* LLCP link activated */
#define NFA_CHO_DEACTIVATED_EVT 0x02 /* LLCP link deactivated */
#define NFA_CHO_CONNECTED_EVT 0x03 /* data link connected */
#define NFA_CHO_DISCONNECTED_EVT 0x04 /* data link disconnected */
#define NFA_CHO_REQUEST_EVT 0x05 /* AC information in "Hr" record */
#define NFA_CHO_SELECT_EVT 0x06 /* AC information in "Hs" record */
#define NFA_CHO_SEL_ERR_EVT 0x07 /* Received select with error */
#define NFA_CHO_TX_FAIL_EVT 0x08 /* Cannot send message to peer */
typedef UINT8 tNFA_CHO_EVT;
/*
** Data for NFA_CHO_ACTIVATED_EVT
*/
typedef struct
{
BOOLEAN is_initiator; /* TRUE if local LLCP is initiator */
} tNFA_CHO_ACTIVATED;
/* NFA Connection Handover Carrier Power State */
#define NFA_CHO_CPS_INACTIVE 0x00 /* Carrier is currently off */
#define NFA_CHO_CPS_ACTIVE 0x01 /* Carrier is currently on */
#define NFA_CHO_CPS_ACTIVATING 0x02 /* Activating carrier */
#define NFA_CHO_CPS_UNKNOWN 0x03 /* Unknown */
typedef UINT8 tNFA_CHO_CPS;
/* Data for Alternative Carrier Information */
typedef struct
{
tNFA_CHO_CPS cps; /* carrier power state */
UINT8 num_aux_data; /* number of Auxiliary NDEF records */
} tNFA_CHO_AC_INFO;
/* Device Role of Handover */
#define NFA_CHO_ROLE_REQUESTER 0
#define NFA_CHO_ROLE_SELECTOR 1
#define NFA_CHO_ROLE_UNDECIDED 2
typedef UINT8 tNFA_CHO_ROLE_TYPE;
/*
** Data for NFA_CHO_CONNECTED_EVT
*/
typedef struct
{
tNFA_CHO_ROLE_TYPE initial_role; /* NFA_CHO_ROLE_REQUESTER if local initiated */
/* NFA_CHO_ROLE_SELECTOR if remote initiated */
} tNFA_CHO_CONNECTED;
/* Disconnected reason */
#define NFA_CHO_DISC_REASON_API_REQUEST 0
#define NFA_CHO_DISC_REASON_ALEADY_CONNECTED 1
#define NFA_CHO_DISC_REASON_CONNECTION_FAIL 2
#define NFA_CHO_DISC_REASON_PEER_REQUEST 3
#define NFA_CHO_DISC_REASON_LINK_DEACTIVATED 4
#define NFA_CHO_DISC_REASON_TIMEOUT 5
#define NFA_CHO_DISC_REASON_UNKNOWN_MSG 6
#define NFA_CHO_DISC_REASON_INVALID_MSG 7
#define NFA_CHO_DISC_REASON_SEMANTIC_ERROR 8
#define NFA_CHO_DISC_REASON_INTERNAL_ERROR 9
typedef UINT8 tNFA_CHO_DISC_REASON;
/*
** Data for NFA_CHO_DISCONNECTED_EVT
*/
typedef struct
{
tNFA_CHO_DISC_REASON reason; /* disconnected reason */
} tNFA_CHO_DISCONNECTED;
/* Reference ID */
typedef struct
{
UINT8 ref_len;
UINT8 ref_name[NFA_CHO_MAX_REF_NAME_LEN];
} tNFA_CHO_REF_ID;
/* Alternative Carrier records including carrier power state, carrier data reference and aux data reference */
typedef struct
{
tNFA_CHO_CPS cps; /* carrier power state */
tNFA_CHO_REF_ID carrier_data_ref; /* carrier data reference */
UINT8 aux_data_ref_count; /* number of aux data */
tNFA_CHO_REF_ID aux_data_ref[NFA_CHO_MAX_AUX_DATA_COUNT]; /* aux data reference */
} tNFA_CHO_AC_REC;
/*
** Data for NFA_CHO_REQUEST_EVT
** Application may receive it while waiting for NFA_CHO_SELECT_EVT because of handover collision.
*/
typedef struct
{
tNFA_STATUS status;
UINT8 num_ac_rec; /* number of Alternative Carrier records*/
tNFA_CHO_AC_REC ac_rec[NFA_CHO_MAX_AC_INFO]; /* Alternative Carrier records */
UINT8 *p_ref_ndef; /* pointer of NDEF including AC records */
UINT32 ref_ndef_len; /* length of NDEF */
} tNFA_CHO_REQUEST;
/*
** Data for NFA_CHO_SELECT_EVT
*/
typedef struct
{
tNFA_STATUS status;
UINT8 num_ac_rec; /* number of Alternative Carrier records*/
tNFA_CHO_AC_REC ac_rec[NFA_CHO_MAX_AC_INFO]; /* Alternative Carrier records */
UINT8 *p_ref_ndef; /* pointer of NDEF including AC records */
UINT32 ref_ndef_len; /* length of NDEF */
} tNFA_CHO_SELECT;
/* Error reason */
#define NFA_CHO_ERROR_TEMP_MEM 0x01
#define NFA_CHO_ERROR_PERM_MEM 0x02
#define NFA_CHO_ERROR_CARRIER 0x03
/*
** Data for NFA_CHO_SEL_ERR_EVT
*/
typedef struct
{
UINT8 error_reason; /* Error reason */
UINT32 error_data; /* Error Data per reason */
} tNFA_CHO_SEL_ERR;
/* Union of all Connection Handover callback structures */
typedef union
{
tNFA_STATUS status; /* NFA_CHO_REG_EVT */
/* NFA_CHO_DEACTIVATED_EVT */
/* NFA_CHO_TX_FAIL_EVT */
tNFA_CHO_ACTIVATED activated; /* NFA_CHO_ACTIVATED_EVT */
tNFA_CHO_CONNECTED connected; /* NFA_CHO_CONNECTED_EVT */
tNFA_CHO_DISCONNECTED disconnected; /* NFA_CHO_DISCONNECTED_EVT */
tNFA_CHO_SELECT select; /* NFA_CHO_SELECT_EVT */
tNFA_CHO_REQUEST request; /* NFA_CHO_REQUEST_EVT */
tNFA_CHO_SEL_ERR sel_err; /* NFA_CHO_SEL_ERR_EVT */
} tNFA_CHO_EVT_DATA;
/* NFA Connection Handover callback */
typedef void (tNFA_CHO_CBACK) (tNFA_CHO_EVT event, tNFA_CHO_EVT_DATA *p_data);
/*****************************************************************************
** External Function Declarations
*****************************************************************************/
#ifdef __cplusplus
extern "C"
{
#endif
/*******************************************************************************
**
** Function NFA_ChoRegister
**
** Description This function is called to register callback function to receive
** connection handover events.
**
** On this registration, "urn:nfc:sn:handover" server will be
** registered on LLCP if enable_server is TRUE.
**
** The result of the registration is reported with NFA_CHO_REG_EVT.
**
** Note: If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT
** should happen before calling this function
**
** Returns NFA_STATUS_OK if successfully initiated
** NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_ChoRegister (BOOLEAN enable_server,
tNFA_CHO_CBACK *p_cback);
/*******************************************************************************
**
** Function NFA_ChoDeregister
**
** Description This function is called to deregister callback function from NFA
** Connection Handover Application.
**
** If this is the valid deregistration, NFA Connection Handover
** Application will close the service with "urn:nfc:sn:handover"
** on LLCP and deregister NDEF type handler if any.
**
** Note: If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT
** should happen before calling this function
**
** Returns NFA_STATUS_OK if successfully initiated
** NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_ChoDeregister (void);
/*******************************************************************************
**
** Function NFA_ChoConnect
**
** Description This function is called to create data link connection to
** Connection Handover server on peer device.
**
** It must be called after receiving NFA_CHO_ACTIVATED_EVT.
** NFA_CHO_CONNECTED_EVT will be returned if successful.
** Otherwise, NFA_CHO_DISCONNECTED_EVT will be returned.
**
** Returns NFA_STATUS_OK if successfully initiated
** NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_ChoConnect (void);
/*******************************************************************************
**
** Function NFA_ChoDisconnect
**
** Description This function is called to disconnect data link connection with
** Connection Handover server on peer device.
**
** NFA_CHO_DISCONNECTED_EVT will be returned.
**
** Returns NFA_STATUS_OK if successfully initiated
** NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_ChoDisconnect (void);
/*******************************************************************************
**
** Function NFA_ChoSendHr
**
** Description This function is called to send Handover Request Message with
** Handover Carrier records or Alternative Carrier records.
**
** It must be called after receiving NFA_CHO_CONNECTED_EVT.
**
** NDEF may include one or more Handover Carrier records or Alternative
** Carrier records with auxiliary data.
** The records in NDEF must be matched with tNFA_CHO_AC_INFO in order.
** Payload ID must be unique and Payload ID length must be less than
** or equal to NFA_CHO_MAX_REF_NAME_LEN.
**
** The alternative carrier information of Handover Select record
** will be sent to application by NFA_CHO_SELECT_EVT. Application
** may receive NFA_CHO_REQUEST_EVT because of handover collision.
**
** Returns NFA_STATUS_OK if successfully initiated
** NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_ChoSendHr (UINT8 num_ac_info,
tNFA_CHO_AC_INFO *p_ac_info,
UINT8 *p_ndef,
UINT32 ndef_len);
/*******************************************************************************
**
** Function NFA_ChoSendHs
**
** Description This function is called to send Handover Select message with
** Alternative Carrier records as response to Handover Request
** message.
**
** NDEF may include one or more Alternative Carrier records with
** auxiliary data.
** The records in NDEF must be matched with tNFA_CHO_AC_INFO in order.
** Payload ID must be unique and Payload ID length must be less than
** or equal to NFA_CHO_MAX_REF_NAME_LEN.
**
** Returns NFA_STATUS_OK if successfully initiated
** NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_ChoSendHs (UINT8 num_ac_info,
tNFA_CHO_AC_INFO *p_ac_info,
UINT8 *p_ndef,
UINT32 ndef_len);
/*******************************************************************************
**
** Function NFA_ChoSendSelectError
**
** Description This function is called to send Error record to indicate failure
** to process the most recently received Handover Request message.
**
** error_reason : NFA_CHO_ERROR_TEMP_MEM
** NFA_CHO_ERROR_PERM_MEM
** NFA_CHO_ERROR_CARRIER
**
** Returns NFA_STATUS_OK if successfully initiated
** NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_ChoSendSelectError (UINT8 error_reason,
UINT32 error_data);
/*******************************************************************************
**
** Function NFA_ChoSetTraceLevel
**
** Description This function sets the trace level for CHO. If called with
** a value of 0xFF, it simply returns the current trace level.
**
** Returns The new or current trace level
**
*******************************************************************************/
NFC_API extern UINT8 NFA_ChoSetTraceLevel (UINT8 new_level);
#if (defined (NFA_CHO_TEST_INCLUDED) && (NFA_CHO_TEST_INCLUDED == TRUE))
#define NFA_CHO_TEST_VERSION 0x01
#define NFA_CHO_TEST_RANDOM 0x02
/*******************************************************************************
**
** Function NFA_ChoSetTestParam
**
** Description This function is called to set test parameters.
**
*******************************************************************************/
NFC_API extern void NFA_ChoSetTestParam (UINT8 test_enable,
UINT8 test_version,
UINT16 test_random_number);
#endif
#ifdef __cplusplus
}
#endif
#endif /* NFA_CHO_API_H */