org.simalliance.openmobileapi

Class FileViewProvider

java.lang.Object

org.simalliance.openmobileapi.Provider

org.simalliance.openmobileapi.FileViewProvider

public class FileViewProvider
extends Provider

This Provider class simplifies file operations on Secure Elements with a file structure specified in ISO/IEC 7816-4. Methods are provided that allow reading or writing file content. If the read or write operation is not allowed because security conditions are not satisfied a SecurityException will be returned. It must be considered that a file operation can only be applied onto a file which has a corresponding structure.

Prerequisites: This Provider requires an ISO/IEC 7816-4 compliant file system on the SE. If this file system is implemented by an Applet within the SE then this Applet must be preselected before this Provider can be used, in case that the Applet is not default selected (e.g. the GSM Applet as default selected Applet on UICC)

Notes:

• If used by multiple threads, synchronization is up to the application.
• Each operation needs an access to the Secure Element. If the access can not be granted because of a closed channel or a missing security condition the called method will return an error.
• Using the basic channel for accessing the file system of the UICC (provided by the default selected GSM Applet) implies the risk of interferences from the baseband controller as the baseband controller works internally on the basic channel and can modify the current file selected state on the basic channel any time. This means a file selection performed by this FileViewProvider does not guarantee a permanent file selection state on the ICC's basic channel and the application using the FileViewProvider has to take care of having the needed file selection state. The FileViewProvider itself cannot avoid interferences from the baseband Open Mobile API specification V2.0.2 29/63 controller on the basic channel but the risk could be minimized if the application using the FileViewProvider performs implicit selections for the file operation or performs the file selection immediately before the file operation.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	FileViewProvider.FCP File Control Parameter contain information of a selected file.
class	FileViewProvider.Record Record class serves as container for record data.

Field Summary

Fields

Modifier and Type	Field and Description
static int	APPEND_RECORD Indicates for record write operations that the record shell be appended.
static int	CURRENT_FILE Indicates for file operation methods that the currently selected file shall be used for the file operation.
static int	INFO_NOT_AVAILABLE Indicates that the demanded information is not available.

Constructor Summary

Constructors

Constructor and Description
FileViewProvider(Channel channel) Encapsulates the defined channel by a FileViewProvider object that can be used for performing file operations on it.

Method Summary

Methods

Modifier and Type	Method and Description
byte[]	readBinary(int sfi, int offset, int length) Reads content of the selected transparent file at the position specified by offset and length.
FileViewProvider.Record	readRecord(int sfi, int recNumber) Returns the record which corresponds to the specified record number.
int[]	searchRecord(int sfi, byte[] searchPattern) Returns the record numbers that contains the defined search pattern.
FileViewProvider.FCP	selectByFID(int fileID) Selects the file specified by the FID.
FileViewProvider.FCP	selectByPath(java.lang.String path, boolean fromCurrentDF) Selects the file specified by a path.
FileViewProvider.FCP	selectParent() Selects the parent DF of the current DF.
void	writeBinary(int sfi, byte[] data, int offset, int length) Writes the defined data into the selected file at the position specified by offset and length.
void	writeRecord(int sfi, FileViewProvider.Record rec) Writes a record into the specified file.

Methods inherited from class org.simalliance.openmobileapi.Provider

getChannel

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CURRENT_FILE

public static final int CURRENT_FILE

Indicates for file operation methods that the currently selected file shall be used for the file operation.

See Also:

Constant Field Values

INFO_NOT_AVAILABLE

public static final int INFO_NOT_AVAILABLE

Indicates that the demanded information is not available.

See Also:

Constant Field Values

APPEND_RECORD

public static final int APPEND_RECORD

Indicates for record write operations that the record shell be appended.

See Also:

Constant Field Values

Constructor Detail

FileViewProvider

public FileViewProvider(Channel channel)
                 throws java.lang.IllegalStateException

Encapsulates the defined channel by a FileViewProvider object that can be used for performing file operations on it.

Note: A file must be selected before a file operation can be performed. The file can be implicitly selected via a short file identifier (SFI) by the file operation method itself or explicitly by defining the file ID (FID) with selectByFID(int) or path with selectByPath(String, boolean).

Parameters:

channel - The channel that shall be used by this Provider for file operations.

Throws:

java.lang.IllegalStateException - if the defined channel is closed.

Method Detail

selectByPath

public FileViewProvider.FCP selectByPath(java.lang.String path,
                                boolean fromCurrentDF)
                                  throws java.lang.IllegalStateException,
                                         java.lang.IllegalArgumentException,
                                         java.lang.SecurityException,
                                         java.lang.UnsupportedOperationException,
                                         java.io.IOException

Selects the file specified by a path. The path references the Secure Element file by a path (concatenation of file IDs and the order of the file IDs is always in the direction "parent to child") in following notation: "DF1:DF2:EF1". e.g. "0023:0034:0043". The defined path is applied to the Secure Element as specified in ISO/IEC 7816-4. Note: For performing read or write operations on a file the last knot in the path must reference an EF that can be read or written.

