net.rim.device.api.system
Class CodeModuleManager

java.lang.Object
  extended by net.rim.device.api.system.CodeModuleManager

public final class CodeModuleManager
extends Object

Manages the Java code modules installed on the device.

How to add sibling .cod files.

You need to write the data in two separate chunks. The first data chunk must be less than 64KB in size.

  1. To write the first data chunk, invoke CodeModuleManager.createNewModule( int totalLength, byte[] data, int length ).
  2. To write the second data chunk, invoke CodeModuleManager.writeNewModule( int newModuleHandle, byte[] data, int newModuleOffset, int length ).


Examples
 // Retrieve a handle for a module.
 int handle = CodeModuleManager.getModuleHandle("test_module");
 
 // Retrieve specific information about a module.
 String name = CodeModuleManager.getModuleName( handle );
 String vendor = CodeModuleManager.getModuleVendor( handle );
 String description = CodeModuleManager.getModuleDescription( handle );
 int version = CodeModuleManager.getModuleVersion( handle );
 int size = CodeModuleManager.getModuleCodeSize( handle );
 int timestamp = CodeModuleManager.getModuleTimestamp( handle );
 
 // Retrieve an array of handles for existing modules on a BlackBerry device
 int handles[] = CodeModuleManager.getModuleHandles();
 
Create a module without data
Invoke createNewModule() and provide the size of the module in bytes as a parameter.
 int handle = CodeModuleManager.createNewModule( 3000 );
 
Create a module with data

Invoke createNewModule(int, byte[], int), providing the following parameters:
• the length in bytes of the entire module
• the byte array to add to the module
• the length parameter to specify the number of bytes from the byte array to add to the start of the module

 
 static int createNewModule(int, byte[], int);
 
Write data into a module

You can write data into a code module in increments, as long as you know the offset at which to add data. Invoke writeNewModule() and provide a byte array of data as a parameter to this method.

 Boolean success = CodeModuleManager.writeNewModule(handle, 0, data, offset, data.length);
 
Save a module to the BlackBerry® device database

Invoke saveNewModule(int). If the module saves successfully, the method returns one of the result codes defined in the CodeModuleManager class.

 int result = CodeModuleManager.saveNewModule(handle);
 
Delete a module from the BlackBerry device database

Invoke deleteModuleEx(int, Boolean) and provide the following parameters:
• the handle of the module to delete
• a Boolean value to specify whether to delete the module and any data it contains, or to delete the module only if it does not have data associated with it

 int handle = CodeModuleManager.getModuleHandle("test_module");
 if( handle != 0 ) 
 {
     boolean success = CodeModuleManager.deleteModule( handle, true );
 }
 
If the module is in use, delete it when the BlackBerry device restarts.

Note that modules can be added and removed by the system in the background. Therefore, module handles can become invalid at any point. Any call that makes use of a module handle can throw an IllegalArgumentException; the caller needs to correctly handle this exception.

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:
BlackBerry API 3.6.0

Field Summary
Category: Signed static int CMM_HANDLE_INVALID
          The operation failed because the specified handle is invalid.
Category: Signed static int CMM_HASH_INVALID
          The operation failed due to an invalid hash.
Category: Signed static int CMM_MODULE_EXCLUDED
          The operation failed because the module is excluded by IT Policy from being present on the device
Category: Signed static int CMM_MODULE_INCOMPATIBLE
          The operation failed because the module is incompatible with an existing module.
Category: Signed static int CMM_MODULE_INVALID
          The operation failed because the module is invalid.
Category: Signed static int CMM_MODULE_IN_USE
          The operation failed because the module is currently in use.
Category: Signed static int CMM_MODULE_IN_USE_BY_PERSISTENT_STORE
          The operation failed because the module is currently in use by the persistent store.
Category: Signed static int CMM_MODULE_REQUIRED
          The operation failed because the module is required by IT Policy to be present on the device
Category: Signed static int CMM_OK
          The operation completed successfully.
Category: Signed static int CMM_OK_MODULE_MARKED_FOR_DELETION
          The operation completed successfully; the module has been marked for deletion at the next reset.
Category: Signed static int CMM_OK_MODULE_OVERWRITTEN
          The operation completed successfully; a module was overwritten and marked for deletion in the process.
