Package net.rim.device.api.io.nfc

Provides access to the Near Field Communication (NFC) feature.

See:
          Description

Interface Summary
NFCFieldListener Receives notifications when an emulated target detects changes in the NFC field.
NFCStatusListener Receives notifications related to changes in NFC service information.
 

Class Summary
NFCManager Manages the status of NFC on the device.
 

Exception Summary
NFCException Represents an error that occurs during operations of the NFC API.
NFCInUseException Indicates that some exclusive NFC functionality, such as NFC virtual target emulation, is already in use.
 

Package net.rim.device.api.io.nfc Description

Provides access to the Near Field Communication (NFC) feature.

NFC is a short-range, wireless communication technology that enables contactless data exchange between electronic devices. NFC operates at 13.56 MHz, and can support communication at speeds up to 848 Kb per second. NFC-enabled devices are often designed to exchange data at appoximately 4 to 10 centimeters.

For more information about creating an NFC application for BlackBerry® devices, see the Networking and Connectivity Development Guide.

For more information about NFC technology and standards visit:

The BlackBerry Java SDK provides the ability to:

Listen for NFC targets in the vicinity

Applications can listen for NFC targets as follows:

Listen for any supported NFC target

public class NfcTargetDetector implements DetectionListener {

    public void onTargetDetected( final Target target ) {
        // do something with the target here
    }

}

public class MyNFCApp extends Application {

    public void myAppInitializationMethod() {
        try {
            ReaderWriterManager myRWManager = ReaderWriterManager.getInstance();
            myRWManager.addDetectionListener( new NFCTargetDetector(), new int[]{Target.NDEF_TAG} );

        } 
        catch ( NFCException e ) {
                // log error
        }
    }
}

Listen for NDEF messages


public class NDEFMessageDetector implements NDEFMessageListener {

    public void onNDEFMessageDetected( NDEFMessage msg ) {
        // do something with the NDEFMessage here
    }

}

public class MyNFCApp extends Application {

    public void myAppInitializationMethod() {
        try {
            ReaderWriterManager myRWManager = ReaderWriterManager.getInstance();
            myRWManager.addNDEFMessageListener( new NDEFMessageDetector(), NDEFRecord.TNF_ANY, null, false );
        } 
        catch ( NFCException e ) {
                // log error
        }
    }

}

Read from NFC tags

Applications can read NFC tags as follows:

Read a detected NDEF tag

public class NfcTargetDetector implements DetectionListener {

    public void onTargetDetected( final Target target ) {
        NDEFTagConnection c = null;
        try {
            c = (NDEFTagConnection)Connector.open(target.getUri(Target.NDEF_TAG));
            NDEFMessage ndefMessage = c.read();
            NDEFRecord[] ndefRecords = ndefMessage.getRecords();
            // do something with the NDEF records here
        } 
        catch (IOException e) {
            // error handling here
        }    
        finally {
            try {
                if (c != null) {
                    c.close();
                }
            } 
            catch (IOException e) {
            }
        }
    }

}

public class MyNFCApp extends Application {

    public void myAppInitializationMethod() {
        try {
            ReaderWriterManager myRWManager = ReaderWriterManager.getInstance();
            myRWManager.addDetectionListener( new NFCTargetDetector(), new int[]{Target.NDEF_TAG} );
        } 
        catch ( NFCException e ) {
                // log error
        }
    }

}

Read a detected non-NDEF tag


public class NfcTargetDetector implements DetectionListener {

    public void onTargetDetected( final Target target ) {
        ISO14443Part3Connection c = null;
        InputStream in = null;
        try {
            c = (ISO14443Part3Connection)Connector.open(target.getUri(Target.ISO_14443_3));
            // send request bytes to tag and get response
            byte[] response = c.transceive( new byte[] {0,1,2,3,4} );
        } 
        catch (IOException e) {
                // error handling here
        } 
        finally {
            try {
                if (in != null) {
                    in.close();
                }
                c.close();
            } 
            catch (IOException e) {
            }
        }
    }

}

public class MyNFCApp extends Application {

    public void myAppInitializationMethod() {
        try {
            ReaderWriterManager myRWManager = ReaderWriterManager.getInstance();
            myRWManager.addDetectionListener( new NFCTargetDetector(), new int[]{Target.ISO_14443_3} );
        }
        catch ( NFCException e ) {
                // error handling
        }
    }

}

Write NFC tags

Applications can write NFC tags as follows:

Write to a detected NDEF tag


This application writes a smart poster record to a tag.

public class NDEFWriterListener implements DetectionListener
{
    public NDEFWriterListener()
    {
        super();
    }

    public void onTargetDetected(Target target)
    {
        NDEFTagConnection c = null;
        try
        {
            NDEFMessage smartTag = createSmartTag();
            c = (NDEFTagConnection)Connector.open(
            target.getUri(Target.NDEF_TAG));
            c.write(smartTag);
            display.message("Successfully wrote to tag.");
        } catch (IOException e)
        {
            // error handling here
        }
    }

