nfc_hce_register_aid()
Register an AID for Host Card Emulation (HCE)
Synopsis:
#include "nfc/nfc.h"
NFC_API nfc_result_t nfc_hce_register_aid(const uint8_t *aid, size_t aid_len, app_category_type_t category, const char *invoke_target)
Since:
BlackBerry 10.3.0
Arguments:
- aid
-
Pointer to the buffer containing the AID.
- aid_len
-
Length of the AID.
- category
-
The purpose of the emulating application. This is used to help the user choose an application when an AID conflict occurs between two or more applications.
- invoke_target
-
The target ID in a null-terminated string. When an NFC reader selects the registered AID, the NFC system includes this target ID in the invocation message it sends. When registering a wildcard AID, set this parameter to NULL.
Library:
libnfc (For the qcc command, use the -l nfc option to link against this library)Description:
An application that wants to perform HCE as defined in ISO-DEP (ISO/IEC 14443-4) can use this function to register an application identifier (AID) according to ISO/IEC 7816-5. When an NFC reader issues a SELECT command with the registered AID, the application is notified through the Invocation Framework using the invoke_target that the application has provided.
An application can register a specific AID or a wildcard AID. When it registers a specific AID, the AID stays registered (that is, the emulation is active) until the application calls nfc_hce_unregister_aid() or until the application is uninstalled from the system. This means that the emulation remains active regardless of whether the application is running (either in the foreground or in the background) or terminated.
An application can register a specific AID only once, but can register more than one AID. The registration of the same AID by more than one application leads to a routing conflict in the system. When the NFC service receives the first SELECT command with the conflicting AID, it prompts the user to resolve the conflict.
An application can register a wildcard AID by setting the parameters aid to NULL and aid_len to 0. A wildcard AID allows the application to receive all ISO 14443-4 commands when it runs in the foreground; however, when it's running in the background or gets terminated, no HCE commands are routed to the application.
An application also needs to register itself as an invocation target in order to be invoked to handle AID routing and transactions. This can be done in the <invoke-target> of the bar-descriptor.xml file.
- NFC_ISO14443_4_COMMAND_EVENT: This event indicates that a command was generated by the target reader. The application must first call nfc_get_target() to retrieve the event target, and then nfc_get_iso14443_4_emulation_command() using the target retrieved to extract the command data from the triggered event.
- NFC_ISO14443_4_EVENT_CODE_EVENT: This event indicates that an ISO 14443-4 related event has occurred. This event is associated with an event code from the target reader. Call nfc_get_notification_value() to extract the event code (of type iso14443_4_event_t).
Feature set 1 doesn't support this function. When called in feature set 1, the function returns NFC_RESULT_UNSUPPORTED_API.
Returns:
- NFC_RESULT_INVALID_PARAMETER: A parameter is invalid.
- NFC_RESULT_SERVICE_CONNECTION_ERROR: The application is not connected to the NFC system.
- NFC_RESULT_OUT_OF_MEMORY: The system memory available for the NFC system to complete this operation is insufficient.
- NFC_RESULT_OPERATION_REJECTED: One of the following errors has occurred:
- The application already started an HCE.
- The application already registered the same AID.
- The AID is not valid for the specified category.
- NFC_RESULT_UNSUPPORTED_API: This API is not supported in this feature set.
Last modified: 2015-07-24