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.

The code module manager is the system service that manages the code modules on the device: it installs them, deletes them, and you can use it to retrieve information about installed modules.

Module types. The code module manager deals with modules on an individual basis, but when you're actually building modules, it's possible to build them in two types: singleton modules, and sibling modules.

Singleton modules are stand-alone: the produced cod file contains a single module.

Sibling modules provide a way of packaging together a series of modules into a single cod file. This provides a way for you to build a project that's larger than can fit into a singleton module. Sibling modules packaged together into a "sibling cod" are arranged with an "eldest module" (the first appearing in the cod) and a series of subsequent modules. If you want to add sibling modules to the system using the code module manager, you must add each sibling module separately: you may find it expedient to add the eldest module first, but it's not strictly necessary. You should add all the modules as part of a single transaction, however (see following).

Module handles can be transitory. The system can add and remove modules in the background at any time. This means that even though you may have once had a valid module handle for a module (even if you added the module yourself), it might become unexpectedly invalid. Most calls where you pass in a module handle can throw an IllegalArgumentException, and so you must be prepared to correctly handle the exception. Note that this is not the case for some of the methods that return status codes; these methods report invalid handles in their return arrays of status codes (with CodeModuleManager.CMM_HANDLE_INVALID).

Adding modules

To add modules, you should use the simple pattern of beginning a transaction, creating modules for each module in the transaction you want to write, and then ending the transaction:

 // begin with byte moduleBuffer[] containing your module's data
 int myModuleHandle;
 int myTransHandle = CodeModuleManager.beginTransaction();
 if( myTransHandle != 0 ) {
     int mLen = moduleBuffer.length();

     myModuleHandle = CodeModuleManager.createNewModule(mLen, moduleBuffer, mLen);

     if( myModuleHandle == 0 ) {
         // couldn't get a module handle! bail!
     } else {
         switch( CodeModuleManager.saveNewModule(myModuleHandle, true, myTransHandle) ) {
               case CMM_OK:
                    // fall through
               case CMM_OK_MODULE_OVERWRITTEN:
                  switch( endTransaction(myTransHandle) ) {
                      case CMM_TRANSACTION_COMPLETE:
                          // addition finished successfully
                          break;
                      case CMM_TRANSACTION_RESET_REQUIRED:
                          // device needs to reset to finish the transaction
                          // ... do the reset work here ...
                          break;
                      default:
                          // transaction failed for some reason; since transactions are all
                          // or nothing, it will cancel itself and clean up the module handle
                          break;
                  } // switch block for endTransaction()
                  break;
               default:
                  // couldn't save the module for some reason, and so the CMM hasn't built an
                  // an association between the transaction handle and the module handle:
                  // we must clean up the module handle ourselves.
                  CodeModuleManager.deleteNewModule(myModuleHandle);
                  break;
         } // switch block for saveNewModule()
     }
 }
 

By using transactions, the VM knows when you're done loading modules and can attempt to link and load them if no reset is required (your modules are not replacing modules that are in use or that have persisted data).

Retrieving information about loaded modules

You can use the code module manager to retrieve information about modules already loaded.

Retrieve a module handle. Many of the manager's exposed methods require you to provide a module handle. If you don't already have one, but you know the module's name, you can use CodeModuleManager.getModuleHandle(String) to retrieve the appropriate handle (if you got the module's name wrong, and there isn't one such module saved in the system, you'll get back a value of 0):

 int handle = CodeModuleManager.getModuleHandle("someModuleName");
 