Category: Signed static int CMM_OUT_OF_MEMORY
          The operation failed because the handheld is out of memory.
Category: Signed static int CMM_SIGNATURE_INVALID
          The operation failed due to an invalid signature.
Category: Signed static int MODULE_FLAG_DELETE
          The module is scheduled for deletion.
Category: Signed static int MODULE_FLAG_INSTALLED
          The module has been installed.
Category: Signed static int MODULE_FLAG_OTA
          The module is marked as having been loaded over-the-air.
 
Method Summary
Category: Signed static void addListener(Application application, CodeModuleListener listener)
          Adds a listener to receive CodeModuleListener events.
Category: Signed static int createNewModule(int length)
          Creates a new, empty module.
Category: Signed static int createNewModule(int totalLength, byte[] data, int length)
          Creates a new, partially populated module.
Category: Signed static boolean deleteModule(int moduleHandle, boolean force)
          Deprecated. Use deleteModuleEx instead.
Category: Signed static int deleteModuleEx(int moduleHandle, boolean force)
          Deletes a specific module.
Category: Signed static int deleteModuleEx(int moduleHandle, boolean force, boolean markOnly)
          Deletes a specific module.
Category: Signed static int[] deleteModules(int[] moduleHandles, boolean force)
          Deletes the specified modules.
Category: Signed static int[] deleteModules(int[] moduleHandles, boolean force, boolean markOnly)
          Deletes the specified modules.
Category: Signed static int deleteNewModule(int newModuleHandle)
          Deletes a newly created module.
Category: Signed static ApplicationDescriptor[] getApplicationDescriptors(int moduleHandle)
          Returns the application descriptors contained in the specified module.
Category: Signed static String getModuleAliasName(int moduleHandle, int index)
          Returns the alias name of a module.
Category: Signed static int getModuleCodeSize(int moduleHandle)
          Returns the size of a module's contained code.
Category: Signed static String getModuleDescription(int moduleHandle)
          Retrieves the description for a module.
Category: Signed static long getModuleDownloadTimestamp(int moduleHandle)
          Returns the download time of a module.
Category: Signed static int getModuleFlags(int moduleHandle)
          Returns the flags for the specified module.
Category: Signed static int getModuleHandle(byte[] hash)
          Returns the handle for the module with the specified SHA hash.
Category: Signed static int getModuleHandle(String name)
          Returns the handle for the module with the specified name.
Category: Signed static int getModuleHandleForClass(Class clazz)
          Returns the handle of the module which implements the given Class.
Category: Signed static int getModuleHandleForObject(Object obj)
          Returns the handle of the module which defines an object's class.
Category: Signed static int[] getModuleHandles()
          Returns handles for all existing modules.
Category: Signed static int[] getModuleHandles(boolean includeSiblings)
          Returns handles for all existing modules.
Category: Signed static byte[] getModuleHash(int moduleHandle)
          Returns the SHA hash of a module.
Category: Signed static boolean getModuleHash(int moduleHandle, byte[] moduleHash)
          Retrieves the hash of a module and places it into a byte array
Category: Signed static String getModuleName(int moduleHandle)
          Returns the name of a module.
Category: Signed static String getModuleName(int moduleHandle, int index)
          Returns the name of a base module.
Category: Signed static byte[] getModuleSignature(int moduleHandle, int signerId)
          Returns the signature on a module from the given signerId.
Category: Signed static int getModuleSignerId(int moduleHandle, int index)
          Returns the signerId of a signature on a module.
Category: Signed static long getModuleTimestamp(int moduleHandle)
          Returns a module's creation time.
Category: Signed static String getModuleURL(int moduleHandle)
          Returns the URL from which a module can be loaded.
Category: Signed static String getModuleVendor(int moduleHandle)
          Returns the vendor information for a module.
Category: Signed static String getModuleVersion(int moduleHandle)
          Returns the version of a module.
Category: Signed static String getModuleVersion(int moduleHandle, int index)
          Retrieves the version of a base module.
Category: Signed static int getNumMidlets()
          Returns the number of midlets installed.
Category: Signed static boolean isLibrary(int moduleHandle)
          Determines if a module is a library.
Category: Signed static boolean isMidlet()
          Determines if the current process is a midlet.
Category: Signed static boolean isMidlet(int moduleHandle)
          Determines if a module is a midlet.
