@ohos.nfc.cardEmulation (Standard NFC Card Emulation)

The cardEmulation module implements Near-Field Communication (NFC) card emulation. You can use the APIs provided by this module to determine the card emulation type supported and implement Host Card Emulation (HCE). HCE provides card emulation that does not depend on a secure element. It allows an application to emulate a card and communicate with an NFC card reader through the NFC service.

NOTE

The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.

HCE and AID Declaration

Before developing an application related to HCE, you must declare NFC-related attributes in the module.json5 file.

{
  "module": {
    // Other declared attributes
    "abilities": [
      {
        // Other declared attributes
        "skills": [
          {
            "actions": [
              "ohos.nfc.cardemulation.action.HOST_APDU_SERVICE"
            ]
          }
        ],
        "metadata": [
          {
            "name": "payment-aid",
            "value": "your payment aid"
          },
          {
            "name": "other-aid",
            "value": "your other aid"
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.NFC_CARD_EMULATION",
        // Set reason to card_emulation_reason.
        "reason": "$string:card_emulation_reason",
      }
    ]
  }
}

NOTE 1. The actions field must contain ohos.nfc.cardemulation.action.HOST_APDU_SERVICE and cannot be changed. 2. The name fields under metadata must be payment-aid or other-aid when application IDs (AIDs) are declared. Incorrect setting will cause a parsing failure. 3. The name field of requestPermissions must be ohos.permission.NFC_CARD_EMULATION and cannot be changed.

Modules to Import

import { cardEmulation } from '@kit.ConnectivityKit';

FeatureType^(deprecated)

Enumerates the NFC card emulation types.

NOTE

This API is supported since API version 6 and deprecated since API version 9. Use hasHceCapability instead.

System capability: SystemCapability.Communication.NFC.CardEmulation

CardType⁹⁺

Enumerates the types of services used by the card emulation application.

System capability: SystemCapability.Communication.NFC.CardEmulation

Atomic service API: This API can be used in atomic services since API version 12.

cardEmulation.isSupported^(deprecated)

isSupported(feature: number): boolean

Checks whether a certain type of card emulation is supported.

NOTE

This API is supported since API version 6 and deprecated since API version 9. Use hasHceCapability instead.

System capability: SystemCapability.Communication.NFC.CardEmulation

Parameters

Return value

Example

import { cardEmulation } from '@kit.ConnectivityKit';

let isHceSupported: boolean = cardEmulation.isSupported(cardEmulation.FeatureType.HCE);
if (!isHceSupported) {
    console.log('this device is not supported for HCE, ignore it.');
}

cardEmulation.hasHceCapability⁹⁺

hasHceCapability(): boolean

Checks whether the device supports HCE.

System capability: SystemCapability.Communication.NFC.CardEmulation

Required permissions: ohos.permission.NFC_CARD_EMULATION

Atomic service API: This API can be used in atomic services since API version 12.

Return value

Error codes

For details about the error codes, see NFC Error Codes.

Example

import { cardEmulation } from '@kit.ConnectivityKit';

let hasHceCap: boolean = cardEmulation.hasHceCapability();
if (!hasHceCap) {
    console.log('this device hasHceCapability false, ignore it.');
}

cardEmulation.isDefaultService⁹⁺

isDefaultService(elementName: ElementName, type: CardType): boolean

Checks whether an application is the default application of the specified service type.

System capability: SystemCapability.Communication.NFC.CardEmulation

Required permissions: ohos.permission.NFC_CARD_EMULATION

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

Error codes

For details about the error codes, see NFC Error Codes.

Return value

Example

import { cardEmulation } from '@kit.ConnectivityKit';
import { bundleManager, Want } from '@kit.AbilityKit';

// Initialize elementName, bundleName, and abilityName and set their values correctly based on the actual application information.
let elementName: bundleManager.ElementName = {
  bundleName: "com.example.myapplication",
  moduleName: "entry",
  abilityName: "EntryAbility"
};

let isDefaultService: boolean = cardEmulation.isDefaultService(elementName, cardEmulation.CardType.PAYMENT);

HceService⁸⁺

Provides APIs for implementing HCE, including receiving Application Protocol Data Units (APDUs) from the peer card reader and sending a response. Before using HCE-related APIs, check whether the device supports HCE.

startHCE^(deprecated)

startHCE(aidList: string[]): boolean

Starts HCE, including enabling this application to run in the foreground preferentially and dynamically registering the AID list.

NOTE This API is supported since API version 8 and deprecated since API version 9. Use start instead.

Required permissions: ohos.permission.NFC_CARD_EMULATION

System capability: SystemCapability.Communication.NFC.CardEmulation

Parameters

Return value

start⁹⁺

start(elementName: ElementName, aidList: string[]): void

Starts HCE, including enabling this application to run in the foreground preferentially and dynamically registering the AID list.

Required permissions: ohos.permission.NFC_CARD_EMULATION

System capability: SystemCapability.Communication.NFC.CardEmulation

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

Error codes

For details about the error codes, see NFC Error Codes.

stopHCE^(deprecated)

stopHCE(): boolean

Stops HCE, including exiting the current application from the foreground, releasing the dynamically registered AID list, and canceling the subscription of hceCmd.

NOTE This API is supported since API version 8 and deprecated since API version 9. Use stop instead.

Required permissions: ohos.permission.NFC_CARD_EMULATION

System capability: SystemCapability.Communication.NFC.CardEmulation

Return value

Example

For details, see the example of on.

stop⁹⁺

stop(elementName: ElementName): void

Stops HCE, including canceling the subscription of APDU data, exiting this application from the foreground, and releasing the dynamically registered AID list. The application needs to call this API in onDestroy of the HCE page.

Required permissions: ohos.permission.NFC_CARD_EMULATION

System capability: SystemCapability.Communication.NFC.CardEmulation

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

Error codes

For details about the error codes, see NFC Error Codes.

on⁸⁺

on(type: ‘hceCmd’, callback: AsyncCallback<number[]>): void

Subscribes to events indicating receiving of APDUs from the peer card reader. The application needs to call this API in onCreate() of the HCE page.

Required permissions: ohos.permission.NFC_CARD_EMULATION

System capability: SystemCapability.Communication.NFC.CardEmulation

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

Error codes

For details about the error codes, see NFC Error Codes.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';
import { cardEmulation } from '@kit.ConnectivityKit';
import { AsyncCallback } from '@kit.BasicServicesKit';
import { ElementName } from './bundleManager/ElementName'
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

let hceService: cardEmulation.HceService = new cardEmulation.HceService();
let element: ElementName;

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, param: AbilityConstant.LaunchParam) {
    hilog.info(0x0000, 'testHce', '%{public}s', 'Ability onCreate');
    element = {
      bundleName: want.bundleName ?? '',
      abilityName: want.abilityName ?? '',
      moduleName: want.moduleName
    }
    const apduCallback: AsyncCallback<number[]> = (err, data) => {
      // Implement data processing and handle exceptions.
      console.log("got apdu data");
    };
    hceService.on('hceCmd', apduCallback);
  }
  onDestroy() {
    hilog.info(0x0000, 'testHce', '%{public}s', 'Ability onDestroy');
    hceService.stop(element);
  }
  // Implement other lifecycle functions as demanded.
}

