common

NFC HAL通用模块提供NFC硬件抽象层的核心接口，包括NFC芯片的上电初始化、NCI协议命令交互、RF轮询发现、数据收发、低功耗管理、NFCEE发现与激活等功能。该模块是NFC中间件服务的基础层，封装了与NFC芯片的直接交互逻辑，为上层NFC业务提供统一的HAL层操作接口。

头文件清单

#include "include/middleware/services/nfc/controller/nfc_defs.h"
#include "include/middleware/services/nfc/controller/nfc_error_code.h"
#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

接口清单

接口名称	功能简述
NFC_HAL_CleanUpDevice	清理NFC芯片端发来的所有NCI消息
NFC_HAL_SendNciCmdAndRecvRsp	发送NCI命令并接收回复
NFC_HAL_SetCoreParams	设置NFC硬件抽象层核心参数
NFC_HAL_Open	打开NFC HAL层，触发芯片上电加载固件
NFC_HAL_Close	关闭NFC HAL层，芯片下电
NFC_HAL_NciReset	执行NCI协议定义的复位操作
NFC_HAL_NciInit	执行NCI协议定义的初始化操作
NFC_HAL_NciSetConfig	执行NCI协议定义的配置参数操作
NFC_HAL_NciDiscovMap	设置NCI RF接口映射关系
NFC_HAL_NciStartDiscovery	发送NCI开启轮询发现命令
NFC_HAL_StartDiscovery	根据输入的技术模式列表开启RF轮询发现流程
NFC_HAL_ReceiveNciPkt	阻塞式接收一个NCI包
NFC_HAL_SendData	发送NFC数据
NFC_HAL_RecvUnchainedData	接收NFC数据并处理NCI流控通知
NFC_HAL_TranceiveUnchainedData	发送NFC数据并接收回复数据
NFC_HAL_Deactivate	NFC去激活到空闲状态
NFC_HAL_EnterIdleSleep	让NFC设备进入空闲低功耗状态
NFC_HAL_CfgLowPwr	配置NFC低功耗特性的使能状态
NFC_HAL_NciIsoDepNakPresenceCheck	使用Iso-Dep NAK方法做卡片在位检测
NFC_HAL_PollRecvIntfActNtf	在Poll模式下接收接口激活通知
NFC_HAL_PollParseIntfActNtf	在Poll模式下解析接口激活通知信息
NFC_HAL_StartPollField	开启连续发场
NFC_HAL_StopPollField	关闭发场
NFC_HAL_NciT3TPolling	开启T3T轮询检测并获取轮询响应结果
NFC_HAL_NfceeDiscovery	开启NFCEE发现流程并返回NFCEE列表
NFC_HAL_NfceeEnable	开启NFCEE激活流程并获取技术模式列表
NFC_HAL_SetListenRouteTbl	设置侦听路由表
NFC_HAL_RestoreHciRam	恢复HCI RAM信息以避免重启时重复会话初始化
NFC_HAL_GetHciRam	获取指定NFCEE的HCI RAM信息

Functions

NFC_HAL_CleanUpDevice

void NFC_HAL_CleanUpDevice(void)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

清理NFC芯片端发来的所有NCI消息
用于在NFC操作异常或状态不一致时清除芯片残留消息
调用后芯片端缓存中的NCI消息将被全部丢弃

NFC_HAL_SendNciCmdAndRecvRsp

NfcErrorCode NFC_HAL_SendNciCmdAndRecvRsp(uint8_t *buf, uint16_t count, uint8_t *recvRsp, uint16_t *rspLen)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

发送NCI命令到NFC芯片并接收对应的回复消息
发送与接收在同一个调用中完成，保证命令与回复的对应关系
适用于NCI控制类命令的收发交互场景

入参

名称	参数类型	详细说明	约束取值范围
buf	uint8_t *	发送数据缓冲区指针	非NULL
count	uint16_t	发送数据字节长度	`1 ~ 65535`
recvRsp	uint8_t *	接收回复的存储地址	非NULL
rspLen	uint16_t *	输入为接收存储空间大小，输出为真实接收到的回复字节长度	非NULL

出参

名称	数据类型	输出说明
recvRsp	uint8_t *	接收到的回复消息内容
rspLen	uint16_t *	真实接收到的回复消息字节长度

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	命令发送及回复接收成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_SetCoreParams

void NFC_HAL_SetCoreParams(NfcHalCoreParams *params)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

设置NFC硬件抽象层核心参数，包括NCI控制包读超时、数据包读超时等
需在NFC_HAL_Open之前调用以配置核心参数
参数配置影响后续NCI包收发的超时行为

入参

