Near field communication

The net.rim.device.api.io.nfc package enables you to read and write data on smart tags, emulate a smart tag, and access a secure element embedded on a BlackBerry® device or SIM card.

Reading smart tags

To read a smart tag, you must register your application to receive a notification when the BlackBerry device detects a tag. Using the ReaderWriterManager class, you can register your implementation of the DetectionListener interface or the NDEFMessageListener interface. When you register an NDEFMessageListener, you can choose whether or not the device should start your application when it detects and NDEF tag. The ReaderWriterManager class and the DetectionListener interface are located in the net.rim.device.api.io.readerwriter package. The NDEFMessageListener interface is located in the net.rim.device.api.io.ndef package.

When a BlackBerry device detects a smart tag, it notifies all registered listeners. If you registered a DetectionListener object, your listener receives a Target object that contains properties about the tag. The Target.getUri() method returns a URI that contains connection details for the detected tag. You can use the URI as the connection string parameter to javax.microedition.Connector.open() to open a connection to the tag.

If you registered an NDEFMessageListener object, your listener receives an NDEFMessage object. The NDEFMessage class contains methods that help you retrieve NDEFRecord objects that contain the data from the tag.

Writing to smart tags

To write data on a smart tag, you must register your application to receive a notification when the BlackBerry device detects a tag. Using the ReaderWriterManager class, you can register your implementation of the DetectionListener interface.

When a BlackBerry device detects a smart tag, it notifies all registered listeners. Your listener receives a Target object that contains properties about the detected tag. The Target.getUri() method returns a URI that contains connection details for the tag. You can use the URI as the connection string parameter to javax.microedition.Connector.open() to open a connection to the tag.

If you write to an NDEF formatted tag using the NFC Forum standards, you can use the NDEFTagConnection interface to control your connection. The NDEFTagConnection.write() method allows you to write NDEFMessage objects to the tag. You can assemble your NDEF message using the NDEFMessage and NDEFRecord classes. You can find the NDEF-related classes and interfaces in the net.rim.device.api.io.nfc.ndef package.

You can send and receive ISO14443-3 and ISO14443-4 tag commands using the ISO14443Part3Connection and ISO14443Part4Connection interfaces, respectively. You can find the ISO14443 connection interfaces in the net.rim.device.api.io.nfc.readerwriter package.

Emulating a smart tag

You can emulate a smart tag by using the classes in the net.rim.device.api.io.nfc.emulation package. The NFC API supports the following tag types for emulation:

Tag type

Class

NFC Forum Type 4

VirtualNDEFTag

ISO14443-4A

VirtualISO1443Part4TypeATarget

ISO14443-4B

VirtualISO1443Part4TypeBTarget

If you want to emulate an NFC Forum Type 4 tag, you must first assemble your NDEF message using the NDEFMessage and NDEFRecord classes from the net.rim.device.api.io.nfc.ndef package. In the VirtualNDEFTag constructor, you can specify the NDEF message that your tag should provide to a reader.

You can respond to interactions with a reader by implementing the VirtualTargetCallback interface (NFC Forum Type 4 tag), or the VirtualISO1443Part4TargetCallback (ISO14443-4 tags). You must specify your callback object when you construct your virtual target.

Accessing a Secure Element

The classes and interfaces in the net.rim.device.api.io.nfc.se package enable you to access a Secure Element on a BlackBerry device or a SIM card. You can use the SecureElementManager class to retrieve a SecureElement object that allows you to access a Secure Element. You should implement the TransactionListener interface if you want to be notified when an external reader completes a transaction with an application on the Secure Element. The TechnologyTypesChangeListener enables you to receive notifications when a secure element requests data for a specified protocol.

If you want to develop a secure element, you must use an external development tool to do so, and then use the net.rim.device.api.io.nfc.se package to access it in your application.

Connecting with Smart Accessories

You can use the Accessory API to connect with smart accessories like a wireless headset or smart dock. The AccessoryManager class in the net.rim.blackberry.api.accessory package allows you to register your application to start when the BlackBerry device connects with a smart accessory. You can register for notifications of connections with device types, or an accessory that has a specific application ID assigned by the manufacturer.

When the BlackBerry device detects a smart accessory, the device starts registered applications and broadcasts a BehaviorGlobalEvent. Your application must listen for a BehaviorGlobalEvent (from the net.rim.blackberry.api.behavior package) to receive the connection notification. When you receive a notification of connection, you can invoke AccessoryManager.getConnectedAccessory() to retrieve information about the accessory.

If multiple applications are registered to listen for notifications of a particular type of accessory, or a particular application ID, the device may prompt the user to choose which application to invoke.

NFC Device Capabilities

The DeviceCapability class in the net.rim.device.api.system.capability package can help you determine what NFC features are available on the BlackBerry device. The DeviceCapability.isNFCSupported() method returns whether a device is NFC-capable. The DeviceCapability.isNFCAvailable() method returns whether the NFC feature is disabled by security policy, or disabled by the user through the Manage connections screen. You can implement the DeviceCapabilityListener interface in the net.rim.device.api.system.capability.listener package, and register it using DeviceCapability.addNFCListener() to receive notifications about changes in status of the NFC feature.

You can determine the NFC services that are available on the device using the NFCManager.getAvailableNFCServices() method. You can receive a notification of changes to the set of available NFC services by implementing the NFCStatusListener interface, and registering it using the NFCManager.addNFCStatusListener() method.

Registering menu item actions for specific patterns

You can create a specific action in your application, and then register this action with a pattern, using the net.rim.device.api.stringpattern.PatternRepository class. If the pattern is found in a NFC SmartPoster tag, the BlackBerry Data Tags application will create a button for device users to execute the corresponding command. Patterns are registered globally on the device, and when a pattern is found in other applications, it is underlined and a context menu item is created to run the corresponding command.

Next topic: SQLite
Previous topic: Location-based services

Was this information helpful? Send us your comments.