Nokia 6131 User Manual
FORUM NOKIA
Nokia 6131 NFC SDK: Programmer’s Guide
Version 1.1; July 3, 2007
NFC
Copyright © 2007 Nokia Corporation. All rights reserved.
Nokia and Forum Nokia are trademarks or registered trademarks of Nokia Corporation. Java and all Java-based
marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other product and company names
mentioned herein may be trademarks or trade names of their respective owners.
Disclaimer
The information in this document is provided “as is,” with no warranties whatsoever, including any warranty of
merchantability, fitness for any particular purpose, or any warranty otherwise arising out of any proposal,
specification, or sample. This document is provided for informational purposes only.
Nokia Corporation disclaims all liability, including liability for infringement of any proprietary rights, relating to
implementation of information presented in this document. Nokia Corporation does not warrant or represent
that such use will not infringe such rights.
Nokia Corporation retains the right to make changes to this specification at any time, without notice.
License
A license is hereby granted to download and print a copy of this specification for personal use only. No other
license to any other intellectual property rights is granted herein.
Nokia 6131 NFC SDK: Programmer’s Guide
2
Contents
1 About this document................................................................................................................................ 5
1.1 Target audience........................................................................................................................................5
1.2 Typographical conventions...................................................................................................................5
2 Introduction................................................................................................................................................ 6
3 Using the API............................................................................................................................................... 7
3.1 Discovering a contactless target .........................................................................................................7
3.2 Exchanging NDEF formatted data.......................................................................................................9
3.3 Using JSR-257 API extensions...............................................................................................................9
3.3.1 SimpleTagConnection........................................................................................................ 10
3.3.2 MFStandardConnection..................................................................................................... 11
3.3.3 NFCIPConnection .................................................................................................................15
3.4 Exchanging data with external smart cards ................................................................................ 16
3.5 Connecting to internal card/tag of the Nokia 6131 NFC device.............................................17
4 Using branding configuration.............................................................................................................. 18
5 Using the MIDP 2.0 PushRegistry......................................................................................................... 20
5.1 NDEF record push ..................................................................................................................................20
6 Working with NDEF records..................................................................................................................21
6.1 RTD Text record......................................................................................................................................22
6.2 Hello World example with NDEF....................................................................................................... 23
7 Example MIDlets....................................................................................................................................... 24
7.1 SimpleNDEFExample.............................................................................................................................24
7.2 TicketingExample .................................................................................................................................. 24
7.3 InternalSecureCardExample...............................................................................................................24
7.4 MFStandardExample.............................................................................................................................24
7.5 P2PExample............................................................................................................................................. 24
7.6 BrandingExample.................................................................................................................................. 25
8 Terms and abbreviations.......................................................................................................................26
9 References .................................................................................................................................................27
10 Evaluate this resource ............................................................................................................................28
Nokia 6131 NFC SDK: Programmer’s Guide
3
Change history
March 27, 2007 Version 1.0 Initial document release
July 3, 2007 Version 1.1 Updated for Nokia 6131 NFC SDK 1.1
Nokia 6131 NFC SDK: Programmer’s Guide
4
1 About this document
This document describes how to develop MIDlets with Nokia 6131 NFC SDK 1.1 that use the Contactless
Communication API (JSR-257).
1.1 Target audience
The target audience of thi
Communication (NFC) card
Contactle
ss Communication API (JSR-257).
s document is mobile Java™ developers, whose target system has Near Field
s and the communication with these cards is handled trough the
1.2 Typographical conventions
The following typographical conventions are used in this document:
Convention Explanation
Bold Bold is used to indicate windows, views, pages and their elements, menu
items, and button names.
Italic Italics are used when referring to manuals. Italics are also used for key
terms and emphasis.
Courier
<variable data>
Courier is used to indicate parameters, file names, processes,
commands, directories, and source code text.
Variable data is written between the < and > characters. For example:
http://<ho
st>:<port>/directory
Nokia 6131 NFC SDK: Programmer’s Guide
5
2 Introduction
This is the Programmer's Guide for the Contactless Communication API (JSR-257), which is part of the
Software Development Kit for Nokia 6131 NFC (Nokia 6131 NFC SDK). The Contactless Communication
API aims to provide access to the information stored on various contactless targets. The API
functionalities are divided into five packages. The API contains mandatory and optional packages,
which all are included in the API implementation. However, some functionalities are left
unimplemented. This document also defines some Nokia implementation-specific additional
interfaces and classes that do not belong to the standard JSR-257.
Near Field Communication (NFC) is a short-range radio frequency technology that evolved from a
combination of contactless radio frequency identification (RFID) and interconnection technologies.
Operating over a distance of only a few centimeters, it allows users to read (and write) small amounts
of data from tags and to communicate with other devices by a simple touch. When touching a tag, the
NFC device reads the data stored on the tag and initiates the appropriate action after the user's
confirmation. For example, it can open a Web page, call a favorite number, or send an SMS message.
Small items such as Web links can also be shared by touching another NFC device.
Applications based on the Contactless Communication API can be developed and tested in a simulated
environment. The Nokia 6131 NFC SDK offers a full-blown development environment with NFC tag and
NFC smart card simulation, and communication to external card readers and devices supporting JSR257 as shown in
Figure 1.
Figure 1: Nokia 6131 NFC SDK development environment
Readers of this guide should have previous experience in developing MIDlets and be familiar with the
external card reader products. They should also have a basic knowledge of secure card technologies.
Before you start, refer to the
started with the Nokia 6131 NFC SDK. For information about the Nokia 6131 NFC device (for example,
NFC antenna area), see the User’s Guide of the device
[12].
Nokia 6131 NFC SDK: Programmer’s Guide
Nokia 6131 NFC SDK: User’s Guide [1] for more information on how to get
[2] or refer to the Nokia 6131 NFC device details
6
3 Using the API
Applications can determine the version of the Contactless Communication API present in the device by
checking the system property microedition.contactle
returned value is string "1.0"; otherwise the returned value is null.
Basically the use of this API consists of two phases: discovering contactless targets and data exchange
with those targets. There are different types of contactless targets. In the API, each contactless target
type is located in its own API package. This chapter describes how to discover contactless targets and
exchange data.
3.1 Discovering a contactless target
The starting point of using the API is to discover a contactless target, so that an application can
communicate with it. The API package javax.microedition.contactle
and interfaces needed in the contactless target discovery.
interfaces in the package.
Class / Interface Description
ss.version. If the API is present, the
ss contains the classes
Table 1 shortly describes classes and
TagConnection
TargetListener
Interface for all RFID tag and smart card-related connections.
Interface that provides a mechanism for discovering contactless
targets.
TransactionListener
Interface for security element activity notifications in card emulation
mode.
DiscoveryManager
TargetProperties
Class that offers a mechanism for contactless target discovery.
Class that collects properties that are common to the supported
contactless targets.
TargetType
ContactlessException
Table 1: Classes and interfaces in the javax.microedition.contactless package
Class that collects the contactless target types supported by the API.
Exception that is thrown when an unsupported operation is attempted.
In your application, you can discover only target types that are supported by the device. That is why
you should first ensure that the target type you are aiming to discover is supported. You can retrieve
information about supported target types by calling the
Di
scoveryManager.getSupportedTargetTypes() method, as shown in the following
example:
TargetType[] targets = DiscoveryManager.getSupportedTargetTypes();
The return value contains the list of target types supported by this API implementation. The possible
values are:
• TargetType.I
commands.
• TargetType.NDEF_TAG for a tag that contains NFC Forum formatted data.
• TargetType.RFID_TAG for general RFID tags.
Nokia 6131 NFC SDK: Programmer’s Guide
SO14443_CARD for ISO 14443-4 compliant smart cards accessed using APDU
7
Now, when you know the supported target types, you can set your application to listen for those
target types. For example, the following code snippet shows how you can discover tags supporting
NFC Forum formatted data.
DiscoveryManager dm = DiscoveryManager.getInstance();
try {
dm.addTargetListener(this, TargetType.NDEF_TAG);
}
catch (ContactlessException ce) {
// handle exception
}
Note that only one TargetLi
target type that already has a registered TargetLi
Illegal
TargetLi
StateException to be thrown. The code snippet below demonstrates
stener implementation by showing how to open the connection to the first found target
by using NDEFTagConnection. Note that the getUrl() method on TargetPropertie
stener for each TargetType is allowed. Setting a listener for a
stener will cause an
s returns
null on connections other than NDEF ones.
If the detected target contains NDEF formatted data, the first element in TargetProperties
contains the NDEF target.
public void targetDetected(TargetProperties[] prop) {
// Select the first found target
TargetProperties target = prop[0];
// Get URL to open the NDEF connection
String url = target.getUrl();
try {
// Open NDEFTagConnection to the target
NDEFTagConnection conn = (NDEFTagConnection)Connector.open(url);
// use the opened NDEFTagConnection.
}
catch (IOException ioe) {
// Handle exception
}
}
Note: There must not be more than one TargetLi
for one TargetListener is needed because the hardware handles only one connection to the
physical target at a time. The registration of TargetListener should fail if there is an existing
listener in other Java virtual machines or in the native platform. Therefore, it would be a good idea to
unregister the TargetListener in your MIDlet’s destroyApp(boolean unconditional)
method. Otherwise, other applications might not be capable of registering target listeners.
Connections to different contactless targets are designed on top of the Generic Connection Framework
(GCF). Each different target type defines a new protocol to the GCF. In practice, a connection opening to
a discovered contactless target can be made using the open method of
javax.microedition.io.Connector.
Note: Transaction events through Tran
NFC SDK. Adding a listener with the addTransactionListener method of DiscoveryManager
will cause a ContactlessException.
Nokia 6131 NFC SDK: Programmer’s Guide
stener for each TargetType. The restriction
sactionListener are not supported in the Nokia 6131
8
3.2 Exchanging NDEF formatted data
The NDEFTagConnection interface defines the basic functionality for exchanging NFC Forum
formatted data with contactless targets. The actual data is stored in the NDEFMe
containing the data in NDEFRecord
located in the javax.microedition.contactle
s. Those classes and the NDEFTagConnection interface are
ss.ndef package (see Table 2).
ssage object
Class / Interface Description
NDEFRecordListener
Interface that provides a mechanism for NDEF records discovery from
contactless targets.
NDEFTagConnection
NDEFMessage
NFEFRecord
NDERecordType
Table 2: Classes and interfaces in the javax.microedition.contactless.ndef package
Interface for exchanging NFC Forum formatted data.
Class representing an NDEF message.
Class representing an NDEF record.
Class that encapsulates the type of an NDEF record.
The NDEFTagConnection interface provides methods for reading and writing data. The
readNDEF() method reads NFC Forum formatted data from the target and the
writeNDEF(NDEFMe
ssage message) method writes NFC Forum formatted data in the NDEF
message to the target.
The NDEFRecordLi
stener provides a mechanism for the application to be notified when NDEF
records are discovered from the contactless targets. The notification is requested based on the NDEF
record type on the target. Through this notification the application has a read-only access to the data
on the target, but it has no possibility to open a connection to it. Applications based on JSR-257 must
implement this interface to receive the notification. The NDEFRecordLi
stener interface contains
one method that is called when registration rules are filled:
void recordDetected(NDEFMe
ssage ndefMessage)
You can add NDEFRecordListener to a certain NDEFRecortType by using DiscoveryManager’s
method addNDEFRecordLi
stener(NDEFRecordListener listener, NDEFRecordType
recordType). A registered listener can be removed by using the method
removeNDEFRecordLi
stener(NDEFRecordListener listener, NDEFRecordType
recordType). There can be multiple applications registered to receive notifications about different
NDEF records. Only one application can register a listener for a certain NDEF record type.
3.3 Using JSR-257 API extensions
The JSR-257 Contactless Communication API contains specific API extensions that provide interfaces for
communicating and accessing certain types of targets.
The Nokia 6131 NFC SDK supports all these extensions, but some of them are provided only as stub
implementations. With the stub implementation, developers are able to create and compile MIDlets
that use these API extensions using the Nokia 6131 NFC SDK, but they need to test and run those on a
real Nokia 6131 NFC device.
Table 3 lists all the JSR-257 API extensions and the level of support for each of them in the Nokia 6131
NFC SDK.
Nokia 6131 NFC SDK: Programmer’s Guide
9
Loading...