名称	参数类型	详细说明	约束取值范围
params	NfcHalCoreParams *	核心参数结构体指针	非NULL

NFC_HAL_Open

NfcErrorCode NFC_HAL_Open(void)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

打开NFC HAL层，触发NFC芯片上电并加载固件
NFC业务操作的入口函数，需在其他NFC操作之前调用
调用后芯片完成上电初始化，可进行后续NCI命令交互

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	芯片上电及固件加载成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_Close

NfcErrorCode NFC_HAL_Close(void)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

关闭NFC HAL层，NFC芯片下电
NFC业务操作的出口函数，调用后芯片停止工作

前置条件

调用时序约束：调用前需确保无正在进行的数据收发操作

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	芯片下电成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_NciReset

NfcErrorCode NFC_HAL_NciReset(void)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

执行NCI协议定义的复位操作，对NFC芯片进行NCI层复位
复位后芯片NCI状态回到初始状态，需重新进行NCI初始化
适用于异常恢复或重新初始化NFC芯片的场景

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	NCI复位操作成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_NciInit

NfcErrorCode NFC_HAL_NciInit(void)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

执行NCI协议定义的初始化操作，获取NFC芯片的能力信息
需在NFC_HAL_NciReset之后调用
初始化完成后可进行后续的NCI配置和业务操作

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	NCI初始化操作成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_NciSetConfig

NfcErrorCode NFC_HAL_NciSetConfig(uint8_t *cmd, uint16_t len)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

执行NCI协议定义的配置参数操作，向NFC芯片下发配置参数
配置内容按NCI协议格式封装

前置条件

调用时序约束：需在NCI初始化完成后调用

入参

名称	参数类型	详细说明	约束取值范围
cmd	uint8_t *	NCI配置参数命令缓冲区指针	非NULL
len	uint16_t	NCI配置参数命令字节长度	`1 ~ 65535`

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	配置参数下发成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_NciDiscovMap

NfcErrorCode NFC_HAL_NciDiscovMap(uint8_t *cmd, uint16_t len)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

设置NCI RF接口映射关系，配置射频技术模式与RF接口之间的映射
需在开启轮询发现之前调用
映射关系决定了发现卡片后使用的RF接口类型

入参

名称	参数类型	详细说明	约束取值范围
cmd	uint8_t *	NCI RF接口映射配置命令缓冲区指针	非NULL
len	uint16_t	NCI RF接口映射配置命令字节长度	`1 ~ 65535`

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	RF接口映射配置成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_NciStartDiscovery

NfcErrorCode NFC_HAL_NciStartDiscovery(uint8_t *cmd, uint16_t len)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

发送NCI开启轮询发现命令，启动RF轮询发现流程
命令参数按NCI协议格式封装，包含发现类型及技术模式等

前置条件

调用时序约束：需在RF接口映射配置完成后调用

入参

名称	参数类型	详细说明	约束取值范围
cmd	uint8_t *	NCI开启轮询发现命令缓冲区指针	非NULL
len	uint16_t	NCI开启轮询发现命令字节长度	`1 ~ 65535`

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	轮询发现命令下发成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_StartDiscovery

NfcErrorCode NFC_HAL_StartDiscovery(uint8_t *techModeList, uint8_t num)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

根据输入的技术模式列表开启RF轮询发现流程
内部自动完成RF接口映射配置和轮询发现命令发送
相比NFC_HAL_NciStartDiscovery，封装了映射和发现两步操作

入参

名称	参数类型	详细说明	约束取值范围
techModeList	uint8_t *	技术模式列表，用于轮询发现	非NULL
num	uint8_t	输入技术模式的个数	`1 ~ 255`

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	轮询发现流程启动成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_ReceiveNciPkt

NfcErrorCode NFC_HAL_ReceiveNciPkt(uint8_t *buff, uint16_t *len, uint32_t timeout)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

阻塞式接收一个NCI包（包含NCI头），根据输入超时时间退出等待
接收到的数据包含完整的NCI包头和载荷
超时时间内未收到数据则返回超时错误

入参

名称	参数类型	详细说明	约束取值范围
buff	uint8_t *	接收NCI包的存储地址	非NULL
len	uint16_t *	输入时为存储空间大小，输出时为真实接收到的数据长度	非NULL
timeout	uint32_t	退出等待的超时时间，单位毫秒	`1 ~ 4294967295`

出参

名称	数据类型	输出说明
buff	uint8_t *	接收到的NCI包数据
len	uint16_t *	真实接收到的数据字节长度

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	成功接收到NCI包
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_SendData

NfcErrorCode NFC_HAL_SendData(uint8_t *buf, uint16_t sendLen, uint8_t conn)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

