net.rim.device.api.system.ApplicationManager
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public abstract class ApplicationManager
Manages all Java applications on the device.
The net.rim.device.api.system.ApplicationManager class enables applications
to interact with the application manager to perform the following tasks:
. interact with processes, such as retrieving the IDs for foreground applications
. post global events to the system
. lock or unlock the handheld, or determine whether the handheld is locked
. run an application immediately or at a specific time
To use any of the ApplicationManager methods, you must first retrieve a reference to the current application manager using the getApplicationManager() method:
ApplicationManager manager = ApplicationManager.getApplicationManager();Retrieve information about applications
You can retrieve information about running processes by invoking getVisibleApplications() on the ApplicationManager. The getVisibleApplications() method retrieves an array of ApplicationDescriptor objects for visible applications that are running. An ApplicationDescriptor contains descriptive information for the application, such as its name, icon, position on the Home screen, resource bundle, and so on. Use ApplicationDescriptor methods to retrieve this information.
ApplicationManager manager = ApplicationManager.getApplicationManager(); ApplicationDescriptor descriptors[] = manager.getVisibleApplications(); String appname1 = descriptors[0].getName();Run an application with different arguments
You can use the ApplicationManager and ApplicationDescriptor classes to run
an application with different arguments, for example, based on a system event.
1. Create an ApplicationDescriptor using the existing ApplicationDesriptor as a template.
Specify the arguments to use in the main() method.
ApplicationDescriptor template = ApplicationDescriptor.currentApplicationDescriptor();
String[] args = { "admin", "secure" };
ApplicationDescriptor newdescriptor = new ApplicationDescriptor(template, args);
2. Run the application using the new ApplicationDescriptor.
ApplicationManager appmanager = ApplicationManager.getApplicationManager();
try
{
appmanager.runApplication(newdescriptor);
}
catch(ApplicationManagerException)
{
// Handle situation when application cannot run
}
The runApplication() method creates a new process and invokes the exported main() method in the specified descriptor, using its arguments. The new process moves to the foreground if possible.
Post global eventsYou can use the ApplicationManager.postGlobalEvent method as a basic mechanism
to communicate with other processes. You can also send and receive messages
between processes using the runtime store.
To post a global event to a specific application, use the following method:
abstract boolean postGlobalEvent(int processId, long guid, int data0, int data1, Object object0, Object object1)
The processID parameter specifies the ID of the process to which to post the event. You can retrieve a process ID by invoking the getProcessId(ApplicationDescriptor) method. The guid parameter specifies a global unique identifier (GUID) for the event. The data and object parameters specify additional information for the event.
To post a global event to all applications, use one of the following forms of the postGlobalEvent() method:
Form 1
boolean postGlobalEvent(long guid);Form 2
boolean postGlobalEvent(long guid, int data0, int data1);Form 3
abstract boolean postGlobalEvent(long guid, int data0, int data1, Object object0, Object object1);
The first form of the method posts a global event with a unique identifier. The second form of the method posts a global event with additional data. The third form of the method posts a global event with additional integer and object data. To receive a global event, an application must implement the net.rim.device.api.system.GlobalEventListener interface and implement the GlobalEventListener.eventOccurred method, which is invoked when a global event occurs. In its implementation of eventOccurred(), the application specifies which actions to perform when a global event is received.
Register the GlobalEventListener by invoking the Application.addGlobalEventListener(GlobalEventListener) method.
Lock the handheld
To determine whether the user's handheld is locked, invoke ApplicationManager.isSystemLocked(). This method returns true if the handheld is locked.
You can use the ApplicationManager.lockSystem method to lock the user's handheld.
For example, you might want to lock the handheld if the user types a password for your application incorrectly a certain number of times.
The following sample code demonstrates how to do this:
ApplicationManager manager = ApplicationManager.getApplicationManager(); manager.lockSystem(true);Schedule an application to run later
You can schedule the application to run at a specified time by invoking scheduleApplication() instead of runApplication(), as demonstrated in the following code sample:
try
{
appmanager.scheduleApplication(newdescriptor, 1728000, false);
}
catch(ApplicationManagerException)
{
//handle situation when application cannot run
}
Note: The application does not run if the handheld is reset or turned off before the specified time.
Application,
ApplicationDescriptor| Method Summary | ||
|---|---|---|
|
static ApplicationManager |
getApplicationManager()
Retrieves the system's application manager. |
|
abstract int |
getForegroundProcessId()
Retrieves the process ID of the foreground process. |
|
abstract long |
getNextAlarm()
Get the next alarm based on the current power on behavior |
|
abstract long |
getNextAlarm(int powerOnBehavior)
Get the next alarm based on the power on behavior |
|
abstract int |
getProcessId(ApplicationDescriptor descriptor)
Retrieves the process ID for specified descriptor's application. |
|
abstract ApplicationDescriptor[] |
getVisibleApplications()
Retrieves descriptors for the visible, running applications. |
|
abstract boolean |
inStartup()
Determines if the device is in the process of starting up. |
|
abstract boolean |
isConsoleDescriptor(ApplicationDescriptor descriptor)
Determines if an application descriptor is the descriptor of the console process. |
|
abstract boolean |
isSystemLocked()
Determines if the system is currently locked. |
|
abstract void |
launch(String url)
Launches an application with provided URL parameter, without returning the process ID of the launched process. |
|
abstract int |
launchApplication(String url)
Launches an application with provided URL parameter. |
|
abstract void |
lockSystem(boolean force)
Locks the system. |
|
abstract boolean |
postGlobalEvent(int processId,
long guid,
int data0,
int data1,
Object object0,
Object object1)
Posts a global event with additional data and attachments to the specified process. |
|
boolean |
postGlobalEvent(long guid)
Posts a global event to all applications in the system. |
|
boolean |
postGlobalEvent(long guid,
int data0,
int data1)
Posts a global event with additional data to all applications in the system. |
|
abstract boolean |
postGlobalEvent(long guid,
int data0,
int data1,
Object object0,
Object object1)
Posts a global event with additional data and attachments to all applications in the system. |
|
abstract void |
requestForeground(int processId)
Sends a foreground request to application with specified process ID. |
|
abstract void |
requestForegroundForConsole()
Requests that the console process (usually the home screen) be notified that it should bring itself to the foreground. |
|
int |
runApplication(ApplicationDescriptor descriptor)
Creates a new process to run an application and ask it to foreground itself. |
|
abstract int |
runApplication(ApplicationDescriptor descriptor,
boolean grabForeground)
Creates a new process to run an application. |
|
abstract boolean |
scheduleApplication(ApplicationDescriptor descriptor,
long time,
boolean absolute)
Schedules an application to run at a specific time. |
|
abstract void |
setCurrentPowerOnBehavior(int powerOnBehavior)
Set the Power On Behavior for scheduled applications |
|
abstract boolean |
setInHolsterInputProcess()
Deprecated. |
|
abstract void |
unlockSystem()
Unlocks the system. |
|
abstract void |
waitForStartup()
Wait for the device to finish the startup process. |
| Methods inherited from class java.lang.Object |
|---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Method Detail |
|---|
public abstract boolean setInHolsterInputProcess()
public abstract void launch(String url)
throws ApplicationManagerException
ApplicationManager.launchApplication(String) instead.
This method launches an application with an URL of the following
form:
module.name?param¶m...
or
module?param¶m...
if there is only a single entry point in the module.
url - URL which can be in any form and is passed in the arguments to
main.
ApplicationManagerException - If the application could not be run.
public abstract int launchApplication(String url)
throws ApplicationManagerException
This method launches an application with an URL of the following
form:
module.name?param¶m...
or
module?param¶m...
if there is only a single entry point in the module.
url - URL which can be in any form and is passed in the arguments to
main.
ApplicationManagerException - If the application could not be run.public abstract void lockSystem(boolean force)
force - Deprecated.public abstract boolean isSystemLocked()
public abstract void unlockSystem()
Calling this method blocks until the system actually unlocks.
public final int runApplication(ApplicationDescriptor descriptor)
throws ApplicationManagerException
Invoke this method to create a new process and invoke the exported
main() method in the specified descriptor. This method then asks the
process to foreground itself (which it may or may not do). If a process
has already been created for your descriptor, then this method sends that
process a foreground request.
descriptor - Descriptor of application to start.
ApplicationManagerException - Thrown if the application could not be run.
public abstract int runApplication(ApplicationDescriptor descriptor,
boolean grabForeground)
throws ApplicationManagerException
Invoke this method to create a new process and invoke the exported
main() method in the specified descriptor. If you pass true for the
grabForeground parameter, then this method also asks the process to
foreground itself (which it may or may not do). If a process has already
been created for your descriptor, and you pass true for the
grabForeground parameter, then this method sends that process a
foreground request.
descriptor - Descriptor of application to start.grabForeground - If true, this method prompts the application to
foreground itself.
ApplicationManagerException - Thrown if the application could not be run.
public abstract boolean scheduleApplication(ApplicationDescriptor descriptor,
long time,
boolean absolute)
If the application is already scheduled to run at a particular time, then this method updates the schedule with your specified time. Note that the application scheduler has a resolution of one minute. Times are rounded down to the nearest minute.
If the specified time is absolute and has already occurred, the application will not be scheduled.
If the application's module changes after this method is invoked then the scheduled launch will be cancelled. For example, if an application invokes this method to schedule itself to launch in 10 minutes and a newer version is installed before the 10 minutes then the scheduled launch will be cancelled. This is because when a module is upgraded or downgraded the "old" module is deleted and a the "new" module is added, which means that the "new" module will have a different handle. Since the module's handle is stored in the ApplicationDescriptor there is no way for this method to completely reliably discover the upgraded module and launch it instead. As a workaround, if an application needs to maintain its scheduled launch after an upgrade it should run on startup and invoke this method to register a scheduled launch of the upgraded version.
descriptor - Descriptor of application to start.time - Time at which to run the application; if a negative value,
remove this application from the schedule.absolute - If true, then the time parameter represents the number of
milliseconds since device's origin time (midnight, January 1, 1970 UTC);
otherwise, it represents the number of milliseconds since midnight local time.
public abstract void requestForeground(int processId)
processId - Process ID for the application to receive a foreground request.public abstract void requestForegroundForConsole()
public abstract boolean isConsoleDescriptor(ApplicationDescriptor descriptor)
descriptor - The descriptor to check.
true if the specified descriptor matches the console process' descriptor;
returns false otherwise or if descriptor==null.public abstract int getProcessId(ApplicationDescriptor descriptor)
descriptor - Descriptor for the application in question.
public abstract int getForegroundProcessId()
processId - Process ID of the application which is currently in the foreground;
-1 if there is no foreground application.public abstract ApplicationDescriptor[] getVisibleApplications()
public final boolean postGlobalEvent(long guid)
To receive and handle such events, an application must register a
GlobalEventListener.
guid - The GUID of the event.
public final boolean postGlobalEvent(long guid,
int data0,
int data1)
To receive and handle such events, an application must register a
GlobalEventListener.
guid - The GUID of the event.data0 - Additional information associated with the event.data1 - Additional information associated with the event.
public abstract boolean postGlobalEvent(long guid,
int data0,
int data1,
Object object0,
Object object1)
To receive and handle such events, an application must register a
GlobalEventListener.
guid - The GUID of the event.data0 - Additional information associated with the event.data1 - Additional information associated with the event.object0 - Additional information associated with the event.object1 - Additional information associated with the event.
public abstract boolean postGlobalEvent(int processId,
long guid,
int data0,
int data1,
Object object0,
Object object1)
To receive and handle such events, the application must register a
GlobalEventListener.
processId - Process ID of the application to receive the event.guid - The GUID of the event.data0 - Additional information associated with the event.data1 - Additional information associated with the event.object0 - Additional information associated with the event.object1 - Additional information associated with the event.
public abstract boolean inStartup()
public abstract void waitForStartup()
public abstract void setCurrentPowerOnBehavior(int powerOnBehavior)
powerOnBehavior - the ApplicationDescriptor power On Behaviour to use.public abstract long getNextAlarm()
public abstract long getNextAlarm(int powerOnBehavior)
powerOnBehavior - the ApplicationDescriptor power On Behaviour filter alarms by.
public static final ApplicationManager getApplicationManager()
|
|||||||||
| 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