Category: Signed static boolean isResetRequired()
          Determines if a reset is required to complete the installation or removal of a module.
Category: Signed static void promptForResetIfRequired()
          If a reset is required to complete installation or removal of a module, a dialog will be displayed prompting the user to reset.
Category: Signed static void removeListener(Application application, CodeModuleListener listener)
          Removes listener from the application's list of listeners.
Category: Signed static int saveNewModule(int newModuleHandle)
          Saves a newly created module in the database.
Category: Signed static int saveNewModule(int newModuleHandle, boolean forceOverwrite)
          Saves a newly created module in the database.
Category: Signed static boolean verifySignature(int moduleHandle, int signerId, byte[] publicKey)
          Returns true if the specified signature on the cod file verifies with the given public key.
Category: Signed static boolean writeNewModule(int newModuleHandle, byte[] data, int newModuleOffset, int length)
          Deprecated. Replaced by CodeModuleManager.writeNewModule(int,int,byte[],int,int).
Category: Signed static boolean writeNewModule(int newModuleHandle, int newModuleOffset, byte[] data, int offset, int length)
          Writes data into a newly created module.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

CMM_OK

public static final int CMM_OK
The operation completed successfully.

See Also:
Constant Field Values
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:
BlackBerry API 3.6.0

CMM_OK_MODULE_OVERWRITTEN

public static final int CMM_OK_MODULE_OVERWRITTEN
The operation completed successfully; a module was overwritten and marked for deletion in the process.

See Also:
Constant Field Values
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:
BlackBerry API 3.6.0

CMM_HASH_INVALID

public static final int CMM_HASH_INVALID
The operation failed due to an invalid hash.

See Also:
Constant Field Values
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:
BlackBerry API 3.6.0

CMM_SIGNATURE_INVALID

public static final int CMM_SIGNATURE_INVALID
The operation failed due to an invalid signature.

See Also:
Constant Field Values
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:
BlackBerry API 3.6.0

CMM_MODULE_INVALID

public static final int CMM_MODULE_INVALID
The operation failed because the module is invalid.

See Also:
Constant Field Values
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:
BlackBerry API 3.6.0

CMM_MODULE_INCOMPATIBLE

public static final int CMM_MODULE_INCOMPATIBLE
The operation failed because the module is incompatible with an existing module.

See Also:
Constant Field Values
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:
BlackBerry API 3.6.0

CMM_OK_MODULE_MARKED_FOR_DELETION

public static final int CMM_OK_MODULE_MARKED_FOR_DELETION
The operation completed successfully; the module has been marked for deletion at the next reset.

See Also:
Constant Field Values
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:
BlackBerry API 4.0.0

CMM_MODULE_IN_USE

public static final int CMM_MODULE_IN_USE
The operation failed because the module is currently in use.

See Also:
Constant Field Values
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:
BlackBerry API 4.0.0

CMM_MODULE_IN_USE_BY_PERSISTENT_STORE

public static final int CMM_MODULE_IN_USE_BY_PERSISTENT_STORE
The operation failed because the module is currently in use by the persistent store.

See Also:
Constant Field Values
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:
BlackBerry API 4.0.0

CMM_MODULE_REQUIRED

public static final int CMM_MODULE_REQUIRED
The operation failed because the module is required by IT Policy to be present on the device

See Also:
Constant Field Values
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:
BlackBerry API 4.0.0

CMM_HANDLE_INVALID

public static final int CMM_HANDLE_INVALID
The operation failed because the specified handle is invalid.

See Also:
Constant Field Values
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:
BlackBerry API 4.0.0

CMM_OUT_OF_MEMORY

public static final int CMM_OUT_OF_MEMORY
The operation failed because the handheld is out of memory.

See Also:
Constant Field Values
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:
BlackBerry API 4.1.0

CMM_MODULE_EXCLUDED

public static final int CMM_MODULE_EXCLUDED
The operation failed because the module is excluded by IT Policy from being present on the device

See Also:
Constant Field Values
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:
BlackBerry API 4.0.0

MODULE_FLAG_DELETE

public static final int MODULE_FLAG_DELETE
The module is scheduled for deletion.

See Also:
Constant Field Values
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:
BlackBerry API 3.6.0

MODULE_FLAG_OTA

public static final int MODULE_FLAG_OTA
The module is marked as having been loaded over-the-air.

See Also:
Constant Field Values
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:
BlackBerry API 3.6.0

MODULE_FLAG_INSTALLED

public static final int MODULE_FLAG_INSTALLED
The module has been installed.

See Also:
Constant Field Values
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:
BlackBerry API 4.0.0


Method Detail

getModuleHandles

public static int[] getModuleHandles()
Returns handles for all existing modules.

Returns:
An array of integers containing the handles of all modules in the database.
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:
BlackBerry API 3.6.0

getModuleHandles

public static int[] getModuleHandles(boolean includeSiblings)
Returns handles for all existing modules.

Parameters:
includeSiblings - Determines whether or not sibling modules are included in the results.
Returns:
An array of integers containing the handles of all modules in the database.
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:
BlackBerry API 4.1.0

getModuleHandleForObject

public static int getModuleHandleForObject(Object obj)
Returns the handle of the module which defines an object's class.

Parameters:
obj - Object for which you want to find the containing module.
Returns:
Handle of the module which defines your object's class. If your object is an array, this method treats it as an Object.
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:
BlackBerry API 3.6.0

getModuleHandleForClass

public static int getModuleHandleForClass(Class clazz)
Returns the handle of the module which implements the given Class.

Parameters:
clazz - Class for which you want to find the implementing module.
Returns:
Handle of the module which defines the given class.
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:
BlackBerry API 4.1.0

getModuleHandle

public static int getModuleHandle(String name)
Returns the handle for the module with the specified name.

Parameters:
name - Name of the module.
Returns:
Module handle, or 0 if no module with the specified name exists.
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:
BlackBerry API 3.6.0

getModuleHandle

public static int getModuleHandle(byte[] hash)
Returns the handle for the module with the specified SHA hash.

Parameters:
hash - SHA hash of the module.
Returns:
Module handle, or 0 if no module with the specified SHA hash exists.
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:
BlackBerry API 4.0.0

deleteModule

public static boolean deleteModule(int moduleHandle,
                                   boolean force)
Deprecated. Use deleteModuleEx instead.

Deletes a specific module.

If the module is currently in use, it will be deleted at the next reset.

If 'force' is false and the device contains data associated with the specified module, the module will not be deleted. If 'force' is true, then the module and any data associated with that module will be deleted.

The module may be required by IT Policy application control. If this is the case the module will not be deleted regardless of the state of the force flag.

Parameters:
moduleHandle - Handle of module to delete.
force - If true, delete the module and any data it owns ( unless IT Policy Application control requires the module ); if false, delete the module only if it has no associated data.
Returns:
True if the module was deleted immediately or was scheduled for deletion; otherwise, false.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

deleteModuleEx

public static int deleteModuleEx(int moduleHandle,
                                 boolean force)
Deletes a specific module.

If the module is currently in use, it will be deleted at the next reset.

If 'force' is false and the device contains data associated with the specified module, the module will not be deleted. If 'force' is true, then the module and any data associated with that module will be deleted.

The module may be required by IT Policy application control. If this is the case the module will not be deleted regardless of the state of the force flag.

Parameters:
moduleHandle - Handle of module to delete.
force - If true, delete the module and any data it owns ( unless IT Policy Application control requires the module ); if false, delete the module only if it has no associated data.
Returns:
One of the CMM_ return codes.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 4.0.0

deleteModuleEx

public static int deleteModuleEx(int moduleHandle,
                                 boolean force,
                                 boolean markOnly)
Deletes a specific module.

If the module is currently in use, it will be deleted at the next reset.

If 'force' is false and the device contains data associated with the specified module, the module will not be deleted. If 'force' is true, then the module and any data associated with that module will be deleted.

The module may be required by IT Policy application control. If this is the case the module will not be deleted regardless of the state of the force flag.

Parameters:
moduleHandle - Handle of module to delete.
force - If true, delete the module and any data it owns ( unless IT Policy Application control requires the module ); if false, delete the module only if it has no associated data.
markOnly - If true, the module will be marked for deletion at the next reset, regardless of whether the module is in use or not.
Returns:
One of the CMM_ return codes.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 6.0.0

deleteModules

public static int[] deleteModules(int[] moduleHandles,
                                  boolean force)
Deletes the specified modules.

If a module is currently in use, it will be deleted at the next reset.

If 'force' is false and the device contains data associated with a specified module, the module will not be deleted. If 'force' is true, then the module and any data associated with that module will be deleted.

The module may be required by IT Policy application control. If this is the case the module will not be deleted regardless of the state of the force flag.

Note this method is more efficient at deleting multiple modules than calling CodeModuleManager.deleteModuleEx(int, boolean) for each module.

Parameters:
moduleHandles - Handles of modules to delete.
force - If true, delete the module and any data it owns ( unless IT Policy Application control requires the module ); if false, delete the module only if it has no associated data.
Returns:
An array containing a CMM_ return code for each handle
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:
BlackBerry API 6.0.0

deleteModules

public static int[] deleteModules(int[] moduleHandles,
                                  boolean force,
                                  boolean markOnly)
Deletes the specified modules.

If a module is currently in use, it will be deleted at the next reset.

If 'force' is false and the device contains data associated with a specified module, the module will not be deleted. If 'force' is true, then the module and any data associated with that module will be deleted.

The module may be required by IT Policy application control. If this is the case the module will not be deleted regardless of the state of the force flag.

Note this method is more efficient at deleting multiple modules than calling CodeModuleManager.deleteModuleEx(int, boolean) for each module.

Parameters:
moduleHandles - Handles of modules to delete.
force - If true, delete the module and any data it owns ( unless IT Policy Application control requires the module ); if false, delete the module only if it has no associated data.
markOnly - If true, the module will be marked for deletion at the next reset, regardless of whether the module is in use or not.
Returns:
An array containing a CMM_ return code for each handle
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:
BlackBerry API 6.0.0

getModuleFlags

public static int getModuleFlags(int moduleHandle)
Returns the flags for the specified module.

Parameters:
moduleHandle - Handle to the module in question.
Returns:
A combination of the MODULE_FLAG_ values.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

getModuleName

public static String getModuleName(int moduleHandle)
Returns the name of a module.

Parameters:
moduleHandle - Handle to the module in question.
Returns:
Name of module.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

getModuleVersion

public static String getModuleVersion(int moduleHandle)
Returns the version of a module.

Parameters:
moduleHandle - Handle to the module in question.
Returns:
Version information string. If version is not set in the Java development project (.jdp) file, or set to an empty string, the method returns "0.0" (without the quotes).
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

getModuleHash

public static byte[] getModuleHash(int moduleHandle)
Returns the SHA hash of a module.

Parameters:
moduleHandle - Handle to the module in question.
Returns:
SHA hash of the module.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

getModuleHash

public static boolean getModuleHash(int moduleHandle,
                                    byte[] moduleHash)
Retrieves the hash of a module and places it into a byte array

Parameters:
moduleHandle - Handle to the module in question.
moduleHash - The hash for the module in question. The byte array must be initialized to store at least 20 elements.
Returns:
True if the hash for the given module handle was retrieved successfully and placed in the byte[] parameter, false otherwise.
Throws:
IllegalArgumentException - If moduleHash is initialized to store less than 20 elements.
NullPointerException - If moduleHash is null.
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:
BlackBerry API 4.1.0

getModuleSignerId

public static int getModuleSignerId(int moduleHandle,
                                    int index)
Returns the signerId of a signature on a module.

Parameters:
moduleHandle - Handle to the module in question.
index - Ordinal to the signature.
Returns:
the signerId of the signature.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
See Also:
CodeSigningKey.convert(int)
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:
BlackBerry API 4.0.0

getModuleSignature

public static byte[] getModuleSignature(int moduleHandle,
                                        int signerId)
Returns the signature on a module from the given signerId.

Parameters:
moduleHandle - Handle to the module in question.
signerId - The id of the signer.
Returns:
the bytes containing the signature.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 4.0.0

getModuleVendor

public static String getModuleVendor(int moduleHandle)
Returns the vendor information for a module.

Parameters:
moduleHandle - Handle to the module in question.
Returns:
Vendor information string. If vendor is not set in the Java development project (.jdp) file, it returns "<unknown>" (without the quotes).
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

getModuleDescription

public static String getModuleDescription(int moduleHandle)
Retrieves the description for a module.

Parameters:
moduleHandle - Handle to the module in question.
Returns:
Description string, or null if the module has no description string.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

getModuleURL

public static String getModuleURL(int moduleHandle)
Returns the URL from which a module can be loaded.

Parameters:
moduleHandle - Handle to the module in question.
Returns:
URL string, or null if the module has no URL string.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

getModuleTimestamp

public static long getModuleTimestamp(int moduleHandle)
Returns a module's creation time.

Parameters:
moduleHandle - Handle to the module in question.
Returns:
Time in milliseconds since the device's origin time (midnight, Jan 1, 1970 UTC).
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

isLibrary

public static boolean isLibrary(int moduleHandle)
Determines if a module is a library.

Parameters:
moduleHandle - Handle to the module in question.
Returns:
True if the specified module is a library; otherwise, false.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

isMidlet

public static boolean isMidlet(int moduleHandle)
Determines if a module is a midlet.

Parameters:
moduleHandle - Handle to the module in question.
Returns:
True if the specified module is a midlet; otherwise, false.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 4.0.0

getNumMidlets

public static int getNumMidlets()
Returns the number of midlets installed.

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:
BlackBerry API 4.0.0

isMidlet

public static boolean isMidlet()
Determines if the current process is a midlet.

Returns:
True if the current process is a midlet; otherwise, false.
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:
BlackBerry API 4.0.0

getModuleCodeSize

public static int getModuleCodeSize(int moduleHandle)
Returns the size of a module's contained code.

Parameters:
moduleHandle - Handle to the module in question.
Returns:
Module's code size in bytes.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

getModuleName

public static String getModuleName(int moduleHandle,
                                   int index)
Returns the name of a base module.

Parameters:
moduleHandle - Handle to the module in question.
index - Ordinal to the module name in question.
Returns:
Name of module, or null if the index is out of range.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

getModuleAliasName

public static String getModuleAliasName(int moduleHandle,
                                        int index)
Returns the alias name of a module.

Parameters:
moduleHandle - Handle to the module in question.
index - Ordinal to the module aliase name in question.
Returns:
Alias name of module, or null if the index is out of range.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 4.1.0

getModuleVersion

public static String getModuleVersion(int moduleHandle,
                                      int index)
Retrieves the version of a base module.

Parameters:
moduleHandle - Handle to the module in question.
index - Ordinal to the module name in question.
Returns:
Version information string. If version is not set in the Java development project (.jdp) file, or set to an empty string, it returns "0.0" (without the quotes). If the index is out of range, it returns null.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

createNewModule

public static int createNewModule(int length)
Creates a new, empty module. Do not use this method for sibling .cod files larger than 64KB.

Parameters:
length - Length in bytes to set aside for module.
Returns:
New module handle, or 0 if the module could not be created.
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:
BlackBerry API 3.6.0

createNewModule

public static int createNewModule(int totalLength,
                                  byte[] data,
                                  int length)
Creates a new, partially populated module.

If the number of bytes you have to provide (the length parameter) is less than the length of the module (the totalLength parameter), then you should write the rest of the data with subsequent invocations of CodeModuleManager.writeNewModule(int, byte[], int, int).

Parameters:
totalLength - Length in bytes of the entire module.
data - Byte array of data to write.
length - Number of bytes to write.
Returns:
New module handle, or 0 if the module could not be created.
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:
BlackBerry API 3.6.0

writeNewModule

public static boolean writeNewModule(int newModuleHandle,
                                     byte[] data,
                                     int newModuleOffset,
                                     int length)
Deprecated. Replaced by CodeModuleManager.writeNewModule(int,int,byte[],int,int).

Writes data into a newly created module.

Parameters:
newModuleHandle - Handle returned by CodeModuleManager.createNewModule(int).
data - Byte array of data to write.
newModuleOffset - Byte offset into the module at which to write the data.
length - Number of bytes to write.
Returns:
True if successful; false otherwise.
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:
BlackBerry API 3.6.0

writeNewModule

public static boolean writeNewModule(int newModuleHandle,
                                     int newModuleOffset,
                                     byte[] data,
                                     int offset,
                                     int length)
Writes data into a newly created module.

Parameters:
newModuleHandle - Handle returned by CodeModuleManager.createNewModule(int).
newModuleOffset - Byte offset into the module at which to write the data.
data - Byte array of data to write.
offset - Byte offset into the data.
length - Number of bytes to write.
Returns:
True if successful; false otherwise.
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:
BlackBerry API 4.0.0

saveNewModule

public static int saveNewModule(int newModuleHandle)
Saves a newly created module in the database.

If the module is excluded by application control IT policy this method will return CMM_MODULE_EXCLUDED.

Note:This method cannot save an empty module.

Parameters:
newModuleHandle - Handle returned by CodeModuleManager.createNewModule(int).
Returns:
One of the CMM_ return codes.
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:
BlackBerry API 3.6.0

saveNewModule

public static int saveNewModule(int newModuleHandle,
                                boolean forceOverwrite)
Saves a newly created module in the database.

If there is an existing module with the same name, 'forceOverwrite' is false and the device contains data associated with the existing module which is not compatible with the new module, the operation will fail and CMM_MODULE_INCOMPATIABLE will be returned.

If 'forceOverwrite' is true, then the existing module will be replaced, and any data associated with that module will be deleted.

If the module is excluded by application control IT policy this method will return CMM_MODULE_EXCLUDED.

Note:This method cannot save an empty module.

Parameters:
newModuleHandle - Handle returned by CodeModuleManager.createNewModule(int).
forceOverwrite - Force any existing module to be overwritten.
Returns:
One of the CMM_ return codes.
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:
BlackBerry API 4.0.0

deleteNewModule

public static int deleteNewModule(int newModuleHandle)
Deletes a newly created module.

Parameters:
newModuleHandle - Handle returned by CodeModuleManager.createNewModule(int).
Returns:
One of the CMM_ return codes.
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:
BlackBerry API 4.0.0

isResetRequired

public static boolean isResetRequired()
Determines if a reset is required to complete the installation or removal of a module.

Note: the process that performs the addition/removal of the module(s) must also be the process calling this method.

Returns:
true if a reset is required, false otherwise
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:
BlackBerry API 4.2.0

promptForResetIfRequired

public static void promptForResetIfRequired()
If a reset is required to complete installation or removal of a module, a dialog will be displayed prompting the user to reset.

Note: the process that performs the addition/removal of the module(s) must also be the process calling this method.

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:
BlackBerry API 4.2.0

getApplicationDescriptors

public static ApplicationDescriptor[] getApplicationDescriptors(int moduleHandle)
Returns the application descriptors contained in the specified module.

Parameters:
moduleHandle - A handle to the specified module.
Returns:
An ApplicationDescriptor array of descriptors contained in the specified module; null if there are no descriptors contained in the specified module.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 3.6.0

verifySignature

public static boolean verifySignature(int moduleHandle,
                                      int signerId,
                                      byte[] publicKey)
Returns true if the specified signature on the cod file verifies with the given public key.

Parameters:
moduleHandle - The handle of the module to be verified.
signerId - The id of the signature on the module to be verified.
publicKey - The public key to verify the signature with; this can be null if signerId is one of the known signer ids specified in CodeSigningKey.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
See Also:
ControlledAccess.verifyCodeModuleSignature(int,CodeSigningKey)
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:
BlackBerry API 4.0.0

getModuleDownloadTimestamp

public static long getModuleDownloadTimestamp(int moduleHandle)
Returns the download time of a module.

Parameters:
moduleHandle - Handle to the module in question.
Returns:
The time in milliseconds on the device when the module was downloaded.
Throws:
IllegalArgumentException - if the given handle does not correspond to a valid module
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:
BlackBerry API 4.0.0

addListener

public static void addListener(Application application,
                               CodeModuleListener listener)
Adds a listener to receive CodeModuleListener events.

Parameters:
application - The application whose event thread will process the notifications sent to listener.
listener - Listener for events.
Throws:
NullPointerException - if listener is null.
IllegalStateException - if this method is called when there is no Application object in the calling process.
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:
BlackBerry API 5.0.0

removeListener

public static void removeListener(Application application,
                                  CodeModuleListener listener)
Removes listener from the application's list of listeners. If listener is null or is not on the application's list of listeners, then this method does nothing.

Parameters:
application - The application whose event thread will no longer process the notifications sent to listener.
listener - Listener for events.
Throws:
IllegalStateException - If this method is called when there is no Application object in the calling process.
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:
BlackBerry API 5.0.0





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.