Step 3 - Building the Menu Structure from a File
 | The aim of this step is to:
|
 | After completing this step you will be able to:
|
 | For this, you will use the following tools:
|
We will use the ADN (Abbreviated Dialing Number) File to store the contact information of the Zyrcon Cinemas. For this example, we will assume that the ADN File only contains Zyrcon Cinemas.
Let's start the File System Editor to check the current content of the ADN File.
The Card (Simulator) we are using is SIM Release 5.
The File System Editor opens but no readers are available.
So, let's start the SIM R5 Card Simulator. The easiest way to start a Card Simulator is to start to run / debug your project. You may also start an independent Card Simulator from the Start Menu.
We may now browse the File System to the EF ADN. The File is located at 3F00/7F10/6F3A or MF/DF_TELECOM/EF_ADN.
If you double click on the ADN File, you will get the details of all the records. For this, you will first need to verify the CHV of the Card Simulator: 1234.
Now, close this Verify CHV dialog and you get the content of the EF ADN:
We will now modify the EF ADN and add our two default Zyrcon Cinemas in the two first records of the EF ADN. For this, we will use the JCardManager.
Here are the APDU commands we shall send to the card:
| Description | APDU |
|---|---|
| Verify PIN [1234] | A0 20 00 01 08 31 32 33 34 FF FF FF FF |
| Select MF [ 3F00 ] | A0 A4 00 00 02 3F 00 |
| Select DF TELECOM [7F10] | A0 A4 00 00 02 7F 10 |
| Select EF ADN [6F3A] | A0 A4 00 00 02 6F 3A |
| Update Record [Berlin] | A0 DC 01 04 1C 42 65 72 6C 69 6E FF FF FF FF FF FF FF FF 08 91 00 94 03 76 98 21 43 FF FF FF FF FF |
| Update Record [London] | A0 DC 02 04 1C 4C 6F 6E 64 6F 6E FF FF FF FF FF FF FF FF 08 91 00 44 10 78 43 21 76 FF FF FF FF FF |
| Select MF [ 3F00 ] | A0 A4 00 00 02 3F 00 |
Within JCardManager, we first [1] choose Send APDU then, for each APDU Command, we will:
[2] Input the CLASS, INS, P1, P2 and Data, the length is automatically computed
[3] Give a name to the APDU Command and add it in the Command List
Once we have all our APDU Commands defined, we select them all in the Command List and [4] run them, using the 
Button.
This list of command may be saved 
as an ATF File to be reused as a Personalization File loaded when we start a debug/run session. Let's save it in our ZyrconCinemas Project as:
D:\WORK\MyWorkspace\ZyrconCinemas\Scripts\Step3_Update_ADN.atf
If we go back to our File System Editor, we will see that the records of the EF ADN have been updated. The context menu on the Record Viewer allows you to switch from Hexadecimal to ASCII.
Now, if we want this script to be run automatically when we start a debug / run session, we need to change the debug/run configuration for our Project.
Select the ZyrconCinemas Run Configuration and add your ATF File.
You will then have the following scripts:
Now, we are sure that the next time we run the Applet in either run or debug mode, we will have 2 Zyrcon Cinemas available right after powering on the Mobile Simulator. The only missing element is the business logic inside our Applet to effectively read the EF_ADN, get the existing records and build the menu items of our 'Cinemas' menu.
Here is the source code to insert in the menu1Action method:
| /** * Manage the Menu1 selection */ private void menu1Action() { // Get the received envelope ProactiveHandler proHdlr = ProactiveHandler.getTheHandler(); // Prepare the "Cinemas" STK Menu proHdlr.init(PRO_CMD_SELECT_ITEM, (byte) 0x00, (byte) ToolkitConstants.DEV_ID_ME); proHdlr.appendTLV((byte) (TAG_ALPHA_IDENTIFIER), Menu1, (short) 0x0000, (short) Menu1.length); // Reset the FCI Buffer resetBuffer(EFFciBuffer, (byte) 0x00); // Select ADN file and store ADN file properties in the FCI Buffer FileAccessLibrary.selectDF_telecom(gsmFile); FileAccessLibrary.selectEF(gsmFile, (short) 0x6F3A, EFFciBuffer); // Get the number of records and the length of each record short recCount = FileAccessLibrary.getLinearFileRecordNumber(EFFciBuffer); short recLength = FileAccessLibrary.getLinearFileRecordLength(EFFciBuffer); // Reset buffer resetBuffer(tempBuffer, (byte) 0xFF); // Append sub menu item for each record that not empty for (short i = 1; i <= recCount; i ++) { FileAccessLibrary.readRecord(gsmFile, i, tempBuffer, (short) recLength); if (!FileAccessLibrary.isEmptyRecord(tempBuffer)) { byte[] name = FileAccessLibrary.getNameFromAdnRecord(tempBuffer, recLength); proHdlr.appendTLV((byte) (TAG_ITEM), (byte) i, name, (short) 0x0000, (short) name.length); } } // select the MF to avoid locking the EF ADN FileAccessLibrary.selectMF(gsmFile); // send the proactive command proHdlr.send(); return; } |
As you might have noticed, this source code uses a Buffer to store the FCI (File Control Information) of the EF ADN, a resetBuffer method as well as some methods of a FileAccessLibrary.
We have to define the EFFciBuffer as a class variable.
| // Buffer for the FCI (File Control Information) private byte[] EFFciBuffer; |
And then initialize it in the Applet's constructor
| // Initialize the FCI Buffer EFFciBuffer = new byte[22]; |
Here is the code of the resetBuffer method:
| /** * Call this method to reset the buffer, fill with 0x00 * * @param buffer the buffer to be reset */ private static void resetBuffer(byte[] buffer, byte fillingByte) { Util.arrayFillNonAtomic(buffer, (short) 0, (short) buffer.length, (byte) fillingByte); } |
For the FileAccessLibrary, instead of coding it by ourselves, we will just import it as part of the UtilityLibrary Project. For this, extract the UtilityLibrary Project inside your Workspace (D:\WORK\MyWorkspace\) then go to the 'File' menu of Eclipse and choose 'Import...' then 'Existing Projects into Workspace'.
Then browse to your Workspace and select the UtilityLibrary Project.
You will see that this new Project also contain another library file, the SMSLibrary. We will use it later.
From our ZyrconCinemas Project Properties, we just have to specify that the Project also needs the UtilityLibrary Project.
Then, make sure that you import all the needed packages. An easy way to do that in Eclipse is to click the error icon or press Ctrl-1 and then choose the suggested fix for the error.
For the ToolkitConstants class, choose the sim.toolkit.ToolkitConstants package.
So, now our Project compiles. But the Java Card Conversion fails. The Export Files of the UtilityLibrary are not found. Some manual update of the Data Profile (GDP File) and the Build Profile (GBP File) are needed.
First, define the Export Files directory in your GDP File. Copy the following XML somewhere between the JCProject tags:
| <ExportPath> <Path Index="1" Value="D:\WORK\Workspace\UtilityLibrary\oncard"/> </ExportPath> |
Then, add the corresponding parameters in the GBP File, inside the jcconverter :
| <jcconverter pkgname="${JCProject.Application.Package.Name}" pkgaid="${JCProject.Application.Package.Aid}" pkgversion="${JCProject.Version.Major}.${JCProject.Version.Minor}" classdir="${JCProject.Path.ClassDir}" outputdir="${JCProject.Path.ConversionDir}" nobanner="yes" nowarn="no" out="CAP JCA EXP" verbose="no" outputfileproperty="conversion.outputfile"> <exportpath dir="${Mugel.Home}/cards/${JCProject.Card.Name}"> <include name="resources/exportfiles"/> </exportpath> <converterpath dir="${Mugel.Home}/cards/${JCProject.Card.Name}/lib/jctools"> <include name="**/*.jar"/> </converterpath> <exportpath dir="${JCProject.ExportPath.Path.1.Value}"/> <applet aid="${JCProject.Application.Applet.1.Aid}" classname="${JCProject.Application.Applet.1.ClassName}"/> </jcconverter> |
Our project now compiles and converts. Let's try it with the Mobile Simulator. When we go in the 'Cinemas' menu, we now see the items 'Berlin' and 'London'
In the next step, we will push some information to the Mobile using SMS. We will update the list of current movies.
Useful Files