mxxce

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

接口清单

接口名称	功能简述
NFC_HAL_MxxCeRegisterCallback	注册处理NFCC上报事件的回调函数
NFC_HAL_MxxCeMessageProc	对NFCC上报的数据进行处理并转换成对应事件
NFC_HAL_MxxCeModeInit	初始化NFCC芯片为MXX卡模拟模式
NFC_HAL_MxxCeStart	开始MXX卡模拟侦听业务
NFC_HAL_MxxCeStop	停止MXX卡模拟侦听业务
NFC_HAL_MxxCeInitCard	初始化一张MXX卡片
NFC_HAL_MxxCeSwitchCardByIndex	切换MXX卡片并下发卡片信息给NFCC
NFC_HAL_MxxCeUploadCurrentCard	命令NFCC上报当前使用的MXX卡的卡片信息
NFC_HAL_MxxCeGetCurrentCardIndex	获取当前卡片编号
NFC_HAL_MxxCeRemoveCardByIndex	删除指定MXX卡片
NFC_HAL_MxxCeRemoveAllCards	删除所有MXX卡片
NFC_HAL_MxxCeIsValidCard	判断指定MXX卡片是否有效

Functions

NFC_HAL_MxxCeRegisterCallback

void NFC_HAL_MxxCeRegisterCallback(MxxCeCallback handler)

头文件清单

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

功能说明

注册上层回调函数，用于接收NFCC上报的事件通知
回调函数类型为 MxxCeCallback，事件类型参考 NfcMxxCeEvent
需在启动MXX卡模拟侦听业务前完成回调注册，否则无法接收NFCC事件

入参

名称	参数类型	详细说明	约束取值范围
handler	MxxCeCallback	用户定义的回调函数接口	非NULL

NFC_HAL_MxxCeMessageProc

NfcErrorCode NFC_HAL_MxxCeMessageProc(uint8_t *data, uint16_t len)

头文件清单

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

功能说明

对NFCC上报的数据进行解析处理，转换为对应的事件并通知上层
支持的事件类型参考 NfcMxxCeEvent

前置条件

调用时序约束：需在回调函数注册完成后调用

入参

名称	参数类型	详细说明	约束取值范围
data	uint8_t *	接收到的数据内容	非NULL
len	uint16_t	数据长度	`0 ~ 65535`

返回值

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

NFC_HAL_MxxCeModeInit

NfcErrorCode NFC_HAL_MxxCeModeInit(void)

头文件清单

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

功能说明

初始化NFCC芯片为MXX卡模拟（CE）工作模式
需在使用其他MXX CE接口前调用，完成模式初始化
初始化前需确保NFCC芯片通信正常

前置条件

NFCC芯片通信已正常建立
回调函数已通过 NFC_HAL_MxxCeRegisterCallback 注册

返回值

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

NFC_HAL_MxxCeStart

NfcErrorCode NFC_HAL_MxxCeStart(void)

头文件清单

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

功能说明

启动MXX卡模拟侦听业务，NFCC开始响应外部读卡器
需在模式初始化完成且至少有一张有效MXX卡片后调用
启动后NFCC将响应外部场事件并通过回调通知上层

前置条件

已通过 NFC_HAL_MxxCeModeInit 完成MXX CE模式初始化
至少已通过 NFC_HAL_MxxCeInitCard 初始化一张MXX卡片

返回值

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

NFC_HAL_MxxCeStop

NfcErrorCode NFC_HAL_MxxCeStop(void)

头文件清单

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

功能说明

停止MXX卡模拟侦听业务，NFCC不再响应外部读卡器
需在侦听业务启动后调用
停止后可通过 NFC_HAL_MxxCeStart 重新启动

前置条件

MXX CE侦听业务已通过 NFC_HAL_MxxCeStart 启动

返回值

返回值	文字含义	触发场景
NFC_OK(0)	成功	侦听业务停止
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_MxxCeInitCard

NfcErrorCode NFC_HAL_MxxCeInitCard(uint8_t index, uint8_t *mem, uint16_t memSize, bool isBlank)

头文件清单

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

功能说明

初始化指定编号的MXX卡片，为其分配内存并设置卡片状态
卡片编号不应超过 MAX_MXX_CARD_NUM
分配的内存大小应为 MXX_MEM_SIZE
可选择初始化为空白卡或非空白卡

入参

名称	参数类型	详细说明	约束取值范围
index	uint8_t	卡片编号	`0 ~ MAX_MXX_CARD_NUM-1`
mem	uint8_t *	为该卡片分配的内存	非NULL，空间不小于memSize
memSize	uint16_t	为该卡片分配的内存大小	MXX_MEM_SIZE
isBlank	bool	是否初始化为空白卡	`true`：空白卡；`false`：非空白卡

返回值

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

NFC_HAL_MxxCeSwitchCardByIndex

NfcErrorCode NFC_HAL_MxxCeSwitchCardByIndex(uint8_t index)

头文件清单

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

功能说明

切换当前使用的MXX卡片，并将卡片信息下发至NFCC
切换前需确保目标卡片已通过 NFC_HAL_MxxCeInitCard 初始化
切换后NFCC将使用新卡片信息响应外部读卡器

入参

名称	参数类型	详细说明	约束取值范围
index	uint8_t	卡片编号	`0 ~ MAX_MXX_CARD_NUM-1`

返回值

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

NFC_HAL_MxxCeUploadCurrentCard

NfcErrorCode NFC_HAL_MxxCeUploadCurrentCard(void)

头文件清单

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

功能说明

命令NFCC上报当前使用的MXX卡的卡片信息
用于获取NFCC侧当前激活的卡片状态

前置条件

调用时序约束：已通过 NFC_HAL_MxxCeModeInit 完成模式初始化

返回值

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

NFC_HAL_MxxCeGetCurrentCardIndex

uint8_t NFC_HAL_MxxCeGetCurrentCardIndex(void)

头文件清单

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

功能说明

获取当前选中的MXX卡片编号
返回值为当前卡片索引，不应超过 MAX_MXX_CARD_NUM
需在至少有一张卡片初始化后调用

前置条件

至少已通过 NFC_HAL_MxxCeInitCard 初始化一张MXX卡片

返回值

返回值	文字含义	触发场景
0 ~ MAX_MXX_CARD_NUM-1	当前卡片编号	获取当前选中卡片编号

NFC_HAL_MxxCeRemoveCardByIndex

NfcErrorCode NFC_HAL_MxxCeRemoveCardByIndex(uint8_t index)

头文件清单

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

功能说明

删除指定编号的MXX卡片，释放其占用的资源
删除后该卡片编号可重新用于 NFC_HAL_MxxCeInitCard 初始化
若删除的是当前使用的卡片，需调用 NFC_HAL_MxxCeSwitchCardByIndex 切换至其他有效卡片
需在业务停止时调用，避免同时修改导致冲突

入参

名称	参数类型	详细说明	约束取值范围
index	uint8_t	卡片编号	`0 ~ MAX_MXX_CARD_NUM-1`

返回值

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

NFC_HAL_MxxCeRemoveAllCards

NfcErrorCode NFC_HAL_MxxCeRemoveAllCards(void)

头文件清单

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

功能说明

删除所有已初始化的MXX卡片，释放全部卡片资源
删除后需重新通过 NFC_HAL_MxxCeInitCard 初始化卡片
需在业务停止时调用，避免同时修改导致冲突

返回值

返回值	文字含义	触发场景
NFC_OK(0)	成功	所有卡片删除完成
Other	其他错误码，参考NfcErrorCode	执行失败

NFC_HAL_MxxCeIsValidCard

bool NFC_HAL_MxxCeIsValidCard(uint8_t index)

头文件清单

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

功能说明

判断指定编号的MXX卡片是否有效
有效卡片指已通过 NFC_HAL_MxxCeInitCard 初始化且未被删除的卡片
在对卡片执行操作前可调用此接口进行有效性检查

入参

名称	参数类型	详细说明	约束取值范围
index	uint8_t	卡片编号	`0 ~ MAX_MXX_CARD_NUM-1`

返回值

返回值	文字含义	触发场景
true	卡片有效	指定编号的卡片已初始化且未删除
false	卡片无效	指定编号的卡片未初始化或已删除

Type definitions

NfcErrorCode

typedef uint32_t NfcErrorCode;

使用说明

NFC模块错误码类型，用于多个MXX CE接口的返回值类型

MxxCeCallback

typedef NfcErrorCode (*MxxCeCallback)(NfcMxxCeEvent evtId);

使用说明

上层注册的回调函数类型，用于 NFC_HAL_MxxCeRegisterCallback 入参类型

调用时机

当NFCC上报事件（如外部起场、断场、卡片更新、芯片复位等）时，通过已注册的MxxCeCallback回调函数通知上层，事件类型由NfcMxxCeEvent枚举值指定

Enumerations

NfcMxxCeEvent

typedef enum {
    NFC_MXXCE_EVENT_NONE,
    NFC_MXXCE_EVENT_FIELD_ON,
    NFC_MXXCE_EVENT_FIELD_OFF,
    NFC_MXXCE_EVENT_CARD_UPDATED,
    NFC_MXXCE_EVENT_RESET,
} NfcMxxCeEvent;

枚举成员	取值	描述
NFC_MXXCE_EVENT_NONE	0	无事件
NFC_MXXCE_EVENT_FIELD_ON	1	外部起场事件
NFC_MXXCE_EVENT_FIELD_OFF	2	外部断场事件
NFC_MXXCE_EVENT_CARD_UPDATED	3	芯片中存储的卡片信息被更新事件
NFC_MXXCE_EVENT_RESET	4	芯片复位事件

Macros

MAX_MXX_CARD_NUM

#define MAX_MXX_CARD_NUM 20

MXX_MEM_SIZE

#define MXX_MEM_SIZE 1024