SHOW Signed

net.rim.device.api.io.file
Interface ExtendedFileConnection

All Superinterfaces:
Connection, FileConnection, InputConnection, OutputConnection, StreamConnection

public interface ExtendedFileConnection
extends FileConnection

This class provides RIM specific extensions to the FileConnection interface.

All ExtendedFileConnection instances have one underlying InputStream and one OutputStream. Opening an InputStream via openRawInputStream, openInputStream or openDataInputStream all count as opening an InputStream, and opening a OutputStream via openRawOutputStream, openOutputStream or openDataOutputStream all count as opening an OutputStream. A FileConnection instance can have only one InputStream and one OutputStream open at any one time. Trying to open more than one InputStream or more than one OutputStream from a StreamConnection causes an IOException. Trying to open an InputStream or an OutputStream after the ExtendedFileConnection has been closed causes an IOException.

Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Since:
JDE 4.2.0

Method Summary
 Category: Signed  void enableDRMForwardLock()
          Enable DRM forward lock for this connection.
 Category: Signed  CodeSigningKey getControlledAccess()
          Retrieves the CodeSigningKey on this file connection.
 Category: Signed  boolean isContentBuiltIn()
          Returns whether or not the content of the FileConnection is embedded into the device or not.
 Category: Signed  boolean isContentDRMForwardLocked()
          Returns whether the content is DRM forward locked or not.
 Category: Signed  boolean isFileEncrypted()
          Returns whether the content is encrypted or not.
 Category: Signed  Enumeration listWithDetails(String filter, boolean includeHidden)
          Returns a filtered list of files and directories contained in a directory.
 Category: Signed  InputStream openRawInputStream()
          Opens a raw input stream to the file; does not do automatic decryption unwrapping.
 Category: Signed  long rawFileSize()
          Returns the raw file size including the size of any DRM/encryption headers.
 Category: Signed  void setAutoEncryptionResolveMode(boolean mode)
          Set the automatic encryption resolve mode.
 Category: Signed  boolean setControlledAccess(CodeSigningKey csk)
          Set the CodeSigningKey on this file connection.
 
Methods inherited from interface javax.microedition.io.file.FileConnection
availableSize, canRead, canWrite, create, delete, directorySize, exists, fileSize, getName, getPath, getURL, isDirectory, isHidden, isOpen, lastModified, list, list, mkdir, openDataInputStream, openDataOutputStream, openInputStream, openOutputStream, openOutputStream, rename, setFileConnection, setHidden, setReadable, setWritable, totalSize, truncate, usedSize
 
Methods inherited from interface javax.microedition.io.Connection
close
 

Method Detail

enableDRMForwardLock

public void enableDRMForwardLock()
                          throws IOException
Enable DRM forward lock for this connection. DRM forward lock MUST be set before a file is created.

If a file is to be DRM forward locked it means that the file can only be opened by the device that created the file itself. The file should be transferred in an encrypted format preventing other devices from being able to read the original content.

Enabling DRM forward lock will wrap the file written out in an encrypted format so that it can not be read by other applications and will only be read by the device that the file was created on. Examples of file systems that do wrapping are store and SDCard

Throws:
IOException - If the connection is closed or the file already exists.
IllegalModeException - if the connection was not opened in Connector.WRITE mode.
Since:
JDE 4.2.0
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getControlledAccess

public CodeSigningKey getControlledAccess()
                                   throws IOException
Retrieves the CodeSigningKey on this file connection. The CodeSigningKey will be constructed from the file it it exists and there is a key set on the file. If the file has not yet been created the method will return the value that was provided to the last successful setControlledAcces method call; otherwise the method will return null.
Returns:
The code signing key associated with the file.
Throws:
IOException - If the connection is closed, or if the method is invoked on a directory.
IllegalModeException - if the connection was not opened in Connector.READ mode.
Since:
JDE 4.2.0
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

isContentBuiltIn

public boolean isContentBuiltIn()
                         throws IOException
Returns whether or not the content of the FileConnection is embedded into the device or not. Example is for pre-loaded media which is not deletable.
Returns:
Whether or not the content is built-in.
Throws:
IOException - If an I/O error occurs, if the connection is closed, if the method is invoked on a directory, the file does not yet exist, or the connection's target is not accessible.
IllegalModeException - if the connection was not opened in Connector.READ mode.
Since:
JDE 4.2.0
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

isContentDRMForwardLocked

public boolean isContentDRMForwardLocked()
                                  throws IOException
Returns whether the content is DRM forward locked or not. If a file is DRM forward locked it means that the file can only be opened by the device that created the file itself. The file will be transferred in an encrypted format preventing other devices from being able to read the original content.
Returns:
Returns if this connection is DRM forward locked or not.
Throws:
IOException - If an I/O error occurs, if the connection is closed, if the method is invoked on a directory, the file does not yet exist, or the connection's target is not accessible.
IllegalModeException - if the connection was not opened in Connector.READ mode.
Since:
JDE 4.2.0
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