通过指定的逻辑管道发送NFC数据
数据发送按NCI数据包格式封装

前置条件

调用时序约束：需在接口激活完成后调用

入参

名称	参数类型	详细说明	约束取值范围
buf	uint8_t *	发送数据缓冲区指针	非NULL
sendLen	uint16_t	发送数据字节长度	`1 ~ 65535`
conn	uint8_t	用于发送数据的逻辑管道号	- NCI_STATIC_RF_CONN - NCI_STATIC_HCI_CONN

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	数据发送成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_RecvUnchainedData

NfcErrorCode NFC_HAL_RecvUnchainedData(uint8_t *recvBuff, uint16_t *buffLen)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

接收NFC非链式数据，同时处理附带的NCI流控通知
接收到的数据为完整的非链式数据包载荷
内部自动过滤并处理流控信用通知

入参

名称	参数类型	详细说明	约束取值范围
recvBuff	uint8_t *	接收数据的存储空间	非NULL
buffLen	uint16_t *	输入为存储空间大小，输出为接收到的数据长度	非NULL

出参

名称	数据类型	输出说明
recvBuff	uint8_t *	接收到的数据内容
buffLen	uint16_t *	接收到的数据字节长度

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	数据接收成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_TranceiveUnchainedData

NfcErrorCode NFC_HAL_TranceiveUnchainedData(uint8_t *sendBuff, uint16_t lenIn, uint8_t conn, uint8_t *recvBuff, uint16_t *lenOut)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

发送NFC数据并接收非链式回复数据，同时处理NCI流控通知
发送与接收在同一调用中完成，保证请求与回复的对应关系
适用于卡片读写等需要请求-回复交互的场景

入参

名称	参数类型	详细说明	约束取值范围
sendBuff	uint8_t *	待发送的数据缓冲区指针	非NULL
lenIn	uint16_t	待发送数据字节长度	`1 ~ 65535`
conn	uint8_t	数据发送所在的逻辑管道号	- NCI_STATIC_RF_CONN - NCI_STATIC_HCI_CONN
recvBuff	uint8_t *	接收数据的存储空间	非NULL
lenOut	uint16_t *	输入为接收存储空间最大长度，输出为真实接收数据长度	非NULL

出参

名称	数据类型	输出说明
recvBuff	uint8_t *	接收到的回复数据内容
lenOut	uint16_t *	接收到的回复数据字节长度

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	数据收发成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_Deactivate

NfcErrorCode NFC_HAL_Deactivate(void)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

NFC去激活到空闲状态，断开当前已激活的RF接口连接
去激活后设备回到空闲状态，可重新发起轮询发现
需在接口激活状态下调用

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	去激活操作成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_EnterIdleSleep

NfcErrorCode NFC_HAL_EnterIdleSleep(void)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

让NFC设备进入空闲低功耗睡眠状态，不做任何业务
进入睡眠后需要重新唤醒才能恢复业务操作
适用于长时间无NFC业务的低功耗场景

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	进入低功耗睡眠成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_CfgLowPwr

NfcErrorCode NFC_HAL_CfgLowPwr(bool status)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

配置NFC低功耗特性的使能或禁能状态
使能低功耗后芯片在空闲时自动进入低功耗模式
配置对后续的NFC业务行为产生影响

入参

名称	参数类型	详细说明	约束取值范围
status	bool	低功耗设置状态，是否启用	- `true`：启用低功耗 - `false`：禁用低功耗

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	低功耗配置成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_NciIsoDepNakPresenceCheck

NfcErrorCode NFC_HAL_NciIsoDepNakPresenceCheck(bool *isPresent, uint16_t timeout)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

使用NCI协议定义的Iso-Dep NAK方法做卡片在位检测
通过发送NAK帧检测已激活的卡片是否仍在近场范围内
适用于Poll模式下卡片在位状态监控场景

前置条件

NFC HAL已通过NFC_HAL_Open打开并完成NCI初始化
当前处于Poll模式下的接口激活状态

入参

名称	参数类型	详细说明	约束取值范围
isPresent	bool *	卡片是否在近场的检测结果输出	非NULL
timeout	uint16_t	等待检测通知的最长时间，单位毫秒	`1 ~ 65535`

出参

名称	数据类型	输出说明
isPresent	bool *	卡片在位检测结果，true表示在位，false表示不在位

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	在位检测操作完成
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_PollRecvIntfActNtf

NfcErrorCode NFC_HAL_PollRecvIntfActNtf(uint8_t priority, uint8_t *recvNtf, uint16_t len, uint32_t timeout)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

在Poll模式下接收接口激活通知，当发现多个对端设备时按优先级选择激活
接收到的通知内容包含激活的接口类型、协议及技术模式信息
需在轮询发现启动后调用以等待卡片激活