You can also get back a matching module handle by providing the module's hash value (retrieved by invoking getModuleHash(handle)) or a class that's defined within the module (by providing the class's Class object to CodeModuleManager.getModuleHandleForClass(Class), or an instance of the class to CodeModuleManager.getModuleHandleForObject(Object)).

If you want a list of all the modules the code module manager currently has registered, then you can invoke CodeModuleManager.getModuleHandles(boolean).

Retrieve information about an installed module. Once you have the module's handle, you can get back a variety of information about the module:

 try {
     // 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 );
 } catch( IllegalArgumentException iae ) {
     // deal with an invalid module handle
 }
 

Deleting modules

There are several things consider when you need to delete a module from the device.

Delete a new module. If you have yet to save the module with saveNewModule(handle), then the module is still "new", and so you must delete it with deleteNewModule(handle).

Delete a single, saved module. After the module gets saved, you must use deleteModuleEx(handle,force) or deleteModuleEx(handle,force,markOnly).

 int mh = CodeModuleManager.getModuleHandle("ModuleName");
 if( mh!=0 ) {
     try {
         int retCode = CodeModuleManager.deleteModuleEx(mh, force, markOnly);
     } catch( IllegalArgumentExcpetion iae ) {
         // deal with attempt to delete a now invalid handle
     }
 }
 

Delete a list of saved modules. If you want to delete more than one module, then you should batch the deletes together. Each time you delete a saved module, the VM must perform a garbage collection; by batching the delete operations together, the VM can do the GC once, rather than between each deletion. Note that the method that batches module deletes together doesn't throw an exception if it encounters an invalid handle; rather it passes this information back through its return codes:

 int[] retCodes = CodeModuleManager.deleteModules( arrayOfValidModHandles[], force );
 

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)
          Registers a CodeModuleListener to recieve code module events.
Category: Signed static int createNewModule(int totalLength)
          Allocates space for a new module.
Category: Signed static int createNewModule(int totalLength, byte[] data, int length)
          Allocates space for a new module and populates it with data.
Category: Signed static boolean deleteModule(int moduleHandle, boolean force)
          Deprecated. Use CodeModuleManager.deleteModuleEx(int,boolean) instead.
Category: Signed static int deleteModuleEx(int moduleHandle, boolean force)
          Deletes a module identified by handle.
Category: Signed static int deleteModuleEx(int moduleHandle, boolean force, boolean markOnly)
          Deletes (or marks for deletion) a module identified by handle.
Category: Signed static int[] deleteModules(int[] moduleHandles, boolean force)
          Deletes a series of modules identified by handle.
Category: Signed static int[] deleteModules(int[] moduleHandles, boolean force, boolean markOnly)
          Deletes (or marks for deletion) a series of modules identified by handle.
Category: Signed static int deleteNewModule(int newModuleHandle)
          Deletes a new, unsaved module.
Category: Signed static ApplicationDescriptor[] getApplicationDescriptors(int moduleHandle)
          Retrieves all the application descriptors from a module.
Category: Signed static String getModuleAliasName(int moduleHandle, int index)
          Retrieves a module's alias name.
Category: Signed static int getModuleCodeSize(int moduleHandle)
          Retrieves the size (in bytes) of a module's code section.
Category: Signed static String getModuleDescription(int moduleHandle)
          Retrieves a modules description.
Category: Signed static long getModuleDownloadTimestamp(int moduleHandle)
          Retrieves the download timesamp for a module.
Category: Signed static int getModuleFlags(int moduleHandle)
          Retrieves a module's flags.
Category: Signed static int getModuleHandle(byte[] hash)
          Retrieves the handle for the module with your provided hash.
Category: Signed static int getModuleHandle(String name)
          Retrieves the handle for the module with your provided name.
Category: Signed static int getModuleHandleForClass(Class clazz)
          Returns the handle of the module that defines the given Class.
Category: Signed static int getModuleHandleForObject(Object obj)
          Retrieves the handle for the module that contains the class definition for your provided object instance.
Category: Signed static int[] getModuleHandles()
          Retrieves a list of handles for all singleton and eldest-sibling modules.
Category: Signed static int[] getModuleHandles(boolean includeSiblings)
          Retrieves a list of handles for all existing modules (including, or not including, younger sibling modules).
Category: Signed static byte[] getModuleHash(int moduleHandle)
          Retrieves a module's hash.
Category: Signed static boolean getModuleHash(int moduleHandle, byte[] moduleHash)
          Writes a module's hash into provided byte array.
Category: Signed static String getModuleName(int moduleHandle)
          Retrieves a module's name.
Category: Signed static String getModuleName(int moduleHandle, int index)
          Retrieves a module's name.
Category: Signed static byte[] getModuleSignature(int moduleHandle, int signerId)
          Retrieves the signature data for one of a module's signatures.