    private NDEFMessage createSmartTag() throws IOException
    {
        NDEFRecord titleRec = new NDEFRecord();
        titleRec.setId("1");
        titleRec.setType(NDEFRecord.TNF_WELL_KNOWN, "T");
        
        ByteArrayOutputStream payload1 = new ByteArrayOutputStream();
        payload1.write((byte) 0x05); // status byte - length of encoding
        payload1.write("en-US".getBytes("UTF-8")); // encoding
        payload1.write("My Title".getBytes("UTF-8")); // title
        payload1.flush();
        titleRec.setPayload(payload1.toByteArray());
        
        NDEFRecord uriRec = new NDEFRecord();
        uriRec.setId("2");
        uriRec.setType(NDEFRecord.TNF_WELL_KNOWN, "U");
        
        ByteArrayOutputStream payload2 = new ByteArrayOutputStream();
        payload2.write((byte) 0x01); // abbreviation: http://www.
        payload2.write("blackberry.com".getBytes("UTF-8")); // uri
        payload2.flush();
        uriRec.setPayload(payload2.toByteArray());
        
        NDEFMessage ndefMessage = new NDEFMessage();
        ndefMessage.setRecords(new NDEFRecord[] {titleRec, uriRec});

        // root message with one record that has in payload a nested
        // message in the form of bytes
        NDEFMessage rootMessage = new NDEFMessage();
        byte[] rootPayload = ndefMessage.getBytes();
        
        NDEFRecord rootRec = new NDEFRecord();
        rootRec.setType(NDEFRecord.TNF_WELL_KNOWN, "Sp");
        rootRec.setPayload(rootPayload);
        rootMessage.setRecords(new NDEFRecord[] {rootRec});
        
        return rootMessage;
    }
}

public class MyNFCApp extends Application {

    public void myAppInitializationMethod() {
        try {
            ReaderWriterManager myRWManager = ReaderWriterManager.getInstance();
            myRWManager.addDetectionListener( new NFCTargetDetector(), new int[]{Target.NDEF_TAG} );
        } 
        catch ( NFCException e ) {
            // error handling here
        }
    }

}

Write to a detected non-NDEF tag


public class NfcTargetDetector implements DetectionListener {

    public void onTargetDetected( final Target target ) {
        if (target.isType(Target.ISO_14443_3)) {
            ISO14443Part3Connection c = null;
            OutputStream out = null;
            try {
                c = (ISO14443Part3Connection)Connector.open(target.getUri(Target.ISO_14443_3));
                // Note: not a real command.  Command bytes need 
                // to be determined based on type of tag being written to
                byte[] response = c.transceive(new byte[]{0,1,2,3,4});
            } 
            catch (IOException e) {
                    // error handling here
            } 
            finally {
                try {
                    if (out != null)
                        out.close();
                } 
                catch (IOException e) {
                }
                try {
                    if (c != null)
                        c.close();
                }    
                catch (IOException e) {
                }
            }
        }
    }

}

public class MyNFCApp extends Application {

    public void myAppInitializationMethod() {
        try {
            ReaderWriterManager myRWManager = ReaderWriterManager.getInstance();
            myRWManager.addDetectionListener( new NFCTargetDetector(), new int[]{Target.ISO_14443_3} );
        } 
        catch ( NFCException e ) {
            // error hanlding here
        }
    }

}

Emulate tags or cards

Applications can emulate an NDEF tag to be read by an NFC capable reader by doing the following:

public class VirtualNDEFTagListener implements VirtualNDEFTagCallback {

    public void onVirtualTargetEvent(int tagEvent) {
        switch (tagEvent) {
            case VirtualNDEFTagCallback.EMULATION_STOPPED:
                    // emulation has stopped
                    break;
            case VirtualNDEFTagCallback.SELECTED:
                    // external reader has selected the tag
                    break;
            case VirtualNDEFTagCallback.TARGET_READ:
                    // external reader has read the tag
                    break;
            case VirtualNDEFTagCallback.TARGET_UPDATED:
                    // external reader has updated the tag
                    break;
            case VirtualNDEFTagCallback.READER_LEFT:
                    // external reader has left 
            default:
                    // ...
        }
    }

}

public class MyNFCApp extends Application {

    private VirtualNDEFTag vt;

    public void startNDEFEmulation() throws NFCException {
        NDEFMessage msg = null;
        try {
            msg = createSmartTag();
        } catch (IOException e) {
            // process error here
        }
        if(msg != null)
        {
            vt = new VirtualNDEFTag(msg, new VirtualNDEFTagListener());
            vt.startEmulation();
        } else
        {
            vt = null;
        }
    }
    
    public void stopNDEFEmulation() throws NFCException {
        if (vt != null ) {
            vt.stopEmulation();
        }
    }

    private NDEFMessage createSmartTag() throws IOException
    {
        NDEFRecord titleRec = new NDEFRecord();
        titleRec.setId("1");
        titleRec.setType(NDEFRecord.TNF_WELL_KNOWN, "T");
        
        ByteArrayOutputStream payload1 = new ByteArrayOutputStream();
        payload1.write((byte) 0x05); // status byte - length of encoding
        payload1.write("en-US".getBytes("UTF-8")); // encoding
        payload1.write("My Title".getBytes("UTF-8")); // title
        payload1.flush();
        titleRec.setPayload(payload1.toByteArray());
        
        NDEFRecord uriRec = new NDEFRecord();
        uriRec.setId("2");
        uriRec.setType(NDEFRecord.TNF_WELL_KNOWN, "U");
        
        ByteArrayOutputStream payload2 = new ByteArrayOutputStream();
        payload2.write((byte) 0x01); // abbreviation: http://www.
        payload2.write("blackberry.com".getBytes("UTF-8")); // uri
        payload2.flush();
        uriRec.setPayload(payload2.toByteArray());
        
        NDEFMessage ndefMessage = new NDEFMessage();
        ndefMessage.setRecords(new NDEFRecord[] {titleRec, uriRec});

        // root message with one record that has in payload a nested
        // message in the form of bytes
        NDEFMessage rootMessage = new NDEFMessage();
        byte[] rootPayload = ndefMessage.getBytes();
        
        NDEFRecord rootRec = new NDEFRecord();
        rootRec.setType(NDEFRecord.TNF_WELL_KNOWN, "Sp");
        rootRec.setPayload(rootPayload);
        rootMessage.setRecords(new NDEFRecord[] {rootRec});
        
        return rootMessage;
    }
    
}






Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal