com.siemens.mp.io
Class File

java.lang.Object
  com.siemens.mp.io.File

public class File

extends Object

The File class holds basic methods for accessing files on the phone's file system.

The first time you run any class method, a storage subfolder under the application folder is created. In general, ".." is forbidden in path specifications. Depending on the phone model, different further restrictions apply to the path specification:

SL45i, 6688i	On these phones only relative path specifications are allowed. 'Relative' means relative to the application's path. This means that a MIDlet may only access its storage folder and its subfolders. There is no way to create a subfolder, so all files are placed in the storage folder directly.
C55, C56, CT56, 2128	In addition to the relative path specifications, these phones allow access to the following folders: Ringing Tone, Bitmap and Animation. An absolute path specification always has to start with "a:\", that means the path specifications to the folders above are "a:\Ringing Tone", "a:\Bitmap" and "a:\Animation". For security reasons the user has to explicitly confirm the access to one of those folders. This happens only once per folder and per session.
S55, S56, S57, S57 SL55, M55	On these phones, path specifications are not restricted to any specific folder; "a:\" specifies the file system's root and an absolute path specification always has to start with this prefix. As with the phone models above, the user has to explicitly confirm the access to any folder. The phone keeps a history of the last 10 confirmed folders. Those 10 folders need only to be confirmed once per session, whereas accessing more than 10 folders may result in another confirmation request for a formerly already confirmed folder.

Example

Version:

20-11-2000

Field Summary

static int	INSIDE_STORAGE_PATH
static int	OUTSIDE_STORAGE_PATH
static String	STORAGE_DRIVE

Constructor Summary

File()

Method Summary

static String	buildPath(String fileName)
static int	checkFileName(String fileName) checkFileName
int	close(int fileDescriptor) Closes the file.
static int	copy(String source, String dest) Creates a file copy.
static int	debugWrite(String fileName, String infoString) Writes a given string at the end of the file specified by the file name.
static int	delete(String fileName) Deletes the file specified by its file name from the storage directory.
static int	exists(String fileName) Checks if the file specified by the file name exists
static boolean	isDirectory(String pathName) Checks if the given path specifies a directory
int	length(int fileDescriptor) Returns the file length, in bytes.
static String[]	list(String pathName) Lists the content of a directory
int	open(String fileName) Opens the file specified by the file name and prepares it for reading or writing.
int	read(int fileDescriptor, byte[] buf, int offset, int numBytes) Reads a maximum of numBytes bytes into a buffer from a file.
static int	rename(String source, String dest) Renames a file from source filename to destination filename.
int	seek(int fileDescriptor, int seekpos) Moves the file pointer to the specified location.
static int	spaceAvailable() Returns the free disk space (in bytes), available on the phone's file system.
static void	truncate(int fileDescriptor, int size) Set the size of a file
int	write(int fileDescriptor, byte[] buf, int offset, int numBytes) Writes numBytes bytes from buffer to a file.

Methods inherited from class java.lang.Object

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

Field Detail

OUTSIDE_STORAGE_PATH

public static final int OUTSIDE_STORAGE_PATH

See Also:

Constant Field Values

INSIDE_STORAGE_PATH

public static final int INSIDE_STORAGE_PATH

See Also:

Constant Field Values

STORAGE_DRIVE

public static final String STORAGE_DRIVE

See Also:

Constant Field Values

Constructor Detail

File

public File()

Method Detail

checkFileName

public static int checkFileName(String fileName)

checkFileName

Parameters:

fileName - Name of file to be checked

Returns:

OUTSIDE_STORAGE_PATH - if a full qualified path name is used INSIDE_STORAGE_PATH - if the specified file is inside the MIDlet storage path

Throws:

IllegalArgumentException - if specified file name violates security policies

debugWrite

public static int debugWrite(String fileName,
                             String infoString)

Writes a given string at the end of the file specified by the file name. It is useful for debug logging, because it requires no file opening and closing.

Parameters:

fileName - the name of the file to write to

infoString - the string that will be written to the file

Returns:

> 0 if successful

Throws:

IOException - if some other kind of I/O error occurs.

Example

open

public int open(String fileName)
         throws IOException

Opens the file specified by the file name and prepares it for reading or writing. On success the file is opened in binary (untranslated) mode. If the specified file does not exist, it will be created.

Parameters:

fileName - the name of the file to be opened

Returns:

file descriptor or < 0 if error occurred

Throws:

IllegalArgumentException - if the path is invalid

IOException - if some other kind of I/O error occurs.

Example

exists

public static int exists(String fileName)

Checks if the file specified by the file name exists

Parameters:

fileName - the name of the file

Returns:

< 0 if error occurred

Throws:

IllegalArgumentException - if the path is invalid

See Also:

copy, rename, delete

Example

seek

public int seek(int fileDescriptor,
                int seekpos)
         throws IOException

Moves the file pointer to the specified location. The file pointer is a starting position for the next read or write operation. The file must be opened before this method call.

Parameters:

fileDescriptor - file descriptor

seekpos - position to set the file pointer to i.e. the number of bytes from the beginning of the file

Returns:

the offset, in bytes, of the new position from the beginning of the file or < 0 if an error occurred

Throws:

IOException - if some kind of I/O error occurs.

See Also:

open, read, write

Example

length

public int length(int fileDescriptor)
           throws IOException

Returns the file length, in bytes. The file must be opened before this method call.

Parameters:

fileDescriptor - file descriptor

Returns:

< 0 if error occurred

Throws:

IOException

See Also:

open

Example

close

public int close(int fileDescriptor)
          throws IOException

Closes the file. After this method call, the specified file descriptor becomes invalid.

Parameters:

fileDescriptor - the file descriptor

Returns:

< 0 if error occurred

Throws:

IOException - if some kind of I/O error occurs.

See Also:

open

Example

write

public int write(int fileDescriptor,
                 byte[] buf,
                 int offset,
                 int numBytes)
          throws IOException

Writes numBytes bytes from buffer to a file. The file must be opened before this method call. The write operation begins at the current position of the file pointer. After the write operation, the file pointer is increased by the number of bytes actually written.

Parameters:

fileDescriptor - the file descriptor

buf - the bytearray with data to be written

offset - offset of the data to be written within the bytearray

numBytes - number of bytes to be written

Returns:

< 0 if error occurred

Throws:

IOException - if some kind of I/O error occurs.

See Also:

open, read, seek

Example

read

public int read(int fileDescriptor,
                byte[] buf,
                int offset,
                int numBytes)
         throws IOException

Reads a maximum of numBytes bytes into a buffer from a file. The file must be opened before this method call. The read operation begins at the current position of the file pointer. After the read operation, the file pointer points to the next unread character.

Parameters:

fileDescriptor - the file descriptor

buf - the buffer for the data to be read

offset - offset within the buffer for data to be read

numBytes - number of bytes to read

Returns:

number of bytes actually read, which may be less than numBytes if there are fewer than numBytes bytes left in the file, or < 0 if error occurred

Throws:

IOException - if some kind of I/O error occurs.

See Also:

open, write, seek

Example

delete

public static int delete(String fileName)
                  throws IOException

Deletes the file specified by its file name from the storage directory. Use this method with care, because the deleted file cannot be restored.

Parameters:

fileName - name of the file to be deleted

Returns:

1 if successful

Throws:

IllegalArgumentException - if the path is invalid

IOException - if some other kind of I/O error occurs.

See Also:

exists, copy, rename

Example

spaceAvailable

public static int spaceAvailable()
                          throws IOException

Returns the free disk space (in bytes), available on the phone's file system.

Returns:

available disk space in bytes

Throws:

IOException - if some kind of I/O error occurs.

Example

rename

public static int rename(String source,
                         String dest)
                  throws IOException

Renames a file from source filename to destination filename.

Parameters:

source - source name of the file

dest - destination name of the file

Returns:

< 0 if error occurred

Throws:

IllegalArgumentException - if the path is invalid

IOException - if some other kind of I/O error occurs.

See Also:

exists, copy, delete

Example

copy

public static int copy(String source,
                       String dest)
                throws IOException

Creates a file copy.

Parameters:

source - name of the source file

dest - name of the destination file (the file copy)

Returns:

< 0 if error occurred

Throws:

IllegalArgumentException - if the path is invalid

IOException - if some other kind of I/O error occurs.

See Also:

exists, rename, delete

Example

isDirectory

public static boolean isDirectory(String pathName)
                           throws IOException

Checks if the given path specifies a directory

Parameters:

pathName - the name of the path to be checked

Returns:

true if pathName specifies a directory - false otherwise

Throws:

IllegalArgumentException - if the path is invalid

IOException - if some kind of I/O error occurs.

Available on:

S55, S56, S57, S57C, SL55, M55

See Also:

open, copy, rename, delete

Example

list

public static String[] list(String pathName)
                     throws IOException

Lists the content of a directory

Parameters:

pathName - path to directory to be listed

Returns:

array of strings containing the files and subdirectories within the path

Throws:

IllegalArgumentException - if the path is invalid

IOException - if some kind of I/O error occurs.

Available on:

S55, S56, S57, S57C, SL55, M55

See Also:

open, copy, rename, delete

Example

buildPath

public static String buildPath(String fileName)

truncate

public static void truncate(int fileDescriptor,
                            int size)
                     throws IOException

Set the size of a file

Parameters:

fileDescriptor - the file descriptor

size - size to truncate the file stream to.

Returns:

< 0 if error occurred

Throws:

IOException - if some kind of I/O error occurs.

Available on:

S55, S56, S57, S57C, SL55, M55