net.rim.device.api.system.CodeModuleManager
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public final class CodeModuleManager
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).
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).
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
}
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 );
| Field Summary | ||
|---|---|---|
|
static int |
CMM_HANDLE_INVALID
The operation failed because the specified handle is invalid. |
|
static int |
CMM_HASH_INVALID
The operation failed due to an invalid hash. |
|
static int |
CMM_MODULE_EXCLUDED
The operation failed because the module is excluded by IT Policy from being present on the device |
|
static int |
CMM_MODULE_INCOMPATIBLE
The operation failed because the module is incompatible with an existing module. |
|
static int |
CMM_MODULE_INVALID
The operation failed because the module is invalid. |
|
static int |
CMM_MODULE_IN_USE
The operation failed because the module is currently in use. |
|
static int |
CMM_MODULE_IN_USE_BY_PERSISTENT_STORE
The operation failed because the module is currently in use by the persistent store. |
|
static int |
CMM_MODULE_REQUIRED
The operation failed because the module is required by IT Policy to be present on the device |
|
static int |
CMM_OK
The operation completed successfully. |
|
static int |
CMM_OK_MODULE_MARKED_FOR_DELETION
The operation completed successfully; the module has been marked for deletion at the next reset. |
|
static int |
CMM_OK_MODULE_OVERWRITTEN
The operation completed successfully; a module was overwritten and marked for deletion in the process. |
|
static int |
CMM_OUT_OF_MEMORY
The operation failed because the handheld is out of memory. |
|
static int |
CMM_SIGNATURE_INVALID
The operation failed due to an invalid signature. |
|
static int |
MODULE_FLAG_DELETE
The module is scheduled for deletion. |
|
static int |
MODULE_FLAG_INSTALLED
The module has been installed. |
|
static int |
MODULE_FLAG_OTA
The module is marked as having been loaded over-the-air. |
| Method Summary | ||
|---|---|---|
|
static void |
addListener(Application application,
CodeModuleListener listener)
Registers a CodeModuleListener to recieve code module events. |
|
static int |
createNewModule(int totalLength)
Allocates space for a new module. |
|
static int |
createNewModule(int totalLength,
byte[] data,
int length)
Allocates space for a new module and populates it with data. |
|
static boolean |
deleteModule(int moduleHandle,
boolean force)
Deprecated. Use CodeModuleManager.deleteModuleEx(int,boolean) instead. |
|
static int |
deleteModuleEx(int moduleHandle,
boolean force)
Deletes a module identified by handle. |
|
static int |
deleteModuleEx(int moduleHandle,
boolean force,
boolean markOnly)
Deletes (or marks for deletion) a module identified by handle. |
|
static int[] |
deleteModules(int[] moduleHandles,
boolean force)
Deletes a series of modules identified by handle. |
|
static int[] |
deleteModules(int[] moduleHandles,
boolean force,
boolean markOnly)
Deletes (or marks for deletion) a series of modules identified by handle. |
|
static int |
deleteNewModule(int newModuleHandle)
Deletes a new, unsaved module. |
|
static ApplicationDescriptor[] |
getApplicationDescriptors(int moduleHandle)
Retrieves all the application descriptors from a module. |
|
static String |
getModuleAliasName(int moduleHandle,
int index)
Retrieves a module's alias name. |
|
static int |
getModuleCodeSize(int moduleHandle)
Retrieves the size (in bytes) of a module's code section. |
|
static String |
getModuleDescription(int moduleHandle)
Retrieves a modules description. |
|
static long |
getModuleDownloadTimestamp(int moduleHandle)
Retrieves the download timestamp for a module. |
|
static int |
getModuleFlags(int moduleHandle)
Retrieves a module's flags. |
|
static int |
getModuleHandle(byte[] hash)
Retrieves the handle for the module with your provided hash. |
|
static int |
getModuleHandle(String name)
Retrieves the handle for the module with your provided name. |
|
static int |
getModuleHandleForClass(Class clazz)
Returns the handle of the module that defines the given Class. |
|
static int |
getModuleHandleForObject(Object obj)
Retrieves the handle for the module that contains the class definition for your provided object instance. |
|
static int[] |
getModuleHandles()
Retrieves a list of handles for all singleton and eldest-sibling modules. |
|
static int[] |
getModuleHandles(boolean includeSiblings)
Retrieves a list of handles for all existing modules (including, or not including, younger sibling modules). |
|
static byte[] |
getModuleHash(int moduleHandle)
Retrieves a module's hash. |
|
static boolean |
getModuleHash(int moduleHandle,
byte[] moduleHash)
Writes a module's hash into provided byte array. |
|
static String |
getModuleName(int moduleHandle)
Retrieves a module's name. |
|
static String |
getModuleName(int moduleHandle,
int index)
Retrieves a module's name. |
|
static byte[] |
getModuleSignature(int moduleHandle,
int signerId)
Retrieves the signature data for one of a module's signatures. |
|
static int |
getModuleSignerId(int moduleHandle,
int index)
Retrieves the signer ID for one of a module's signatures. |
|
static long |
getModuleTimestamp(int moduleHandle)
Retrieves a module's creation time. |
|
static String |
getModuleURL(int moduleHandle)
Retrieves a module's URL. |
|
static String |
getModuleVendor(int moduleHandle)
Retrieves a module's vendor information. |
|
static String |
getModuleVersion(int moduleHandle)
Retrieves a module's version string. |
|
static String |
getModuleVersion(int moduleHandle,
int index)
Retreives a module's version string. |
|
static int |
getNumMidlets()
Retrieves the number of midlets installed on the device. |
|
static boolean |
isLibrary(int moduleHandle)
Determines if a module is a library. |
|
static boolean |
isMidlet()
Determines if the current process is a midlet. |
|
static boolean |
isMidlet(int moduleHandle)
Determines if a module is a midlet. |
|
static boolean |
isResetRequired()
Determines if the device must reset in order to complete the addition or deletion of a module. |
|
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. |
|
static void |
removeListener(Application application,
CodeModuleListener listener)
Removes a registered CodeModuleListener from an application's list of listeners. |
|
static int |
saveNewModule(int newModuleHandle)
Saves a newly created module in the database. |
|
static int |
saveNewModule(int newModuleHandle,
boolean forceOverwrite)
Saves a newly created module in the database, potentially forcing. |
|
static boolean |
verifySignature(int moduleHandle,
int signerId,
byte[] publicKey)
Verifies module signature against provided public key. |
|
static boolean |
writeNewModule(int newModuleHandle,
byte[] data,
int newModuleOffset,
int length)
Deprecated. Replaced by CodeModuleManager.writeNewModule(int,int,byte[],int,int). |
|
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 |
|---|
public static final int CMM_OK
public static final int CMM_OK_MODULE_OVERWRITTEN
public static final int CMM_HASH_INVALID
public static final int CMM_SIGNATURE_INVALID
public static final int CMM_MODULE_INVALID
public static final int CMM_MODULE_INCOMPATIBLE
public static final int CMM_OK_MODULE_MARKED_FOR_DELETION
public static final int CMM_MODULE_IN_USE
public static final int CMM_MODULE_IN_USE_BY_PERSISTENT_STORE
public static final int CMM_MODULE_REQUIRED
public static final int CMM_HANDLE_INVALID
public static final int CMM_OUT_OF_MEMORY
public static final int CMM_MODULE_EXCLUDED
public static final int MODULE_FLAG_DELETE
public static final int MODULE_FLAG_OTA
public static final int MODULE_FLAG_INSTALLED
| Method Detail |
|---|
public static int[] getModuleHandles()
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.
public static int[] getModuleHandles(boolean includeSiblings)
includeSiblings - If true, this method includes all younger sibling
modules; otherwise, behaves just as CodeModuleManager.getModuleHandles().
public static int getModuleHandleForObject(Object obj)
Note that
getModuleHandleForObject(o)
retrieves the same module handle as
getModuleHandleForClass(o.getClass()).
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.
NullPointerException - If you provide a null paramter.public static int getModuleHandleForClass(Class clazz)
Note that
getModuleHandleForObject(o)
retrieves the same module handle as
getModuleHandleForClass(o.getClass()).
clazz - Class object for the class for which you want to find the
defining module; must not be null.
NullPointerException - If you provide a null parameter.public static int getModuleHandle(String name)
name - Name for the module to find.
public static int getModuleHandle(byte[] hash)
This method retrieves the handle for the module matching the hash
that can be originally retrieved by
getModuleHash(handle).
hash - SHA hash of the module.
public static boolean deleteModule(int moduleHandle,
boolean force)
CodeModuleManager.deleteModuleEx(int,boolean) instead.
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.
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.
IllegalArgumentException - If you provide an invalid module handle.
public static int deleteModuleEx(int moduleHandle,
boolean force)
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.
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.
CodeModuleManager.CMM_OK; if the module gets marked for deletion
after a reset, you should expect #CMM_MODULE_MARKED_FOR_DELETION).
IllegalArgumentException - If you provide an invalid module
handle.
public static int deleteModuleEx(int moduleHandle,
boolean force,
boolean markOnly)
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.
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.
CodeModuleManager.CMM_OK; if the module gets marked for deletion
after a reset, you should expect #CMM_MODULE_MARKED_FOR_DELETION).
IllegalArgumentException - If you provide an invalid module
handle.
public static int[] deleteModules(int[] moduleHandles,
boolean force)
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.
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.
CodeModuleManager.deleteModuleEx(int,boolean)
public static int[] deleteModules(int[] moduleHandles,
boolean force,
boolean markOnly)
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).
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.
CodeModuleManager.CMM_OK; if a module gets
marked for deletion after a reset, you should expect
#CMM_MODULE_MARKED_FOR_DELETION).CodeModuleManager.deleteModuleEx(int,boolean,boolean)public static int getModuleFlags(int moduleHandle)
Example
int value = getModuleFlags( myHandle ); boolean wasInstalledOTA = ( value & CMM_MODULE_FLAG_OTA ) == CMM_MODULE_FLAG_OTA;
moduleHandle - Handle for the module.
IllegalArgumentException - If you provide an invalid module handle.public static String getModuleName(int moduleHandle)
moduleHandle - Handle for the module.
IllegalArgumentException - If you provide an invalid module handle.public static String getModuleVersion(int moduleHandle)
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".
moduleHandle - Handle for the module.
IllegalArgumentException - If you provide an invalid module handle.public static byte[] getModuleHash(int moduleHandle)
moduleHandle - Handle for the module.
IllegalArgumentException - If you provide an invalid module handle.
public static boolean getModuleHash(int moduleHandle,
byte[] moduleHash)
Note: If you provide an invalid module handle, this method does not throw an exception: rather, it returns false.
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.
IllegalArgumentException - If your provided buffer is too small.
NullPointerException - If you provide a null buffer.
public static int getModuleSignerId(int moduleHandle,
int index)
You can use CodeSigningKey.convert(int) to convert the
signer ID into a string form.
moduleHandle - Handle for the module.index - Position (first is '0') of the signature in the list
of signatures.
IllegalArgumentException - If you provide an invalid module
handle.
public static byte[] getModuleSignature(int moduleHandle,
int signerId)
moduleHandle - Handle for the module.signerId - Signer ID (as retrieved by CodeModuleManager.getModuleSignerId(int,int)).
IllegalArgumentException - If you provide an invalid module
handle.public static String getModuleVendor(int moduleHandle)
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 "
moduleHandle - Handle for the module.
IllegalArgumentException - If you provide an invalid module
handle.
public static String getModuleDescription(int moduleHandle)
moduleHandle - Handle for the module.
IllegalArgumentException - If you provide an invalid module
handle.public static String getModuleURL(int moduleHandle)
moduleHandle - Handle for the module.
IllegalArgumentException - If you provide an invalid module
handle.public static long getModuleTimestamp(int moduleHandle)
moduleHandle - Handle for the module.
IllegalArgumentException - If you provide an invalid module handle.public static boolean isLibrary(int moduleHandle)
moduleHandle - Handle for the module.
IllegalArgumentException - If you provide an invalid module
handle.public static boolean isMidlet(int moduleHandle)
moduleHandle - Handle for the module.
IllegalArgumentException - If you provide an invalid module handle.public static int getNumMidlets()
public static boolean isMidlet()
public static int getModuleCodeSize(int moduleHandle)
moduleHandle - Handle for the module.
IllegalArgumentException - If you provide an invalid module
handle.
public static String getModuleName(int moduleHandle,
int index)
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.
moduleHandle - Handle for the module.index - Position (first is '0') of the name in the module's
list of referred-to modules.
IllegalArgumentException - If you provide an invalid module
handle.
public static String getModuleAliasName(int moduleHandle,
int index)
moduleHandle - Handle for the module.index - Position (first is '0') of the name in the module's list of
alias names.
IllegalArgumentException - If you provide an invalid module
handle.
public static String getModuleVersion(int moduleHandle,
int index)
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".
moduleHandle - Handle for the module.index - Position (first is '0') of the version string in the
module's list of version strings.
IllegalArgumentException - If you provide an invalid module handle.public static int createNewModule(int totalLength)
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.
totalLength - Total number of bytes the device should set aside for
module; this value must be the total length of the module data.
public static int createNewModule(int totalLength,
byte[] data,
int length)
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.
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].
public static boolean writeNewModule(int newModuleHandle,
byte[] data,
int newModuleOffset,
int length)
CodeModuleManager.writeNewModule(int,int,byte[],int,int).
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.
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.
public static boolean writeNewModule(int newModuleHandle,
int newModuleOffset,
byte[] data,
int offset,
int length)
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).
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.
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.public static int saveNewModule(int newModuleHandle)
This is a convenience method that wraps
saveNewModule(moduleHandle,false,0).
newModuleHandle - Handle returned by CodeModuleManager.createNewModule(int).
public static int saveNewModule(int newModuleHandle,
boolean forceOverwrite)
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.
newModuleHandle - Handle returned by CodeModuleManager.createNewModule(int).forceOverwrite - Force this method to overwrite an older version of
your new module.
public static int deleteNewModule(int newModuleHandle)
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.
newModuleHandle - Handle for the module.
CodeModuleManager.CMM_OK if the module gets successfully deleted, or
CodeModuleManager.CMM_HANDLE_INVALID if you provide an invalid module handle,public static boolean isResetRequired()
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.
public static void promptForResetIfRequired()
Note: the process attempting the addition/deletion of the module(s) must also be the process calling this method.
public static ApplicationDescriptor[] getApplicationDescriptors(int moduleHandle)
moduleHandle - Handle for the module.
IllegalArgumentException - If you provide an invalid module handle.
public static boolean verifySignature(int moduleHandle,
int signerId,
byte[] publicKey)
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.
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.
IllegalArgumentException - If you provide an invalid module
handle.ControlledAccess.verifyCodeModuleSignature(int,CodeSigningKey)public static long getModuleDownloadTimestamp(int moduleHandle)
moduleHandle - Handle for the module.
IllegalArgumentException - If you provide an invalid module handle.
public static void addListener(Application application,
CodeModuleListener listener)
application - Application providing the event thread that will
process the events; must not be null.listener - Listener to notify; must not be null.
NullPointerException - If you provide a null listener or null
application parameter.
public static void removeListener(Application application,
CodeModuleListener listener)
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.
NullPointerException - If you provide a null application.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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