Category: Signed static int getModuleSignerId(int moduleHandle, int index)
          Retrieves the signer ID for one of a module's signatures.
Category: Signed static long getModuleTimestamp(int moduleHandle)
          Retrieves a module's creation time.
Category: Signed static String getModuleURL(int moduleHandle)
          Retrieves a module's URL.
Category: Signed static String getModuleVendor(int moduleHandle)
          Retrieves a module's vendor information.
Category: Signed static String getModuleVersion(int moduleHandle)
          Retrieves a module's version string.
Category: Signed static String getModuleVersion(int moduleHandle, int index)
          Retreives a module's version string.
Category: Signed static int getNumMidlets()
          Retrieves the number of midlets installed on the device.
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 the device must reset in order to complete the addition or deletion of a module.
Category: Signed static void promptForResetIfRequired()
          Prompts the user to reset the device if a reset is required in order to complete the addition or deletion of a module.
Category: Signed static void removeListener(Application application, CodeModuleListener listener)
          Removes a registered CodeModuleListener from an 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, potentially forcing.
Category: Signed static boolean verifySignature(int moduleHandle, int signerId, byte[] publicKey)
          Verifies module signature against provided 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()
Retrieves a list of handles for all singleton and eldest-sibling modules.

This method retrieves a list of handles to all singleton modules, and the handle for all eldest modules amongst groups of siblings. It will not retrieve handles for any younger sibling modules.

Returns:
Array of handles to all singleton and eldest-sibling modules currently in the device's 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)
Retrieves a list of handles for all existing modules (including, or not including, younger sibling modules).

Parameters:
includeSiblings - If true, this method includes all younger sibling modules; otherwise, behaves just as CodeModuleManager.getModuleHandles().
Returns:
Array of handles for all singleton and eldest-sibling modules currently in the devices's database; if you provide a true parameter, also includes all the younger-sibling modules.
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)
Retrieves the handle for the module that contains the class definition for your provided object instance.

Note that getModuleHandleForObject(o) retrieves the same module handle as getModuleHandleForClass(o.getClass()).

Parameters:
obj - Instance of the class for which you want to find the defining module; must not be null. If your instance is an array, this method returns the handle to the module defining Object.
Returns:
Handle of the module that defines your instance's class.
Throws:
NullPointerException - If you provide a null paramter.
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 that defines the given Class.

Note that getModuleHandleForObject(o) retrieves the same module handle as getModuleHandleForClass(o.getClass()).

Parameters:
clazz - Class object for the class for which you want to find the defining module; must not be null.
Returns:
Handle of the module which defines the given class.
Throws:
NullPointerException - If you provide a null parameter.
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)
Retrieves the handle for the module with your provided name.

Parameters:
name - Name for the module to find.
Returns:
Module handle, or 0 if the system can find no module with your name.
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)
Retrieves the handle for the module with your provided hash.

This method retrieves the handle for the module matching the hash that can be originally retrieved by getModuleHash(handle).

Parameters:
hash - SHA hash of the module.
Returns:
Module handle, or 0 if the system can find no module with your hash.
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 CodeModuleManager.deleteModuleEx(int,boolean) instead.

Deletes a module identified by handle.

This method is deprecated; it is equivalent to invoking #deleteModuleEx(moduleHandle,force) and reporting true if the module was either immediately deleted, or successfully marked for deletion after a reset.

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 is not in use, and has no associated data.
Returns:
True if this method deleted the module, or marked it for deletion at next reset; otherwise, false.
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

deleteModuleEx

public static int deleteModuleEx(int moduleHandle,
                                 boolean force)
Deletes a module identified by handle.

There are three factors that prevent immediate deletion of a module: if the module is required, if the module is in use (because of active execution thread, or live class refs for which the module provides the definition), or if the module has persisted data (that is, the module defines classes instantiated by persisted data).

Module is required. IT Policy application control may require the presence of the module, and in that case, this method will do nothing and will return CodeModuleManager.CMM_MODULE_REQUIRED.

Module is in use or has persisted data. The device cannot delete the module without you forcing it to (by providing true to the 'force' parameter). If you want to force deletion (true), then this method will seek to mark the module for deletion after the next reset; if you don't want to force deletion (false), then this method will do nothing and return CodeModuleManager.CMM_MODULE_IN_USE_BY_PERSISTENT_STORE or USE, as appropriate.

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 persistent data and is not in use.
Returns:
One of the CMM_ return codes (if the module gets deleted, you should expect CodeModuleManager.CMM_OK; if the module gets marked for deletion after a reset, you should expect #CMM_MODULE_MARKED_FOR_DELETION).
Throws:
IllegalArgumentException - If you provide an invalid module 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 4.0.0

deleteModuleEx

public static int deleteModuleEx(int moduleHandle,
                                 boolean force,
                                 boolean markOnly)
Deletes (or marks for deletion) a module identified by handle.

There are times when you may not want to immediately delete a module, but may want to schedule it for deletion after the next reset. You can use this method to do that, with the 'markOnly' paramter:

If you provide false for 'markOnly', then this method behaves exactly as does CodeModuleManager.deleteModuleEx(int,boolean). The method will only delete modules in use, or with associated persisted data, if you provide true for the 'force' parameter.

If you provide true for 'markOnly', then this method ignores the actual value of the 'force' parameter, and behaves as if it were true.

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. This parameter's value is only meaningful if 'markOnly' is false.
markOnly - If true, this method marks the module for deletion at the next reset, regardless of whether the module is in use or not; if false, then this method's behaviour is governed by the 'force' parameter.
Returns:
One of the CMM_ return codes (if the module gets deleted, you should expect CodeModuleManager.CMM_OK; if the module gets marked for deletion after a reset, you should expect #CMM_MODULE_MARKED_FOR_DELETION).
Throws:
IllegalArgumentException - If you provide an invalid module 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)
Deletes a series of modules identified by handle.

This method accepts an array of module handles and essentially deals with each module handle in the list, h, as if you'd invoked deleteModuleEx(h,force).

However, there are several points to note.

Return codes. This method returns an array containing return codes, writing the return code for each module deletion attempt into the corresponding index in the return code array.

Efficiency. This method is more efficient at deleting a series of modules than a series of invocations of deleteModuleEx(), because it restricts the VM's garbage collection to a single GC before attempting to delete the first module in the list. If you merely iterate over deleteModuleEx(), then the VM performs a GC before each deletion attempt.

Dealing with failure. The failure of an attempt to delete one module in the list doesn't stop this method from attempting to delete each subsequent module in the list. This method attempts to delete all the modules in the list. Note that, unlike deleteModuleEx, this method does not throw an illegal argument exception if it finds an invalid module in your list of handles. Rather, it will write CodeModuleManager.CMM_HANDLE_INVALID into the corresponding position in the return code array.

Required modules. If IT Policy application control requires the presence of any module in the list, this method doesn't delete that module (even if you try to force the deletion), and writes CodeModuleManager.CMM_MODULE_REQUIRED into the corresponding position in the return code array.

Forcing deletion. This method's 'force' parameter applies to every module handle in the array. If you provide false for the parameter, then any module in the list that's in use or has associated persistent data will not be deleted. If you provide true for the parameter, then any module in the list that is in use or has persistent data will get marked for deletion after the next reset.

Modules that are not in use and do not have associated persistent data will get immediately deleted regardless of your 'force' parameter's value.

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 is not in use and has no associated persistent data.
Returns:
An array containing a CMM_ return code corresponding to the attemp to delete each module.
See Also:
CodeModuleManager.deleteModuleEx(int,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.
Since:
BlackBerry API 6.0.0

deleteModules

public static int[] deleteModules(int[] moduleHandles,
                                  boolean force,
                                  boolean markOnly)
Deletes (or marks for deletion) a series of modules identified by handle.

This method behaves in comparison to CodeModuleManager.deleteModules(int[],boolean) just as CodeModuleManager.deleteModuleEx(int,boolean,boolean) behaves in comparison to CodeModuleManager.deleteModuleEx(int,boolean). That is, it provides you with the opportunity to postpone deletion for all modules in your list until after a device reset (by providing true for the 'markOnly' parameter).

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 is not in use and has no associated persistent data. This parameter's value is only meaningful if 'markOnly' is false.
markOnly - If true, this method marks each module for deletion after the next reset, regardless of whether the module is in use or not; if false, then this method's behaviour is governed by the 'force' parameter.
Returns:
An array containing a CMM_ return code for each handle (if a module gets deleted, you should expect CodeModuleManager.CMM_OK; if a module gets marked for deletion after a reset, you should expect #CMM_MODULE_MARKED_FOR_DELETION).
See Also:
CodeModuleManager.deleteModuleEx(int,boolean,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.
Since:
BlackBerry API 6.0.0

getModuleFlags

public static int getModuleFlags(int moduleHandle)
Retrieves a module's flags.

Example

 int value = getModuleFlags( myHandle );
 boolean wasInstalledOTA = ( value & CMM_MODULE_FLAG_OTA ) == CMM_MODULE_FLAG_OTA;
 

Parameters:
moduleHandle - Handle for the module.
Returns:
Value containing the modules flags; compare against the various CMM_MODULE_FLAG_* mask values to determine which are set for your module.
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

getModuleName

public static String getModuleName(int moduleHandle)
Retrieves a module's name.

Parameters:
moduleHandle - Handle for the module.
Returns:
Name of module.
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

getModuleVersion

public static String getModuleVersion(int moduleHandle)
Retrieves a module's version string.

A module's version information string gets set by the build process at build time. If the module's version string was not set at build time, or was set to an empty string, then this method uses the string "0.0".

Parameters:
moduleHandle - Handle for the module.
Returns:
Version information string, or "0.0" if the version info string was unset or set to an empty string at the module's build time.
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

getModuleHash

public static byte[] getModuleHash(int moduleHandle)
Retrieves a module's hash.

Parameters:
moduleHandle - Handle for the module.
Returns:
SHA hash of the module.
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

getModuleHash

public static boolean getModuleHash(int moduleHandle,
                                    byte[] moduleHash)
Writes a module's hash into provided byte array.

Note: If you provide an invalid module handle, this method does not throw an exception: rather, it returns false.

Parameters:
moduleHandle - Handle for the module.
moduleHash - Byte array to receive the hash data; this array must not be null, and must be initialized to store at least 20 bytes.
Returns:
True if this method successfully wrote the module's entire hash into your buffer; otherwise, false.
Throws:
IllegalArgumentException - If your provided buffer is too small.
NullPointerException - If you provide a null buffer.
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)
Retrieves the signer ID for one of a module's signatures.

You can use CodeSigningKey.convert(int) to convert the signer ID into a string form.

Parameters:
moduleHandle - Handle for the module.
index - Position (first is '0') of the signature in the list of signatures.
Returns:
Signer ID of the signature if found, or -1 if no such signature exists.
Throws:
IllegalArgumentException - If you provide an invalid module 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 4.0.0

getModuleSignature

public static byte[] getModuleSignature(int moduleHandle,
                                        int signerId)
Retrieves the signature data for one of a module's signatures.

Parameters:
moduleHandle - Handle for the module.
signerId - Signer ID (as retrieved by CodeModuleManager.getModuleSignerId(int,int)).
Returns:
Signature data contained in a byte array.
Throws:
IllegalArgumentException - If you provide an invalid module 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 4.0.0

getModuleVendor

public static String getModuleVendor(int moduleHandle)
Retrieves a module's vendor information.

A module's vendor information string gets set by the build process at build time. If the module's vendor string was not set at build time, or was set to an empty string, then this method uses the string "".

Parameters:
moduleHandle - Handle for the module.
Returns:
Vendor information string, or "" if the vendor info string was unset or set to an empty string at the module's build time.
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

getModuleDescription

public static String getModuleDescription(int moduleHandle)
Retrieves a modules description.

Parameters:
moduleHandle - Handle for the module.
Returns:
Description string, or null if the module has no description string.
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

getModuleURL

public static String getModuleURL(int moduleHandle)
Retrieves a module's URL.

Parameters:
moduleHandle - Handle for the module.
Returns:
URL string, or null if the module has no URL string.
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

getModuleTimestamp

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

Parameters:
moduleHandle - Handle for the module.
Returns:
Time in milliseconds since the device's origin time (midnight, Jan 1, 1970 UTC).
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

isLibrary

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

Parameters:
moduleHandle - Handle for the module.
Returns:
True if the specified module is a library; otherwise, false.
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

isMidlet

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

Parameters:
moduleHandle - Handle for the module.
Returns:
True if the specified module is a midlet; otherwise, false.
Throws:
IllegalArgumentException - If you provide an invalid module 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 4.0.0

getNumMidlets

public static int getNumMidlets()
Retrieves the number of midlets installed on the device.

Returns:
Number of midlets installed on the device.
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)
Retrieves the size (in bytes) of a module's code section.

Parameters:
moduleHandle - Handle for the module.
Returns:
Module's code size in bytes.
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

getModuleName

public static String getModuleName(int moduleHandle,
                                   int index)
Retrieves a module's name.

Each module contains a list of names for all the modules it references; the first name in the list (position 0) is always the name for 'this' module.

Parameters:
moduleHandle - Handle for the module.
index - Position (first is '0') of the name in the module's list of referred-to modules.
Returns:
Name for the module at provided position in the name list, or null if you try to retrieve a name that the module doesn't have (i.e. index value is out of range).
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

getModuleAliasName

public static String getModuleAliasName(int moduleHandle,
                                        int index)
Retrieves a module's alias name.

Parameters:
moduleHandle - Handle for the module.
index - Position (first is '0') of the name in the module's list of alias names.
Returns:
Alias name of module, or null if you try to retrieve an alias name that the module doesn't have (i.e. index value is out of range).
Throws:
IllegalArgumentException - If you provide an invalid module 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 4.1.0

getModuleVersion

public static String getModuleVersion(int moduleHandle,
                                      int index)
Retreives a module's version string.

Each module contains a list of version strings associated with the list of module names you can retrieve with CodeModuleManager.getModuleName(int,int): the version string for 'this' module is the first in the list (position 0).

A module's version information string gets set by the build process and build time. If the module's version string was not set at byuild time, or was set to an empty string, then this method uses the string "0.0".

Parameters:
moduleHandle - Handle for the module.
index - Position (first is '0') of the version string in the module's list of version strings.
Returns:
Version information string for the provided position in the version string list, or "0.0" if the version info string was unset or set to an empty string at the associated module's build time. This method can also return null if you try to retrieve a version string for a module name not into the module's list (i.e. your index value is out of range).
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

createNewModule

public static int createNewModule(int totalLength)
Allocates space for a new module.

If this method returns a valid handle, you should then make calls to CodeModuleManager.writeNewModule(int,int,byte[],int,int) to write the data into the allocated module record.

Parameters:
totalLength - Total number of bytes the device should set aside for module; this value must be the total length of the module data.
Returns:
Handle for the new module, or 0 if the manager couldn't allocate space for the new 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 totalLength,
                                  byte[] data,
                                  int length)
Allocates space for a new module and populates it with data.

Typically, to create a new module, you use this method passing in the module's entire data, with the 'length' parameter set to the same value as 'totalLength'. However, there may be cases where it's not expedient to write all of the module's data at once. In this case, you can provide the first segment of the module's data with this method, and then make calls to CodeModuleManager.writeNewModule(int,int,byte[],int,int) to write the rest of the module's data into the allocated module record.

Parameters:
totalLength - Total number of bytes the device should set aside for the module.
data - Module's data.
length - Number of bytes from the module's data to write, starting with data[0].
Returns:
Handle for the new module, or 0 if the manager couldn't allocated space for the new 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

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 for the new module.
data - Byte array of data to write; must not be null.
newModuleOffset - Byte offset into the module at which to write the data.
length - Number of bytes to write.
Returns:
True if this method was able to write all the bytes you indicated; otherwise, false.
Throws:
IllegalArgumentException - If you provide an invalid module handle.
NullPointerException - If you provide a null 'data' parameter.
OutOfMemoryError - If the device was unable to write a portion of your data.
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.

Use this method to write more data into a module newly allocated with CodeModuleManager.createNewModule(int) or CodeModuleManager.createNewModule(int,byte[],int).

Note that the 'newModuleOffset' parameter is the offset past the first byte of the written module data where you want to start writing new bytes (thus, a newModuleOffset of 0 means the method should write to the first byte of the module); the 'offset' parameter is the offset past the first byte of the 'data' array that you pass in, where this method should start reading bytes to write into the module.

It's up to you to keep track of the offset position in the already written module data that represents the "cursor" point (i.e.the last byte you wrote).

Parameters:
newModuleHandle - Handle for the new module.
newModuleOffset - Byte offset into the module at which to write the data.
data - Byte array of data to write; must not be null.
offset - Byte offset into the data array where this method should start reading data to write into the module.
length - Number of bytes to write.
Returns:
True if this method was able to write all the bytes you indicated; otherwise, false.
Throws:
IllegalArgumentException - If you provide an invalid module handle.
NullPointerException - If you provide a null 'data' parameter.
OutOfMemoryError - If the device was unable to write a portion of your data.
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.

This is a convenience method that wraps saveNewModule(moduleHandle,false,0).

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, potentially forcing.

This is a convenience method that wraps saveNewModule(moduleHandle,forceOverwrite,0).

You can use this version of the method to force-save a module in the case that it's replacing an existing module with incompatible persisted data.

Parameters:
newModuleHandle - Handle returned by CodeModuleManager.createNewModule(int).
forceOverwrite - Force this method to overwrite an older version of your new module.
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 new, unsaved module.

Note: Use this method only for newly created modules (ones that you have not yet saved); if you pass a module that's saved into the persisted module store, this method will report the handle as invalid.

Parameters:
newModuleHandle - Handle for the module.
Returns:
CodeModuleManager.CMM_OK if the module gets successfully deleted, or CodeModuleManager.CMM_HANDLE_INVALID if you provide an invalid module 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 4.0.0

isResetRequired

public static boolean isResetRequired()
Determines if the device must reset in order to complete the addition or deletion of a module.

Note: note that the value returned from this method is only reliable if the process attempting the addition/deletion of the module(s) is the one invoking this method.

Returns:
True if the device must reset to finish the module change; 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.2.0

promptForResetIfRequired

public static void promptForResetIfRequired()
Prompts the user to reset the device if a reset is required in order to complete the addition or deletion of a module.

Note: the process attempting the addition/deletion 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)
Retrieves all the application descriptors from a module.

Parameters:
moduleHandle - Handle for the module.
Returns:
Array of descriptors for the module, or null, if the module contains no application descriptors.
Throws:
IllegalArgumentException - If you provide an invalid module 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 3.6.0

verifySignature

public static boolean verifySignature(int moduleHandle,
                                      int signerId,
                                      byte[] publicKey)
Verifies module signature against provided public key.

Use this method to verify that a signer signed a module, given the signer's public key. Since more than one signature can envelope a module, you identify the signature to verify against by providing a signer ID. Returns true if the specified signature on the cod file verifies with the given public key.

Parameters:
moduleHandle - Handle for the module.
signerId - Signer ID of the signature to verify.
publicKey - Public key to verify the signature with; if the signer ID is one of the known signer IDs specified in CodeSigningKey, then you can provide null for this parameter, because the system already has access to the appropriate public key data.
Returns:
True if the identified signature on the module verifies with the provided (or identified by signature ID) public key.
Throws:
IllegalArgumentException - If you provide an invalid module handle.
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)
Retrieves the download timesamp for a module.

Parameters:
moduleHandle - Handle for the module.
Returns:
Number of milliseconds after the origin date when the module was downloaded.
Throws:
IllegalArgumentException - If you provide an invalid module 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 4.0.0

addListener

public static void addListener(Application application,
                               CodeModuleListener listener)
Registers a CodeModuleListener to recieve code module events.

Parameters:
application - Application providing the event thread that will process the events; must not be null.
listener - Listener to notify; must not be null.
Throws:
NullPointerException - If you provide a null listener or null application parameter.
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 a registered CodeModuleListener from an application's list of listeners.

Parameters:
application - Application that provided the event thread on which the listener was registered; must not be null.
listener - Listener to unregister; if this listener is null, or not in the list of your provided application, then this method does nothing.
Throws:
NullPointerException - If you provide a null application.
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-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal