SHOW Signed

net.rim.device.api.notification
Class NotificationsManager

java.lang.Object
  |
  +--net.rim.device.api.notification.NotificationsManager

All Implemented Interfaces:

NotificationsConstants

public final class NotificationsManager

extends Object

implements NotificationsConstants

Manages the handling of events between applications and the notification engine. Keeps track of registered engine listeners as well as known consequence implementors.

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.

Since:

JDE 3.6.0

Fields inherited from interface net.rim.device.api.notification.NotificationsConstants

CALLERID_ADDRESSCARD_UID, CASUAL, CRITICAL, CUSTOM_TUNE_NAME, DEFAULT_LEVEL, FORCE_NO_REPEAT_NOTIFICATIONS_FLAG, FORCED, IMPORTANT, IN_HOLSTER_ENGINE_STATE, MANUAL_TRIGGER, NOTIFICATION_LEVEL_KEY, NOTIFICATION_PRIVATE_FLAG_KEY, NOTIFICATION_REPEAT_COUNT, NOTIFICATION_REPEAT_DELAY, OUT_OF_HOLSTER_ENGINE_STATE, OUT_OF_HOLSTER_TRIGGER, SENSITIVE, STOP_CONDITIONS

Method Summary

	static void	cancelAllDeferredEvents(long sourceID, int triggerIndex, Object context) Cancels all events matching the source, level and trigger.
	static void	cancelDeferredEvent(long sourceID, long eventID, Object eventReference, int triggerIndex, Object context) Cancels the event.
	static void	cancelImmediateEvent(long sourceID, long eventID, Object eventReference, Object context) Cancels any current immediate events.
	static void	deregisterConsequence(long consequenceID) Removes the consequence from the list of known consequences.
	static void	deregisterNotificationsEngineListener(long sourceID, NotificationsEngineListener listener) Removes the listener from the list of known listeneres.
	static void	deregisterSource(long sourceID) Removes the application from the list of known event sources.
	static int	getDeferredEventCount(long sourceID) Returns the count of all events matching the source currently in the queue.
	static long[]	getDeferredEventIds(long sourceID) Returns the count of all events matching the source currently in the queue.
	static Object[]	getDeferredEvents(long sourceID) Returns the count of all events matching the source currently in the queue.
	static long	getLastEventDate() Method returns time stamp when the latest even either immediate or deferred happened
	static boolean	isImmediateEventOccuring(long sourceIdLong) Tests whether a particular event is playing or led blinking for an profile
	static void	negotiateDeferredEvent(long sourceID, long eventID, Object eventReference, long eventDate, int triggerIndex, Object context) Adds the specified event to the event queue.
	static void	registerConsequence(long consequenceID, Consequence consequence) Adds a new consequence to the list of known event consequences.
	static void	registerNotificationsEngineListener(long sourceID, NotificationsEngineListener listener) Adds a listener to the list of known engine listeners.
	static void	registerSource(long sourceID, Object source, int level) Adds the application to the list of known event sources.
	static void	triggerImmediateEvent(long sourceID, long eventID, Object eventReference, Object context) Triggers an immediate event.

Methods inherited from class java.lang.Object

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

Method Detail

triggerImmediateEvent

public static void triggerImmediateEvent(long sourceID,
                                         long eventID,
                                         Object eventReference,
                                         Object context)

Triggers an immediate event. This is intended to support consequences such as tone, vibration or the LED. In other words, things that do not require user interaction.

Parameters:

sourceID - Identifier of the application triggering the event.

eventID - Application-specific event identifier.

eventReference - Application-specific event cookie.

context - Optional context object.

Since:

JDE 3.6.0

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.

cancelImmediateEvent

public static void cancelImmediateEvent(long sourceID,
                                        long eventID,
                                        Object eventReference,
                                        Object context)

Cancels any current immediate events.

Parameters:

sourceID - Identifier of the application that triggered the event.

eventID - Application-specific event identifier.

eventReference - Application-specific event cookie.

context - Optional context object.

Since:

JDE 3.6.0

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.

negotiateDeferredEvent

public static void negotiateDeferredEvent(long sourceID,
                                          long eventID,
                                          Object eventReference,
                                          long eventDate,
                                          int triggerIndex,
                                          Object context)

Adds the specified event to the event queue. Exactly where in the queue the event is inserted is engine-specific, i.e., neither the event nor the application can decide it.

The triggerIndex parameter specifies further criteria for determining the event. Currently only two values are defined:

• NotificationsConstants.OUT_OF_HOLSTER_TRIGGER
• NotificationsConstants.MANUAl_TRIGGER

If OUT_OF_HOLSTER_TRIGGER is specified, the event will occur when the device is next removed from the holster. Furthermore, the event will expire on it's own if the eventDate time is reached. Finally, the current implementation will drop this event if the device is NOT in the holster when this call is made.

If the value MANUAL_TRIGGER is specified as the triggerIndex, the eventDate expiry parameter is ignored.

An event can be cancelled via the cancelDeferredEvent method. Furthermore, this call must be made to cancel an event that has no timeout.

Parameters:

sourceID - Identifier of the application that is queuing the event.

eventID - Application-specific event identifier.

eventReference - Application-specific event cookie.

eventDate - Event expiry time. A relative ms count from the time the method is called. This parameter is currently ignored UNLESS the triggerIndex is NotificationsConstants.OUT_OF_HOLSTER_TRIGGER

triggerIndex - Identifier of the way in which the event will be triggered.

context - Optional context object.

Since:

JDE 3.6.0

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.

cancelDeferredEvent

public static void cancelDeferredEvent(long sourceID,
                                       long eventID,
                                       Object eventReference,
                                       int triggerIndex,
                                       Object context)

Cancels the event. This could be the current event being negotiated or a future event still in the event queue.

Parameters:

sourceID - Identifier of the application that queued the event.

eventID - Application-specific event identifier.

eventReference - Application-specific event cookie.

triggerIndex - Identifier of the way in which the event was to be triggered.

context - Optional context object.

Since:

JDE 3.6.0

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.

cancelAllDeferredEvents

public static void cancelAllDeferredEvents(long sourceID,
                                           int triggerIndex,
                                           Object context)

Cancels all events matching the source, level and trigger.

Parameters:

sourceID - Identifier of the application that queued the events.

triggerIndex - Identifier of the way in which the events were to be triggered.

context - Optional context object.

Since:

JDE 3.6.0

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.

getDeferredEventCount

public static int getDeferredEventCount(long sourceID)

Returns the count of all events matching the source currently in the queue.

Parameters:

sourceID - GUID of the source object.

Since:

JDE 4.0.2

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.

getDeferredEvents

public static Object[] getDeferredEvents(long sourceID)

Returns the count of all events matching the source currently in the queue.

Parameters:

sourceID - GUID of the source object.

Since:

JDE 4.1.0

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.

getDeferredEventIds

public static long[] getDeferredEventIds(long sourceID)

Returns the count of all events matching the source currently in the queue.

Parameters:

sourceID - GUID of the source object.

Since:

JDE 4.1.0

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.

registerSource

public static void registerSource(long sourceID,
                                  Object source,
                                  int level)

Adds the application to the list of known event sources.

Parameters:

sourceID - Identifier of the application to register.

source - Source application object.

level - Level at which the application is to be registered.

Since:

JDE 3.6.0

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.

deregisterSource

public static void deregisterSource(long sourceID)

Removes the application from the list of known event sources.

Parameters:

sourceID - Identifier of the application to deregister.

Since:

JDE 3.6.0

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.

registerNotificationsEngineListener

public static void registerNotificationsEngineListener(long sourceID,
                                                       NotificationsEngineListener listener)

Adds a listener to the list of known engine listeners.

Parameters:

sourceID - GUID of the listener object to register.

listener - Listener object.

Since:

JDE 3.6.0

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.

deregisterNotificationsEngineListener

public static void deregisterNotificationsEngineListener(long sourceID,
                                                         NotificationsEngineListener listener)

Removes the listener from the list of known listeneres.

Parameters:

sourceID - GUID of the listener object to deregister.

listener - Listener object.

Since:

JDE 3.6.0

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.

registerConsequence

public static void registerConsequence(long consequenceID,
                                       Consequence consequence)

Adds a new consequence to the list of known event consequences.

Parameters:

consequenceID - GUID of the consequence object to register.

consequence - Consequence object itself.

Since:

JDE 3.6.0

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.

deregisterConsequence

public static void deregisterConsequence(long consequenceID)

Removes the consequence from the list of known consequences.

Parameters:

consequenceID - GUID of the consequence object to deregister.

Since:

JDE 3.6.0

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.

getLastEventDate

public static long getLastEventDate()

Method returns time stamp when the latest even either immediate or deferred happened

Returns:

Time stamp when the latest even either immediate or deferred happened.

Since:

JDE 4.0.0

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.

isImmediateEventOccuring

public static boolean isImmediateEventOccuring(long sourceIdLong)

Tests whether a particular event is playing or led blinking for an profile

Returns:

True if it an immediate event is occuring

Since:

JDE 4.1.0

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.