前置条件

NFC HAL已通过NFC_HAL_Open打开并完成NCI初始化
已通过NFC_HAL_StartDiscovery或NFC_HAL_NciStartDiscovery启动轮询发现

入参

名称	参数类型	详细说明	约束取值范围
priority	uint8_t	选卡优先级，参考NFC_CARD_SELECT_PRIORITY_ENUM	- PRIO_FIRST - PRIO_T1T - PRIO_T2T - PRIO_T3T - PRIO_ISODEP - PRIO_NFCDEP - PRIO_T5T - PRIO_PUBLIC_END - PRIO_PROP_A
recvNtf	uint8_t *	接收通知的存储空间	非NULL
len	uint16_t	存储空间大小	`1 ~ 65535`
timeout	uint32_t	等待接口激活通知的最长时间，单位毫秒	`1 ~ 4294967295`

出参

名称	数据类型	输出说明
recvNtf	uint8_t *	接收到的接口激活通知内容

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	接收到接口激活通知
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_PollParseIntfActNtf

NfcErrorCode NFC_HAL_PollParseIntfActNtf(NfcIntfActInfo *intfActInfo, uint8_t *recvNtf, uint16_t len)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

在Poll模式下解析接口激活通知，提取接口、协议、技术模式及技术参数信息
需配合NFC_HAL_PollRecvIntfActNtf使用，解析其接收到的通知数据
解析结果存储在NfcIntfActInfo结构体中，包含完整的激活信息

前置条件

已通过NFC_HAL_PollRecvIntfActNtf接收到接口激活通知数据

入参

名称	参数类型	详细说明	约束取值范围
intfActInfo	NfcIntfActInfo *	用于存储解析出的接口激活通知信息的结构体	非NULL
recvNtf	uint8_t *	接收到的接口激活通知数据	非NULL
len	uint16_t	接收到的接口激活通知字节长度	`1 ~ 65535`

出参

名称	数据类型	输出说明
intfActInfo	NfcIntfActInfo *	解析出的接口激活信息

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	解析成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_StartPollField

NfcErrorCode NFC_HAL_StartPollField(void)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

开启连续发场，使NFC设备持续发射射频场
开启后NFC设备处于主动轮询模式
适用于需要持续发射射频场的场景

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	发场开启成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_StopPollField

NfcErrorCode NFC_HAL_StopPollField(void)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

关闭发场，停止NFC设备射频场的持续发射
需在NFC_HAL_StartPollField之后调用
关闭后NFC设备不再主动发射射频场

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	发场关闭成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_NciT3TPolling

NfcErrorCode NFC_HAL_NciT3TPolling(NfcHalT3tPollCmdParams *cmdParams, NfcHalT3tSensfRes *ntfParams)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

开启T3T轮询检测并获取轮询响应结果
输入T3T轮询命令参数，输出轮询检测到的卡片感应通知
适用于T3T卡片的轮询检测与在位确认场景

前置条件

NFC HAL已通过NFC_HAL_Open打开并完成NCI初始化
当前处于Poll模式下且已激活T3T类型的RF接口

入参

名称	参数类型	详细说明	约束取值范围
cmdParams	NfcHalT3tPollCmdParams *	T3T轮询命令参数结构体指针	非NULL
ntfParams	NfcHalT3tSensfRes *	存储接收到的轮询响应通知的结构体指针	非NULL

出参

名称	数据类型	输出说明
ntfParams	NfcHalT3tSensfRes *	接收到的T3T轮询感应通知

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	T3T轮询检测成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_NfceeDiscovery

NfcErrorCode NFC_HAL_NfceeDiscovery(uint8_t *nfceeList, uint8_t size, uint8_t *num)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

开启NFCEE发现流程并返回发现的NFCEE列表
发现到的NFCEE ID存储在输出列表中
适用于Listen模式下发现可用的NFCEE设备

入参

名称	参数类型	详细说明	约束取值范围
nfceeList	uint8_t *	用于存储发现的多个NFCEE的列表	非NULL
size	uint8_t	列表最多可存储的NFCEE数目	`1 ~ 255`
num	uint8_t *	实际发现的NFCEE个数	非NULL

出参

名称	数据类型	输出说明
nfceeList	uint8_t *	发现的NFCEE ID列表
num	uint8_t *	实际发现的NFCEE个数

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	NFCEE发现流程完成
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_NfceeEnable

NfcErrorCode NFC_HAL_NfceeEnable(uint8_t nfceeId, uint8_t *techModeList, uint8_t size, uint8_t *num)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

