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 through an openRawInputStream, an openInputStream or an openDataInputStream is the same as opening an InputStream.

Opening an OutputStream through an openRawOutputStream, an openOutputStream or an openDataOutputStream is the same as opening an OutputStream.

A FileConnection instance can have only one InputStream and one OutputStream open at a time.

Trying to open more than one InputStream or more than one OutputStream from a StreamConnection throws an IOException.

Trying to open an InputStream or an OutputStream after the ExtendedFileConnection is closed throws an IOException.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

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 BlackBerry device, for example, pre-loaded media on a BlackBery device that cannot be deleted.
 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 for a filesystem that automatically resolves file name entries to encrypted filenames.
 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 DRM forward locked, the file can only be opened by the BlackBerry device that created the file. To prevent other devices from being able to read the original content, the file should be transferred in an encrypted format.

Enabling DRM forward lock wraps the written out file in an encrypted format. This prevents other applications from reading the file. The file can only be read by the BlackBerry device that the file is created on. Examples of file systems that wrap the written out file 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 applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

getControlledAccess

public CodeSigningKey getControlledAccess()
                                   throws IOException
Retrieves the CodeSigningKey on this file connection. The CodeSigningKey is constructed from the file,if it exists, and from a key set for the file. If the file does not yet exist, the method returns the value provided to the last successful invocation of the setControlledAcces method; otherwise the method returns 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 applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

isContentBuiltIn

public boolean isContentBuiltIn()
                         throws IOException
Returns whether or not the content of the FileConnection is embedded into the BlackBerry device, for example, pre-loaded media on a BlackBery device that cannot be deleted.
Returns:
a boolean value that indicates 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, if the file does not yet exist, or if 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 applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

isContentDRMForwardLocked

public boolean isContentDRMForwardLocked()
                                  throws IOException
Returns whether the content is DRM forward locked or not. If a file is DRM forward locked, it the file can only be opened by the BlackBerry device that created the file. The file is transferred in an encrypted format that prevents other devices from reading the original content of the file.
Returns:
a boolean that indicates 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, if the file does not yet exist, or if 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 applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

isFileEncrypted

public boolean isFileEncrypted()
                        throws IOException
Returns whether the content is encrypted or not.
Returns:
a boolean that indicates 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, if the file does not yet exist, or if 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 applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

listWithDetails

public Enumeration listWithDetails(String filter,
                                   boolean includeHidden)
                            throws IOException
Returns a filtered list of files and directories contained in a directory.
Parameters:
filter - a 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 - a boolean indicating whether files marked as hidden should be included in the list of files and directories that the method returns.
Returns:
An Enumeration of net.rim.device.api.io.FileInfo objects.
Throws:
IOException - if invoked on a file, if the directory does not exist, if the connection is closed, if the directory is not accessible, or if 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, for example, 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 applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

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, if the file does not yet exist, or if 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 applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

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 a call to openRawInputStream() returns. 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 a call to openInputStream() returns. The returned length is he length of the stored data and does n0t include meta information that the root may add.

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, if the file does not yet exist, or if 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 applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

setAutoEncryptionResolveMode

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

When automatic encryption resolve mode is set to 'on', the file system attempts to find a match for a file with a ".rem" extension before trying to find a match to filenames provided by methods on the connection. Files with an REM file extension are encrypted files and are only used on file systems that require wrapping objects, such as the SDCard root. An automatic resolve occurs during the first file access to the FileConnection. Applications should invoke this method direclty after opening the FileConnection.

Parameters:
mode - Whether file names should automatically resolve to their encrypted name.
Throws:
IOException - If the connection is closed.
Since:
JDE 4.2.0
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

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 the file is created, when an application opens an input or output stream, the calling module is checked to ensure it is signed by the key.

If controlled access is enabled for a file, the file that is written out may be wrapped in an encrypted format so that other applications cannot read it. Wrapping of the file may depend on the underlying file system root as some file systems may store the controlled access key directly with the file, for example, the SDCard root. An example of a file system that does not wrap the file is the store

Parameters:
csk - The code signing key to be set on this file.
Returns:
a boolean that indicates if 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 if 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 applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.



Copyright 1999-2009 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.