Note:

• A file must be selected before a file operation can be performed.
• This method is based on the ISO/IEC 7816-4 command SELECT.

Parameters:

path - The path that references a file (DF or EF) on the Secure Element. This path shall not contain the current DF or MF at the beginning of the path.

fromCurrentDF - If true then the path is selected from the current DF, if false then the path is selected from the MF.

Returns:

The FCP containing information to the selected file.

Throws:

java.lang.IllegalStateException - if the defined channel is closed.

java.lang.IllegalArgumentException - if the file couldn't be selected. TODO: should be an IllegalReferenceError

java.lang.IllegalArgumentException - if the defined path is invalid.

java.lang.SecurityException - if the operation is not allowed because the security conditions are not satisfied.

java.lang.UnsupportedOperationException - if this operation is not supported.

java.io.IOException - Lower-lever API exception.

selectByFID

public FileViewProvider.FCP selectByFID(int fileID)
                                 throws java.lang.IllegalStateException,
                                        java.lang.IllegalArgumentException,
                                        java.lang.SecurityException,
                                        java.lang.UnsupportedOperationException,
                                        java.io.IOException

Selects the file specified by the FID. The file ID references the Secure Element file (DF or EF) by a FID. The FID consists of a two byte value as defined in ISO/IEC 7816-4.

Notes:

• A file must be selected before a file operation can be performed.
• This method is based on the ISO/IEC 7816-4 command SELECT.

Parameters:

fileID - The FID that references the file (DF or EF) on the Secure Element. The FID must be in the range of (0x0000-0xFFFF).

Returns:

The FCP containing information of the selected file.

Throws:

java.lang.IllegalStateException - if the defined channel is closed.

java.lang.IllegalArgumentException - if the file couldn't be selected. TODO: should be an IllegalReferenceError

java.lang.IllegalArgumentException - if the defined fileID is not valid.

java.lang.SecurityException - if the operation is not allowed because the security conditions are not satisfied.

java.lang.UnsupportedOperationException - if this operation is not supported.

java.io.IOException - Lower-lever API exception.

selectParent

public FileViewProvider.FCP selectParent()
                                  throws java.lang.IllegalStateException,
                                         java.lang.SecurityException,
                                         java.lang.UnsupportedOperationException,
                                         java.io.IOException

Selects the parent DF of the current DF. The parent DF of the currently selected file is selected according to ISO/IEC 7816-4. If the currently selected file has no parent then nothing will be done.

Note:

• A file must be selected before a file operation can be performed.
• This method is based on the ISO/IEC 7816-4 command SELECT.

Returns:

The FCP containing information of the selected file.

Throws:

java.lang.IllegalStateException - if the defined channel is closed.

java.lang.IllegalArgumentException - if the file couldn't be selected. TODO: should be an IllegalReferenceError

java.lang.SecurityException - if the operation is not allowed because the security conditions are not satisfied.

java.lang.UnsupportedOperationException - if this operation is not supported.

java.io.IOException - Lower-lever API exception.

readRecord

public FileViewProvider.Record readRecord(int sfi,
                                 int recNumber)
                                   throws java.lang.IllegalStateException,
                                          java.lang.IllegalArgumentException,
                                          java.lang.SecurityException,
                                          java.lang.UnsupportedOperationException,
                                          java.io.IOException

Returns the record which corresponds to the specified record number. If the record is not found then null will be returned.

Note: This method is based on the ISO/IEC 7816-4 command READ RECORD.

Parameters:

sfi - The SFI of the file which shall be selected for this read operation. CURRENT_FILE can be applied if the file is already selected. The sfi must be in the range of (1-30).

recNumber - The record number that references the record that should be read.

Returns:

The record which corresponds to the specified record ID.

Throws:

java.lang.IllegalStateException - if the used channel is closed, if no file is currently selected, if the currently selected file is not a record based file or if the record couldn't be read.

java.lang.IllegalArgumentException - if the file couldn't be selected via SFI. TODO: should be an IllegalReferenceError

java.lang.IllegalArgumentException - if the defined sfi is not valid or if the defined record ID is invalid.

java.lang.SecurityException - if the operation is not allowed because the security conditions are not satisfied.

java.lang.UnsupportedOperationException - if this operation is not supported.

java.io.IOException - Lower-lever API exception.

writeRecord

public void writeRecord(int sfi,
               FileViewProvider.Record rec)
                 throws java.lang.IllegalArgumentException,
                        java.lang.IllegalStateException,
                        java.lang.SecurityException,
                        java.lang.UnsupportedOperationException,
                        java.io.IOException

Writes a record into the specified file.

Note: This method is based on the ISO/IEC 7816-4 command APPEND RECORD and UPDATE RECORD (which replaces existing bytes).