开启NFCEE激活流程，从NFCEE接收到的RF轮询请求通知中解析出技术模式列表
返回的技术模式列表可用于后续的轮询发现配置

前置条件

调用时序约束：已通过NFC_HAL_NfceeDiscovery发现目标NFCEE

入参

名称	参数类型	详细说明	约束取值范围
nfceeId	uint8_t	需要激活的NFCEE ID值	通过NFC_HAL_NfceeDiscovery获取
techModeList	uint8_t *	用于存储返回的技术模式信息的数组	非NULL
size	uint8_t	最多可存储的技术模式数目	`1 ~ 255`
num	uint8_t *	返回的真实存储的技术模式个数	非NULL

出参

名称	数据类型	输出说明
techModeList	uint8_t *	从RF发现请求通知中解析出的技术模式列表
num	uint8_t *	实际存储的技术模式个数

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	NFCEE激活成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_SetListenRouteTbl

NfcErrorCode NFC_HAL_SetListenRouteTbl(uint8_t *cmd, uint16_t len)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

设置侦听路由表，配置NFCC的侦听路由规则
路由表决定了NFCC在Listen模式下如何路由接收到的数据
需在NFCEE激活完成后配置

入参

名称	参数类型	详细说明	约束取值范围
cmd	uint8_t *	侦听路由表的配置命令缓冲区指针	非NULL
len	uint16_t	命令字节长度	`1 ~ 65535`

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	侦听路由表设置成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_RestoreHciRam

NfcErrorCode NFC_HAL_RestoreHciRam(uint8_t *cmd, uint16_t len)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

恢复HCI RAM信息，避免重启时对同一NFCEE首次激活做不必要的会话初始化
命令内容从cmd+3位置开始，头部3字节预留给函数内部填充NCI头
HCI RAM信息可通过NFC_HAL_GetHciRam获取，首字节为NFCEE ID

入参

名称	参数类型	详细说明	约束取值范围
cmd	uint8_t *	恢复HCI RAM信息的配置命令，有效数据从cmd+3开始	非NULL，cmd缓冲区至少有3+len字节
len	uint16_t	从cmd+3位置开始计算的恢复HCI RAM信息命令字节长度	`1 ~ 65535`

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	HCI RAM信息恢复成功
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_GetHciRam

NfcErrorCode NFC_HAL_GetHciRam(uint8_t nfceeId, uint8_t *buff, uint16_t *len)

头文件清单

#include "include/middleware/services/nfc/controller/nfc_hal_core.h"

功能说明

获取指定NFCEE的HCI RAM信息，用于保存到文件中以便重启后恢复
返回的buff内容包含3字节NCI头+1字节Status+X字节HCI RAM信息
调用者需将HCI RAM信息保存到文件，重启时通过NFC_HAL_RestoreHciRam恢复

入参

名称	参数类型	详细说明	约束取值范围
nfceeId	uint8_t	需要获取HCI RAM信息的NFCEE ID	通过NFC_HAL_NfceeDiscovery获取
buff	uint8_t *	用于存储含有HCI RAM信息的完整NCI包	非NULL
len	uint16_t *	输入为buff总大小，输出为接收到的完整NCI包长度	非NULL

出参

名称	数据类型	输出说明
buff	uint8_t *	含有HCI RAM信息的完整NCI包，有效内容为3字节NCI头+1字节Status+X字节HCI RAM信息
len	uint16_t *	接收到的完整NCI包长度

返回值

返回值	文字含义	触发场景
NFC_OK(0)	执行成功	HCI RAM信息获取成功
Other	其他错误码，参考NfcErrorCode	执行失败

Type definitions

NfcErrorCode

typedef uint32_t NfcErrorCode;

使用说明

NFC模块错误码类型，作为NFC_HAL_Open、NFC_HAL_Close、NFC_HAL_NciReset等接口的返回值类型

Enumerations

NFC_NCI_RF_TECH_MODE_ENUM

enum NFC_NCI_RF_TECH_MODE_ENUM {
    NFC_NCI_A_PASSIVE_POLL_MODE   = 0x00,
    NFC_NCI_B_PASSIVE_POLL_MODE   = 0x01,
    NFC_NCI_F_PASSIVE_POLL_MODE   = 0x02,
    NFC_NCI_ACTIVE_POLL_MODE      = 0x03,
    NFC_NCI_V_PASSIVE_POLL_MODE   = 0x06,
    NFC_NCI_A_PASSIVE_LISTEN_MODE = 0x80,
    NFC_NCI_B_PASSIVE_LISTEN_MODE = 0x81,
    NFC_NCI_F_PASSIVE_LISTEN_MODE = 0x82,
    NFC_NCI_ACTIVE_LISTEN_MODE    = 0x83,
};

