SHOW Signed

net.rim.device.api.system
Class ApplicationManager

java.lang.Object
  |
  +--net.rim.device.api.system.ApplicationManager

public abstract class ApplicationManager

extends Object

Manages all Java applications on the device.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Method Summary

	static ApplicationManager	getApplicationManager() Retrieves the system's application manager.
	abstract int	getForegroundProcessId() Retrieves the process ID of the foreground process.
	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	isSystemLocked() Determines if the system is currently locked.
	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.
	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 boolean	setInHolsterInputProcess() Sets the invoking process to receive input events when the device is in the holster.
	abstract void	unlockSystem() Unlocks the system.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setInHolsterInputProcess

public abstract boolean setInHolsterInputProcess()

Sets the invoking process to receive input events when the device is in the holster.

Returns:

True if the invocation was successful; false if there is already another in-holster process set.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

lockSystem

public abstract void lockSystem(boolean force)

Locks the system.

Parameters:

force - If true, force the system to be locked even if security is disabled. This is used when the IT Policy changes.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

isSystemLocked

public abstract boolean isSystemLocked()

Determines if the system is currently locked.

Returns:

True if the system is currently locked.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

unlockSystem

public abstract void unlockSystem()

Unlocks the system.

Calling this method blocks until the system actually unlocks.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

runApplication

public final int runApplication(ApplicationDescriptor descriptor)
                         throws ApplicationManagerException

Creates a new process to run an application and ask it to foreground itself.

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.

Parameters:

descriptor - Descriptor of application to start.

Returns:

Process ID for the application's new process; if the application already has a running process, this will be the ID for that process.

Throws:

ApplicationManagerException - Thrown if the application could not be run.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

runApplication

public abstract int runApplication(ApplicationDescriptor descriptor,
                                   boolean grabForeground)
                            throws ApplicationManagerException

Creates a new process to run an application.

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.

Parameters:

descriptor - Descriptor of application to start.

grabForeground - If true, this method prompts the application to foreground itself.

Returns:

Process ID for the application's new process; if the application already has a running process, this will be the ID for that process.

Throws:

ApplicationManagerException - Thrown if the application could not be run.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

scheduleApplication

public abstract boolean scheduleApplication(ApplicationDescriptor descriptor,
                                            long time,
                                            boolean absolute)

Schedules an application to run at a specific time.

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.

Parameters:

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.

Returns:

True if the application was scheduled successfully; otherwise, false.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

requestForeground

public abstract void requestForeground(int processId)

Sends a foreground request to application with specified process ID.

Parameters:

processId - Process ID for the application to receive a foreground request.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getProcessId

public abstract int getProcessId(ApplicationDescriptor descriptor)

Retrieves the process ID for specified descriptor's application.

Parameters:

descriptor - Descriptor for the application in question.

Returns:

ID for process hosting descriptor's application; -1 if application has no process (i.e. is not running).

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getForegroundProcessId

public abstract int getForegroundProcessId()

Retrieves the process ID of the foreground process.

Parameters:

processId - Process ID of the application which is currently in the foreground; -1 if there is no foreground application.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getVisibleApplications

public abstract ApplicationDescriptor[] getVisibleApplications()

Retrieves descriptors for the visible, running applications.

Returns:

Array of descriptors for the visible (foregroundable), running applications.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

postGlobalEvent

public final boolean postGlobalEvent(long guid)

Posts a global event to all applications in the system.

To receive and handle such events, an application must register a GlobalEventListener.

Parameters:

guid - The GUID of the event.

Returns:

True if the event was successfully posted; otherwise, false.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

postGlobalEvent

public final boolean postGlobalEvent(long guid,
                                     int data0,
                                     int data1)

Posts a global event with additional data to all applications in the system.

To receive and handle such events, an application must register a GlobalEventListener.

Parameters:

guid - The GUID of the event.

data0 - Additional information associated with the event.

data1 - Additional information associated with the event.

Returns:

True if the event was successfully posted; otherwise, false.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

postGlobalEvent

public 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.

To receive and handle such events, an application must register a GlobalEventListener.

Parameters:

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.

Returns:

True if the event was successfully posted; otherwise, false.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

postGlobalEvent

public 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.

To receive and handle such events, the application must register a GlobalEventListener.

Parameters:

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.

Returns:

True if the event was successfully posted; otherwise, false.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getApplicationManager

public static final ApplicationManager getApplicationManager()

Retrieves the system's application manager.

Returns:

Reference to the system's application manager.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.