NFC API
The BlackBerry 10 NFC API provides the following capabilities:
- Reading from and writing to NFC tags
- Sharing data between NFC-enabled devices
- Sharing files using Bluetooth and Wi-Fi connection handover
- Card emulation (using libnfc)
The NFC API has two layers. The first layer consists of a C API that supports many NFC features. The second layer is the C++ NFC API, which is a C++ and Qt layer that is built on top of the C API. The C++ NFC API supports a subset of the features found in the C API. The BlackBerry 10 OS also provides the invocation framework, which can be used with both the Cascades APIs and the C APIs to give your apps access to an enhanced set of additional functionality when working with NFC.
You can use Cascades and Qt (that is, the C++ NFC APIs) to build your apps, or you can build your apps using the BlackBerry 10 native C APIs. Both approaches have their own set of advantages and disadvantages. It's important to note that the Cascades and Qt APIs provide a subset of the functionalities found in the native C APIs, therefore whichever approach you choose depends upon the functional requirements of your app. If the Cascades and Qt APIs satisfy the functional requirements of your app, then you may want to use the flexibility and power of the Cascades and Qt object oriented C++ APIs. If the functionality that your app requires is not available in the Cascades and Qt NFC APIs, then you may want to consider using the native C API. You can also use the Cascades and Qt APIs and the invocation framework to build the UI layer of your app and use the NFC C API to access any lower-level functionality you need.
The following diagram illustrates the layered APIs that an app can use to access the NFC service.
The C++ NFC API includes the following components:
- A subset of the Qt Connectivity NFC API: The base functionality is provided by QtNfcSubset, which is an extension of some of the core classes found in the Qt Connectivity API. These classes are used for creating and parsing NDEF messages.
- The Cascades NFC API: To supplement QtNfcSubset, Cascades provides a set of classes in the bb::system namespace that are specific to the BlackBerry 10 OS. These classes provide the functionality needed for sharing NDEF and non-NDEF content over NFC.
The C API (libnfc and libnfc_bps) includes the following components:
- NFC BPS extension: Using BlackBerry Platform Services to deliver and monitor NFC events
- General NFC functionalities: APIs for tag reading and writing, NDEF operations, NDEF emulation, and Host Card Emulation
- NFC secure element functionalities: APIs for accessing the UICC secure element, and for registering for transaction notification
For more information about the invocation framework, see Invocation framework.
Card emulation
The NFC service C API provides the following card emulation capabilities:
- NDEF tag emulation: Using the tag emulation functions, an application can emulate an NFC tag that stores an NDEF message, which is detected and read by another NFC-enabled device that acts as an initiator.
- Host Card Emulation (HCE): HCE allows the BlackBerry 10 device to look like an ISO 14443-4 smart card, ready to connect with a reader device and perform transactions such as payment and ticketing, without going through a UICC or secure element.
- UICC secure element card emulation (UICC SE CE): Through applets
that run on the SE, the UICC SE allows your device to perform financial
transactions with external card readers. In UICC SE CE, applications don't play
a role in card transactions, but can communicate with the applet through card
emulation APIs to obtain information related to card transactions. The card
emulation APIs allow an application to:
- Communicate with the applets on the SE through formatted byte arrays called Application Protocol Data Units (APDUs)
- Register for and receive transaction notifications when transactions of interest take place on the SE
Technology types
The NFC service C API supports a number of technology types for card emulation, defined in technology_type_t. Technology types A, B, B’, and F are all based on the ISO 14443 standard at the lower layers, but use different protocols at the higher layers.
- Type A and Type B: ISO 14443 Type A and Type B. Different in the modulation procedure used for data transfer.
- Type B': The Calypso card that is used in the Calypso transport application, created by the Calypso Networks Association. Similar to Type B but uses proprietary protocols in the upper layers.
- Type F: The Felica card produced by Sony and used mainly in Asia. FeliCa uses its own modulation schema that is different from Type A and Type B. It also uses proprietary security protocols.
Parallel operation dependencies
When using the NFC service C API, some NFC functions may depend on other NFC functions. Some passive mode functionalities may be available only when other passive modes are disabled or restricted in their applicable technologies.
The table below describes the NFC passive modes your device supports. An "X" indicates that the passive mode is supported under the specified technology type (A, B, B', or F). Some of the passive modes cannot be enabled simultaneously. See the rules below on parallel operation among the different functionalities.
| NFC Technology | A | B | B' | F |
|---|---|---|---|---|
| Host Card Emulation (HCE) | X | X | ||
| NDEF tag emulation | X | X | ||
| UICC secure element card emulation (UICC SE CE) | X | X | X | |
| Peer-to-peer (P2P) mode in passive mode (P2P target) | X | X |
You may request any passive modes supported in the table above. The NFC service determines the passive modes and technologies to offer to the user after applying the following rules:
- When nfc_start_iso14443_4_emulation() is used for HCE:
- All other forms of card emulation are disabled.
- HCE is active only when the application is in the foreground.
- When nfc_hce_register_aid() is used with an AID wild card:
- All other forms of card emulation are disabled.
- HCE is active only when the application is in the foreground
- When nfc_hce_register_aid() is used with a dedicated AID:
- Other forms of card emulation may run in parallel.
- HCE remains active while the application runs in the foreground or background, or is terminated.
- When the UICC SE CE uses either technology A or B, other passive modes must use the same technology as the UICC SE CE. This rule doesn't affect technology F. For example, if UICC SE CE uses only technology A, then HCE and NDEF tag emulation must use only technology A.
- When UICC SE CE is not active, HCE and NDEF tag emulation are enabled on both technologies A and B.
- When UICC SE CE is active on technology B and inactive on technology A, P2P target is disabled on technology A.
- The nfc_start_iso14443_4_emulation() function for HCE requires selecting either technology A or B. When you use this function to select technology B, P2P target is disabled on technology A.
- When NDEF tag emulation is active, P2P target is disabled.
- NDEF tag emulation is active only when the application is in the foreground.
Supported feature sets
Different BlackBerry 10 devices may have different NFC functionalities. These differences are called feature sets, and are highlighted in the documentation as feature set 1 and feature set 2. Using the NFC service C API, you can call nfc_get_feature_set() to see which feature set a device supports.
- Feature set 0: NFC is not supported on the device.
- Feature set 1: NFC is supported. See table below for details.
- Feature set 2: NFC is supported. See table below for details.
| Functionality and Affected APIs | Feature set 1 | Feature set 2 |
|---|---|---|
| Jewel support: nfc_get_tag_name() | Does not detect Jewel tags | Detects Jewel tags |
| Writing multiple NDEF messages: nfc_write_ndef_message_to _tag() | Supported | Not supported |
| Battery mode: battery_mode_t | Supports both low battery and empty (or no) battery mode | Supports only low battery mode |
| Retrieving tag ID: nfc_get_tag_id() |
Depends on the tag variant and the connection type |
Depends on the tag variant and the connection type |
| Retrieving tag name: nfc_get_tag_name() |
Depends on the tag variant and the connection type |
Depends on the tag variant and the connection type |
| AID-based Host Card Emulation (HCE): nfc_hce_register_aid() nfc_hce_unregister_aid() nfc_hce_is_aid_registered() | Not supported; affected functions return NFC_RESULT_ UNSUPPORTED_API | Supported |
| NFC events: NFC_VIRTUAL_TAG_READ_EVENT | Supported | Not supported |
| Creating an LLCP connection listener: nfc_llcp_register _connection_listener() | Supports a range of values for the sap parameter | Supports a range of values for the sap parameter |
| Writing to tag: nfc_tag_transceive() | Handles tag responses differently | Handles tag responses differently |