枚举成员	取值	描述
NFC_NCI_A_PASSIVE_POLL_MODE	0x00	技术A的被动轮询模式
NFC_NCI_B_PASSIVE_POLL_MODE	0x01	技术B的被动轮询模式
NFC_NCI_F_PASSIVE_POLL_MODE	0x02	技术F的被动轮询模式
NFC_NCI_ACTIVE_POLL_MODE	0x03	主动轮询模式
NFC_NCI_V_PASSIVE_POLL_MODE	0x06	技术V的被动轮询模式
NFC_NCI_A_PASSIVE_LISTEN_MODE	0x80	技术A的被动侦听模式
NFC_NCI_B_PASSIVE_LISTEN_MODE	0x81	技术B的被动侦听模式
NFC_NCI_F_PASSIVE_LISTEN_MODE	0x82	技术F的被动侦听模式
NFC_NCI_ACTIVE_LISTEN_MODE	0x83	主动侦听模式

NFC_NCI_RF_PROTOCOL_ENUM

enum NFC_NCI_RF_PROTOCOL_ENUM {
    NFC_NCI_RF_PROTOCOL_UNDETERMINED = 0x00,
    NFC_NCI_RF_PROTOCOL_T1T          = 0x01,
    NFC_NCI_RF_PROTOCOL_T2T          = 0x02,
    NFC_NCI_RF_PROTOCOL_T3T          = 0x03,
    NFC_NCI_RF_PROTOCOL_ISO_DEP      = 0x04,
    NFC_NCI_RF_PROTOCOL_NFC_DEP      = 0x05,
    NFC_NCI_RF_PROTOCOL_T5T          = 0x06,
    NFC_NCI_RF_PROP_PROTOCOL_A       = 0x80,
};

枚举成员	取值	描述
NFC_NCI_RF_PROTOCOL_UNDETERMINED	0x00	未定义的射频协议
NFC_NCI_RF_PROTOCOL_T1T	0x01	T1T射频协议
NFC_NCI_RF_PROTOCOL_T2T	0x02	T2T射频协议
NFC_NCI_RF_PROTOCOL_T3T	0x03	T3T射频协议
NFC_NCI_RF_PROTOCOL_ISO_DEP	0x04	ISO-DEP射频协议
NFC_NCI_RF_PROTOCOL_NFC_DEP	0x05	NFC-DEP射频协议
NFC_NCI_RF_PROTOCOL_T5T	0x06	T5T射频协议
NFC_NCI_RF_PROP_PROTOCOL_A	0x80	私有射频协议A

NFC_NCI_RF_INTERFACE_ENUM

enum NFC_NCI_RF_INTERFACE_ENUM {
    NFC_NCI_NFCEE_DIRECT_RF_INTERFACE = 0x00,
    NFC_NCI_FRAME_RF_INTERFACE        = 0x01,
    NFC_NCI_ISODEP_RF_INTERFACE       = 0x02,
    NFC_NCI_NFCDEP_RF_INTERFACE       = 0x03,
    NFC_NCI_PROP_A_RF_INTERFACE       = 0x80,
};

枚举成员	取值	描述
NFC_NCI_NFCEE_DIRECT_RF_INTERFACE	0x00	NFCEE直连模式的射频接口
NFC_NCI_FRAME_RF_INTERFACE	0x01	帧透传射频接口
NFC_NCI_ISODEP_RF_INTERFACE	0x02	基于ISO-DEP协议的射频接口
NFC_NCI_NFCDEP_RF_INTERFACE	0x03	基于NFC-DEP协议的射频接口
NFC_NCI_PROP_A_RF_INTERFACE	0x80	基于私有协议A的射频接口

NCI_LOGIC_CONN_ID_ENUM

enum NCI_LOGIC_CONN_ID_ENUM {
    NCI_STATIC_RF_CONN      = 0x00,
    NCI_STATIC_HCI_CONN     = 0x01,
};

枚举成员	取值	描述
NCI_STATIC_RF_CONN	0x00	静态射频逻辑管道
NCI_STATIC_HCI_CONN	0x01	静态HCI逻辑管道

NFC_CARD_SELECT_PRIORITY_ENUM

enum NFC_CARD_SELECT_PRIORITY_ENUM {
    PRIO_FIRST      = 0x00,
    PRIO_T1T        = 0x01,
    PRIO_T2T        = 0x02,
    PRIO_T3T        = 0x03,
    PRIO_ISODEP     = 0x04,
    PRIO_NFCDEP     = 0x05,
    PRIO_T5T        = 0x06,
    PRIO_PUBLIC_END = 0x07,
    PRIO_PROP_A     = 0x80,
};