isFileEncrypted

public boolean isFileEncrypted()
                        throws IOException
Returns whether the content is encrypted or not.
Returns:
Returns if this connection is encrypted or not.
Throws:
IOException - If an I/O error occurs, if the connection is closed, if the method is invoked on a directory, the file does not yet exist, or the connection's target is not accessible.
IllegalModeException - if the connection was not opened in Connector.READ mode.
Since:
JDE 4.2.0
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

listWithDetails

public Enumeration listWithDetails(String filter,
                                   boolean includeHidden)
                            throws IOException
Returns a filtered list of files and directories contained in a directory.
Parameters:
filter - String against which all files and directories are matched for retrieval. An asterisk ("*") can be used as a wildcard to represent 0 or more occurrences of any character.
includeHidden - boolean indicating whether files marked as hidden should be included or not in the list of files and directories returned.
Returns:
An Enumeration of net.rim.device.api.io.FileInfo objects.
Throws:
IOException - if invoked on a file, the directory does not exist, the connection is closed, the directory is not accessible, or an I/O error occurs.
IllegalModeException - if the application does have read access to the connection's target but has opened the connection in Connector.WRITE mode.
NullPointerException - if filter is null.
IllegalArgumentException - if filter contains any path specification or is an invalid filename for the platform (e.g. contains characters invalid for a filename on the platform).
Since:
JDE 4.2.0
See Also:
FileConnection.list(String, boolean)
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

openRawInputStream

public InputStream openRawInputStream()
                               throws IOException
Opens a raw input stream to the file; does not do automatic decryption unwrapping. This method is required to be able to transfer the raw file.
Returns:
Returns the raw input stream to the content.
Throws:
IOException - If an I/O error occurs, if the connection is closed, if the method is invoked on a directory, the file does not yet exist, or the connection's target is not accessible.
IllegalModeException - if the connection was not opened in Connector.READ mode.
Since:
JDE 4.2.0
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

rawFileSize

public long rawFileSize()
                 throws IOException
Returns the raw file size including the size of any DRM/encryption headers.

The rawFileSize method provides the exact length of the stream that is returned when calling openRawInputStream(). The raw length includes any encryption data that the root may need to write to the file to protect the data. In contrast the fileSize method provides the exact length of the data that is returned when calling openInputStream(). The length returned is just the length of the stored data itself and doesn't include any meta information that the root may have added.

Returns:
Returns the raw file size of the content, or -1 if the file does not exist or is not accessible.
Throws:
IOException - If an I/O error occurs, if the connection is closed, if the method is invoked on a directory, the file does not yet exist, or the connection's target is not accessible.
IllegalModeException - if the connection was not opened in Connector.READ mode.
Since:
JDE 4.2.0
See Also:
FileConnection.fileSize()
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setAutoEncryptionResolveMode

public void setAutoEncryptionResolveMode(boolean mode)
                                  throws IOException
Set the automatic encryption resolve mode. Where the filesystem automatically resolves file name entries to encrypted filenames. The default mode is on.

When the automatic encryption resolve mode is on the file system will always try to find a match for a file with a ".rem" extension before trying the filenames provided in any methods on the connection. REM file extensions indicate a wrapper for encrypted content and are only used on file systems that require wrapping objects, such as the SDCard root. The automatic resolve will occur on the first file access to the FileConnection so it is recommended that this method be called directly after opening the FileConnection.

Parameters:
mode - Whether file names should automatically be resolved to their encrypted name.
Throws:
IOException - If connection has been closed.
Since:
JDE 4.2.0
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

setControlledAccess

public boolean setControlledAccess(CodeSigningKey csk)
                            throws IOException
Set the CodeSigningKey on this file connection. Code signing keys MUST be set before a file is created. Once a code signing key has been set on a connection and that file is created any access to opening the input or output streams will assert that the calling code module has been signed by that key.

Enabling controlled access on a file may wrap the file written out in an encrypted format so that it can not be read by other applications. This wrapping may depend on the underlying file system root because some file systems may be able to store the controlled access key directly with the file. Examples of file systems do wrapping are SDCard root. Examples of file systems that do not do wrapping are store

Parameters:
csk - The code signing key to be set on this file.
Returns:
Whether or not the operation was successful. The operation is not successful if the csk parameter is null or setControlledAccess method has already been called.
Throws:
IOException - If the connection is closed, if the method is invoked on a directory, or the file already exists.
IllegalModeException - if the connection was not opened in Connector.WRITE mode.
Since:
JDE 4.2.0
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.


Copyright 1999-2007 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.