Parameters:

sfi - The SFI of the file which shall be selected for this write operation. CURRENT_FILE can be applied if the file is already selected. The SFI must be in the range of (1-30).

rec - The Record that shall be written.

Throws:

java.lang.IllegalStateException - if the used channel is closed, if no file is currently selected, if the currently selected file is not a record based file or if the record couldn't be written.

java.lang.IllegalArgumentException - if the file couldn't be selected via SFI. TODO: should be an IllegalReferenceError

java.lang.IllegalArgumentException - if the defined Record is invalid, if the defined SFI is not valid.

java.lang.SecurityException - if the operation is not allowed because the security conditions are not satisfied.

java.lang.UnsupportedOperationException - if this operation is not supported.

java.io.IOException - Lower-lever API exception.

searchRecord

public int[] searchRecord(int sfi,
                 byte[] searchPattern)
                   throws java.lang.IllegalStateException,
                          java.lang.IllegalArgumentException,
                          java.lang.SecurityException,
                          java.lang.UnsupportedOperationException,
                          java.io.IOException

Returns the record numbers that contains the defined search pattern.

Note:This method is based on the ISO/IEC 7816-4 command SEARCH RECORD with simple search.

Parameters:

sfi - The SFI of the file which shall be selected for this search operation. CURRENT_FILE can be applied if the file is already selected. The sfi must be in the range of (1-30).

searchPattern - The pattern that shall match with Records.

Returns:

A list of record numbers (position 1..n of the record in the file) of the records which match to the search pattern. If no record matches then null will be returned.

Throws:

java.lang.IllegalStateException - if the used channel is closed, if no file is currently selected, if the currently selected file is not a record based file or if the data couldn't be searched.

java.lang.IllegalArgumentException - if the file couldn't be selected via SFI. TODO: should be an IllegalReferenceError

java.lang.IllegalArgumentException - if the defined SFI is not valid, if the search pattern is empty or if the search pattern is too long.

java.lang.SecurityException - if the operation is not allowed because the security conditions are not satisfied.

java.lang.UnsupportedOperationException - if this operation is not supported.

java.io.IOException - Lower-lever API exception.

readBinary

public byte[] readBinary(int sfi,
                int offset,
                int length)
                  throws java.lang.IllegalStateException,
                         java.lang.IllegalArgumentException,
                         java.lang.SecurityException,
                         java.lang.UnsupportedOperationException,
                         java.io.IOException

Reads content of the selected transparent file at the position specified by offset and length.

Note:This method is based on the ISO/IEC 7816-4 command READ BINARY.

Parameters:

sfi - The SFI of the file which shall be selected for this read operation. CURRENT_FILE can be applied if the file is already selected. The sfi must be in the range of (1-30).

offset - Defines the start point of the file where the data should be read.

length - Defines the length of the data which should be read. If set to 0, all possible data within the limit of ISO7816#MAX_COMMAND_DATA_LENGTH will be read.

Returns:

The data read from the file or null if no content is available.

Throws:

java.lang.IllegalStateException - if the used channel is closed, if no file is currently selected, if the currently selected file is not a transparent file or if the data couldn't be read.

java.lang.IllegalArgumentException - if the file couldn't be selected via SFI. TODO: should be an IllegalReferenceError

java.lang.IllegalArgumentException - if the defined sfi is not valid or if the defined offset and length couldn't be applied.

java.lang.SecurityException - if the operation is not allowed because the security conditions are not satisfied.

java.lang.UnsupportedOperationException - if this operation is not supported.

java.io.IOException - Lower-lever API exception.

writeBinary

public void writeBinary(int sfi,
               byte[] data,
               int offset,
               int length)
                 throws java.lang.IllegalStateException,
                        java.lang.IllegalArgumentException,
                        java.lang.SecurityException,
                        java.lang.UnsupportedOperationException,
                        java.io.IOException

Writes the defined data into the selected file at the position specified by offset and length.

Note:This method is based on the ISO/IEC 7816-4 command UPDATE BINARY.

Parameters:

sfi - The SFI of the file which shall be selected for this write operation. CURRENT_FILE can be applied if the file is already selected. The sfi must be in the range of (1-30).

data - The data which shall be written.

offset - Defines the position in the file where the data should be stored.

length - Defines the length of the data which shall be written.

Throws:

java.lang.IllegalStateException - if the used channel is closed, if no file is currently selected, if the currently selected file is not a transparent file or if the record couldn't be written.

java.lang.IllegalArgumentException - if the file couldn't be selected via SFI. TODO: should be an IllegalReferenceError

java.lang.IllegalArgumentException - if the defined sfi is not valid, if the defined data array is empty or too short or if the defined offset and length couldn't be applied.

java.lang.SecurityException - if the operation is not allowed because the security conditions are not satisfied.

java.lang.UnsupportedOperationException - if this operation is not supported.

java.io.IOException - Lower-lever API exception.