枚举成员	取值	描述
PRIO_FIRST	0x00	优先选择第一个发现的卡片设备
PRIO_T1T	0x01	优先选择第一个T1T协议的卡片设备
PRIO_T2T	0x02	优先选择第一个T2T协议的卡片设备
PRIO_T3T	0x03	优先选择第一个T3T协议的卡片设备
PRIO_ISODEP	0x04	优先选择第一个ISO-DEP协议的卡片设备
PRIO_NFCDEP	0x05	优先选择第一个NFC-DEP协议的卡片设备
PRIO_T5T	0x06	优先选择第一个T5T协议的卡片设备
PRIO_PUBLIC_END	0x07	在公开协议基础上的无效优先级值
PRIO_PROP_A	0x80	优先选择第一个私有协议A的卡片设备

Structures

NfcHalCoreParams

typedef struct NfcHalCoreParamsStruct {
    uint32_t readTimeout;
    uint32_t dataTimeout;
#ifdef HAVE_NFC_LISTEN
    FuncProcessHciFromNfcee processHciFromNfcee;
#endif
} NfcHalCoreParams;

成员说明

成员名称	数据类型	描述
readTimeout	uint32_t	NCI控制包读操作超时，单位毫秒
dataTimeout	uint32_t	NCI数据包读操作超时，单位毫秒
processHciFromNfcee	FuncProcessHciFromNfcee	上层注册的回调函数，用于处理从NFCEE过来的HCI命令或通知（仅HAVE_NFC_LISTEN宏使能时存在）

NfcHalT3tPollNtfParams

#pragma pack(push, 1)
typedef struct NfcHalT3tPollNtfParamsStruct {
    uint8_t nfcid2[NFCID2_LEN];
    uint8_t pad0[T3T_PAD0_LEN];
    uint8_t pad1[T3T_PAD1_LEN];
    uint8_t mrtiCheck;
    uint8_t mrtiUpdate;
    uint8_t pad2;
    uint8_t rd[T3T_RD_LEN];
} NfcHalT3tPollNtfParams;
#pragma pack(pop)

成员说明

成员名称	数据类型	描述
nfcid2	uint8_t[NFCID2_LEN]	NFCID2的存储数组，长度参考NFCID2_LEN
pad0	uint8_t[T3T_PAD0_LEN]	PAD0的存储数组，长度参考T3T_PAD0_LEN
pad1	uint8_t[T3T_PAD1_LEN]	PAD1的存储数组，长度参考T3T_PAD1_LEN
mrtiCheck	uint8_t	MRTI-check参数
mrtiUpdate	uint8_t	MRTI-update参数
pad2	uint8_t	PAD2参数
rd	uint8_t[T3T_RD_LEN]	RD的存储数组，长度参考T3T_RD_LEN

NfcHalT3tSensfRes

typedef struct NfcHalT3tSensfResStruct {
    NfcHalT3tPollNtfParams resParams[T3T_POLL_SENSF_RES_MAX_SIZE];
    uint8_t resNum;
} NfcHalT3tSensfRes;

成员说明

成员名称	数据类型	描述
resParams	NfcHalT3tPollNtfParams[T3T_POLL_SENSF_RES_MAX_SIZE]	T3T轮询感应通知结构体数组
resNum	uint8_t	接收到的T3T轮询感应通知个数

NfcHalT3tPollCmdParams

typedef struct NfcHalT3tPollCmdParamsStruct {
    uint16_t sc;
    uint8_t rc;
    uint8_t tsn;
    uint16_t timeout;
} NfcHalT3tPollCmdParams;

成员说明

成员名称	数据类型	描述
sc	uint16_t	T3T轮询命令的系统码
rc	uint8_t	T3T轮询命令的请求码
tsn	uint8_t	T3T轮询命令的时隙个数
timeout	uint16_t	T3T轮询等待响应通知的超时时间，单位毫秒

NfcTechAParams

typedef struct {
    uint8_t sensRes[SENS_RES_LEN];
    uint8_t nfcid1Len;
    uint8_t nfcid1[NFCID1_MAX_LEN];
    uint8_t selRes;
} NfcTechAParams;

成员说明

成员名称	数据类型	描述
sensRes	uint8_t[SENS_RES_LEN]	技术A的轮询感应回复，长度参考SENS_RES_LEN
nfcid1Len	uint8_t	NFCID1的长度
nfcid1	uint8_t[NFCID1_MAX_LEN]	NFCID1的存储空间，最大长度参考NFCID1_MAX_LEN
selRes	uint8_t	技术A的选择回复

NfcTechBParams

typedef struct {
    uint8_t sensbResLen;
    uint8_t sensbRes[SENSB_RES_MAX_LEN];
} NfcTechBParams;

成员说明

成员名称	数据类型	描述
sensbResLen	uint8_t	技术B的轮询感应回复长度
sensbRes	uint8_t[SENSB_RES_MAX_LEN]	技术B的轮询感应回复，头部4字节是NFCID0，最大长度参考SENSB_RES_MAX_LEN

NfcTechFParams

typedef struct {
    uint8_t bitRate;
    uint8_t sensfResLen;
    uint8_t sensfRes[SENSF_RES_MAX_LEN];
} NfcTechFParams;

成员说明

成员名称	数据类型	描述
bitRate	uint8_t	技术F的速率
sensfResLen	uint8_t	技术F的轮询感应回复长度
sensfRes	uint8_t[SENSF_RES_MAX_LEN]	技术F的轮询感应回复，头部8字节是NFCID2，最大长度参考SENSF_RES_MAX_LEN

NfcTechVParams

typedef struct {
    uint8_t resFlag;
    uint8_t dsfid;
    uint8_t uid[UID_LEN];
} NfcTechVParams;

成员说明

成员名称	数据类型	描述
resFlag	uint8_t	回复的标记字节信息
dsfid	uint8_t	DSFID参数信息
uid	uint8_t[UID_LEN]	UID信息，长度参考UID_LEN

NfcIntfActInfo

typedef struct {
    uint8_t interface;
    uint8_t protocol;
    uint8_t techMode;
    NfcTechParams techParams;
} NfcIntfActInfo;

成员说明

成员名称	数据类型	描述
interface	uint8_t	NCI接口，参考NFC_NCI_RF_INTERFACE_ENUM
protocol	uint8_t	NCI协议，参考NFC_NCI_RF_PROTOCOL_ENUM
techMode	uint8_t	NCI技术模式，参考NFC_NCI_RF_TECH_MODE_ENUM
techParams	NfcTechParams	NFC技术的参数联合体，参考NfcTechParams

Associations

NfcTechParams

typedef union {
    NfcTechAParams a;
    NfcTechBParams b;
    NfcTechFParams f;
    NfcTechVParams v;
} NfcTechParams;

成员名称	类型	描述	接口使用逻辑
a	NfcTechAParams	技术A的参数信息	NFC_HAL_PollParseIntfActNtf出参NfcIntfActInfo的成员
b	NfcTechBParams	技术B的参数信息	NFC_HAL_PollParseIntfActNtf出参NfcIntfActInfo的成员
f	NfcTechFParams	技术F的参数信息	NFC_HAL_PollParseIntfActNtf出参NfcIntfActInfo的成员
v	NfcTechVParams	技术V的参数信息	NFC_HAL_PollParseIntfActNtf出参NfcIntfActInfo的成员

Macros

NCI_MAX_PAYLOAD_LEN

#define NCI_MAX_PAYLOAD_LEN       255

HAL_MAX_BUF_LEN

#define HAL_MAX_BUF_LEN           258

HAL_SHORT_BUFF_LEN

#define HAL_SHORT_BUFF_LEN        32

NCI_HEAD_LEN

#define NCI_HEAD_LEN              3

NCI_LEN_POS

#define NCI_LEN_POS               2

NCI_READ_TO

#define NCI_READ_TO               1000

NCI_READ_DATA_TO

#define NCI_READ_DATA_TO          1500

NCI_RF_FRAME_CORRUPTED

#define NCI_RF_FRAME_CORRUPTED    0x02

SENS_RES_LEN

#define SENS_RES_LEN              2

SENSB_RES_MAX_LEN

#define SENSB_RES_MAX_LEN         12

SENSF_RES_MAX_LEN

#define SENSF_RES_MAX_LEN         18

NFCID1_MAX_LEN

#define NFCID1_MAX_LEN            10

NFCID1_CASLVL1_LEN

#define NFCID1_CASLVL1_LEN        4

NFCID1_CASLVL2_LEN

#define NFCID1_CASLVL2_LEN        7

NFCID1_CASLVL3_LEN

#define NFCID1_CASLVL3_LEN        10

NFCID0_LEN

#define NFCID0_LEN                4

NFCID2_LEN

#define NFCID2_LEN                8

UID_LEN

#define UID_LEN                   8

T3T_PAD0_LEN

#define T3T_PAD0_LEN                 2

T3T_PAD1_LEN

#define T3T_PAD1_LEN                 3

T3T_RD_LEN

#define T3T_RD_LEN                   2

T3T_POLL_SENSF_RES_MAX_SIZE

#define T3T_POLL_SENSF_RES_MAX_SIZE  13