Accessing data on NDEF targets

The Contactless Communication API allows MIDlets to detect and read data from NDEF targets directly and in one go without having to separately specify the target type and opening a connection to the target. The MIDlet only needs to specify the type of NDEF record it is interested in. When the device detects an NDEF target that contains NDEF records of the specified type, a notification is sent to the MIDlet in the form of an NDEF message, which contains all the NDEF records from the NDEF target.

If you design your MIDlet to only read data from NFC devices or tags, use the present approach, since it is simpler to implement than first detecting contactless targets of the specified type and then opening a connection to those targets. However, if you need to write data to NFC devices or tags, use the latter approach to open an NDEFTagConnection to the target.

To access data on NDEF targets:

1. Import the required Contactless Communication API packages:

   // packages required for registering and implementing an NDEFRecordListener
   import javax.microedition.contactless.ContactlessException;
   import javax.microedition.contactless.DiscoveryManager;
   import javax.microedition.contactless.ndef.*;

2. Register an NDEFRecordListener for the desired NDEFRecordType by using the DiscoveryManager.addNDEFRecordListener method. If you want to register the NDEFRecordListener for multiple NDEF record types, call the method separately for each type.

   The following code snippet creates a custom method that registers the specified NDEFRecordListener for the specified NDEFRecordType (passed as parameters).

   NDEFRecordType recordType = new NDEFRecordType(NDEFRecordType.NFC_FORUM_RTD, "urn:nfc:wkt:Sp");
   
   // ...
   
   public void registerNDEFListener(NDEFRecordListener recordListener,
                                    NDEFRecordType recordType) {
   
       try {
           // create a DiscoveryManager instance
           DiscoveryManager discoveryManager = DiscoveryManager.getInstance();
           // register recordListener for recordType
           discoveryManager.addNDEFRecordListener(recordListener, recordType);
       } catch (SecurityException e) {
           // handle SecurityException from DiscoveryManager.getInstance()
       } catch (ContactlessException e) {
           // handle ContactlessException from discoveryManager.addNDEFRecordListener()
       } catch (IllegalStateException e) {
           // handle IllegalStateException from discoveryManager.addNDEFRecordListener()
       } catch (NullPointerException e) {
           // handle NullPointerException from discoveryManager.addNDEFRecordListener()
       }
   
   }

   NDEFRecordType consists of:

   • Record type name format, which specifies the syntax in which the record type name is presented

   • Record type name, which identifies the NDEF record type, that is, the content type of the NDEF record

   The Contactless Communication API supports the following record type name formats:

   • EMPTY for NDEF records with no type (and hence no record type name) associated with them

   • EXTERNAL_RTD for application-specific record type names that follow the NFC Forum naming conventions

   • MIME for MIME media types

   • NFC_FORUM_RTD for well-known NFC record type names that follow the NFC Forum Record Type Description (RTD)

   • UNKNOWN for NDEF records whose content ("payload") type is unknown

   • URI for absolute URIs

3. To handle returned NDEF records, implement the NDEFRecordListener you registered in the previous step.

   NDEFRecordListener defines the recordDetected method, which is called every time the device detects a contactless target that contains NDEF records of the specified type. The recordDetected method returns an NDEFMessage containing all the NDEF records (of any type) from the NDEF target.

   Depending on your MIDlet implementation, you can define the recordDetected method in the MIDlet main class, provided the main class implements NDEFRecordListener, or you can define the method in a custom class that implements NDEFRecordListener.

   The following code snippet creates a recordDetected method that retrieves and processes all the NDEF records from the returned NDEF message.

   public void recordDetected(NDEFMessage message) {
   
       // retrieve all records in the message
       NDEFRecord[] records = message.getRecords();
   
       for (int i=0; i<records.length; i++) {
           NDEFRecord record = records[i];
           // process the record using NDEFRecord methods
           // ...
       }
   
   }