off¹⁸⁺

off(type: ‘hceCmd’, callback?: AsyncCallback<number[]>): void

Unsubscribes from events indicating receiving of APDUs from the peer card reader.

Required permissions: ohos.permission.NFC_CARD_EMULATION

System capability: SystemCapability.Communication.NFC.CardEmulation

Atomic service API: This API can be used in atomic services since API version 18.

Parameters

Error codes

For details about the error codes, see NFC Error Codes.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';
import { cardEmulation } from '@kit.ConnectivityKit';
import { AsyncCallback } from '@kit.BasicServicesKit';
import { ElementName } from './bundleManager/ElementName'
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

let hceService: cardEmulation.HceService = new cardEmulation.HceService();
let element: ElementName;
const apduCallback: AsyncCallback<number[]> = (err, data) => {
  // Implement data processing and handle exceptions.
  console.log("AsyncCallback got apdu data");
};

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, param: AbilityConstant.LaunchParam) {
    hilog.info(0x0000, 'testHce', '%{public}s', 'Ability onCreate');
    element = {
      bundleName: want.bundleName ?? '',
      abilityName: want.abilityName ?? '',
      moduleName: want.moduleName
    }
    const apduCallback: AsyncCallback<number[]> = (err, data) => {
      // Implement data processing and handle exceptions.
      console.log("got apdu data");
    };
    hceService.on('hceCmd', apduCallback);
  }
  onDestroy() {
    hilog.info(0x0000, 'testHce', '%{public}s', 'Ability onDestroy');
    hceService.off('hceCmd', apduCallback);
    hceService.stop(element);
  }
  // Implement other lifecycle functions as demanded.
}

sendResponse^(deprecated)

sendResponse(responseApdu: number[]): void

Sends a response to the peer card reader.

NOTE This API is supported since API version 8 and deprecated since API version 9. Use transmit instead.

Required permissions: ohos.permission.NFC_CARD_EMULATION

System capability: SystemCapability.Communication.NFC.CardEmulation

Parameters

transmit⁹⁺

transmit(response: number[]): Promise<void>

Transmits an APDU to the peer card reader. This API uses a promise to return the result. The application calls this API only after receiving an APDU sent by the card reader via on.

Required permissions: ohos.permission.NFC_CARD_EMULATION

System capability: SystemCapability.Communication.NFC.CardEmulation

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

Example

import { cardEmulation } from '@kit.ConnectivityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let hceService: cardEmulation.HceService = new cardEmulation.HceService();

// Data to be sent by the application. The following data is for reference only.
const responseData = [0x1, 0x2];
hceService.transmit(responseData).then(() => {
  // Process the promise.
  console.log("transmit Promise success.");
}).catch((err: BusinessError) => {
  console.log("transmit Promise error:", err);
});

transmit⁹⁺

transmit(response: number[], callback: AsyncCallback<void>): void

Transmits an APDU to the peer card reader. This API uses an asynchronous callback to return the result. The application calls this API only after receiving an APDU sent by the card reader via on.

Required permissions: ohos.permission.NFC_CARD_EMULATION

System capability: SystemCapability.Communication.NFC.CardEmulation

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

Error codes

For details about the error codes, see NFC Error Codes.

Example

import { cardEmulation } from '@kit.ConnectivityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let hceService: cardEmulation.HceService = new cardEmulation.HceService();

// Data to be sent by the application. The following data is for reference only.
try {
  const responseData = [0x1, 0x2];

  hceService.transmit(responseData, (err : BusinessError)=> {
    if (err) {
      console.error(`transmit AsyncCallback err Code: ${err.code}, message: ${err.message}`);
    } else {
      console.log("transmit AsyncCallback success.");
    }
  });
} catch (error) {
  console.error(`transmit AsyncCallback catch Code: ${(error as BusinessError).code}, ` +
    `message: ${(error as BusinessError).message}`);
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Connectivity Kit (Short-Range Communication Service)

harmony 鸿蒙Bluetooth

harmony 鸿蒙Wifi

harmony 鸿蒙Bluetooth Error Codes

harmony 鸿蒙NFC Error Codes

harmony 鸿蒙SecureElement Error Codes

harmony 鸿蒙Wi-Fi Error Codes

harmony 鸿蒙@ohos.bluetooth.a2dp (Bluetooth A2DP Module) (System API)

harmony 鸿蒙@ohos.bluetooth.a2dp (Bluetooth A2DP Module)

harmony 鸿蒙@ohos.bluetooth.access (Bluetooth Access Module) (System API)