com.nokia.notifications
Interface NotificationSession

public interface NotificationSession

NotificationMessage is the interface for communicating with the Notification Enabler.

The session is created when the MIDlet calls NotificationSessionFactory.openSession(javax.microedition.midlet.MIDlet, String, String, NotificationSessionListener) and destroyed when the MIDlet exits.

See Also:

NotificationSessionFactory, NotificationSessionListener

Method Summary

void	close() Frees resources allocated for this session.
int	getEnvironment() Check which domain Notification Enabler is connected.
void	getNotificationInformation() Asynchronous function to retrieve Notification ID used by Notification Enabler.
int	getReceiveAtLatest() Returns the MIDlet's receive at latest -value.
boolean	isAudioAlertEnabled() Returns audio alert setting of the MIDlet.
boolean	isWakeUp() Deprecated. This API is not supported in Nokia Asha OS 1.0. NNA registered MIDlet will always have wake-up as true.
void	registerApplication() Calls registerApplication(boolean) with parameter requireUserAuthentication set to false.
void	registerApplication(boolean requireUserAuthentication) Asynchronous call to register the MIDlet to receive notifications.
void	setAudioAlertEnabled(boolean enabled) Turns audio alert on or off for the MIDlet.
void	setReceiveAtLatest(int receiveAtLatest) Sets the MIDlet's receive at latest -value.
void	setWakeUp(boolean wakeUp) Deprecated. This API is not supported in Nokia Asha OS 1.0. NNA registered MIDlet cannot set or unset the wake-up setting. If the MIDlet wants to disable NNA, it should use #unregisterApplication(). Calling this API does not do anything with NNA.
void	unregisterApplication() Asynchronous call to unregister the MIDlet.

Method Detail

registerApplication

void registerApplication(boolean requireUserAuthentication)
                         throws NotificationException

Asynchronous call to register the MIDlet to receive notifications.

It is mandatory to call this method before notifications can be received for the MIDlet.

If the network connection is not already open, Notification Enabler will open the connection.

NotificationSessionListener.stateChanged(NotificationState) is called with

• NotificationState.STATE_CONNECTING state information while registering this MIDlet
• NotificationState.STATE_ONLINE state information and NotificationError.ERROR_NONE error code after successful registration or if the MIDlet has already been registered with the same Application ID
• Error code NotificationError.ERROR_NO_NETWORK if the network connection is lost because of bad network area.
• Error code NotificationError.ERROR_APPLICATION_ID_CONFLICT if the Application ID is already used by another MIDlet.
• Error code NotificationError.ERROR_APPLICATION_ID_INVALID if the Application ID is not valid (either empty or more than 255 characters long).
• Error code NotificationError.ERROR_DISABLED_BY_USER if the user has turned Off the MIDlet switch from Notifications settings.
• Error code NotificationError.ERROR_CONNECTION_DISABLED_BY_USER if the user doesn't have active data connection turned On eg: phone is in flight mode or user has turned Off all data connection swtiches.
• Error code NotificationError.ERROR_SERVICE_UNAVAILABLE if the Notifcation Server is down for a service break.
• Error code NotificationError.ERROR_NOT_KNOWN if any other internal error occured.

Parameters:

requireUserAuthentication - This argument is not supported in Nokia Asha OS 1.0.

Throws:

NotificationException - With reason value NotificationError.ERROR_SESSION_CLOSED if session is not open.

See Also:

NotificationSessionListener.stateChanged(NotificationState), unregisterApplication()

registerApplication

void registerApplication()
                         throws NotificationException

Calls registerApplication(boolean) with parameter requireUserAuthentication set to false.

Throws:

NotificationException - With reason value NotificationError.ERROR_SESSION_CLOSED if session is not open.

unregisterApplication

void unregisterApplication()
                           throws NotificationException

Asynchronous call to unregister the MIDlet.

This API unregisters MIDlet from the Notification Server and removes MIDlet's Notification Enabler settings from the device.

NotificationSessionListener.stateChanged(NotificationState) callback function is called with one of the following error codes after the unregister operation is finished

• if the MIDlet is unregistered successfully NotificationError.ERROR_NONE error code is given
• if the MIDlet hasn't registered yet then NotificationError.ERROR_NOT_REGISTERED error code is given
• if user tries to call unregister without registering or call unregister twice.

Notice, the Notification Enabler handles the unregistering automatically behind the scenes when the MIDlet is uninstalled.

Throws:

NotificationException - With reason value NotificationError.ERROR_SESSION_CLOSED if session is not open.

See Also:

NotificationSessionListener.stateChanged(NotificationState), registerApplication()

getNotificationInformation

void getNotificationInformation()
                                throws NotificationException

Asynchronous function to retrieve Notification ID used by Notification Enabler.

Requested information is returned through the callback function NotificationSessionListener.infoReceived(NotificationInfo). The information contains device indentifier used by MIDlet. This value can be empty if the service is not available or the request has timed out.

Throws:

NotificationException - With reason value NotificationError.ERROR_NOT_ALLOWED if session state is not NotificationState.STATE_ONLINE. With reason value NotificationError.ERROR_SESSION_CLOSED if session is not open.

isWakeUp

boolean isWakeUp()
                 throws NotificationException

Deprecated. This API is not supported in Nokia Asha OS 1.0. NNA registered MIDlet will always have wake-up as true.

This API returns the wake-up setting for the MIDlet.

Returns:

It always true.

Throws:

NotificationException - No exception is thrown.

setWakeUp

void setWakeUp(boolean wakeUp)
               throws NotificationException

Deprecated. This API is not supported in Nokia Asha OS 1.0. NNA registered MIDlet cannot set or unset the wake-up setting. If the MIDlet wants to disable NNA, it should use #unregisterApplication(). Calling this API does not do anything with NNA.

This API can set or unset wake-up settings for the MIDlet.

Throws:

NotificationException - No exception is thrown.

close

void close()

Frees resources allocated for this session. The session should always be closed before the MIDlet exits.

After the session is closed, the notification session listener does not get any calls to its callback functions.

The network connection is closed if there is not at least one session open between a registered MIDlet and the Notification Enabler and no MIDlets are registered for the MIDlet wake-up.

See Also:

NotificationSessionFactory.openSession(MIDlet, String, String, NotificationSessionListener)

setReceiveAtLatest

void setReceiveAtLatest(int receiveAtLatest)
                        throws NotificationException

Sets the MIDlet's receive at latest -value.

Parameters:

receiveAtLatest - the receive at latest -value in seconds.

Throws:

java.lang.IllegalArgumentException - if the value is less than 0.

NotificationException - With reason value NotificationError.ERROR_SESSION_CLOSED if session is not open. NotificationError.ERROR_NOT_REGISTERED if it called before register API.

See Also:

getReceiveAtLatest()

getReceiveAtLatest

int getReceiveAtLatest()
                       throws NotificationException

Returns the MIDlet's receive at latest -value. If it has not been set, then the default value (0 second) will be returned.

The Notification Enabler stores this value for each registered MIDlet. The smallest of the values is used to define how fast the Notification Enabler should reconnect in case the connection has been lost. The delay is also applied when the Notification Enabler starts.

Returns:

the receive at latest value in seconds.

Throws:

NotificationException - With reason value NotificationError.ERROR_SESSION_CLOSED if session is not open. NotificationError.ERROR_NOT_REGISTERED if it called before register API.

setAudioAlertEnabled

void setAudioAlertEnabled(boolean enabled)
                          throws NotificationException

Turns audio alert on or off for the MIDlet. The audio alert will be played when a notification is received while MIDlet is not running. The default value for audio alert is off. In addition, the audio alert has to be set when sending the notification, using the Service API.

Parameters:

enabled - If true then an audio alert will be played in the event of notifications.

Throws:

NotificationException - With reason value NotificationError.ERROR_SESSION_CLOSED if session is not open. NotificationError.ERROR_NOT_REGISTERED if it called before register API.

isAudioAlertEnabled

boolean isAudioAlertEnabled()
                            throws NotificationException

Returns audio alert setting of the MIDlet. The audio alert will be played when a notification is received while MIDlet is not running.

Returns:

true if alert enabled, else alert disabled. Error codes. ERROR_SESSION_CLOSED, ERROR_NOT_REGISTERED

Throws:

NotificationException - With reason value NotificationError.ERROR_SESSION_CLOSED if session is not open. NotificationError.ERROR_NOT_REGISTERED if it called before register API.

getEnvironment

int getEnvironment()
                   throws NotificationException

Check which domain Notification Enabler is connected.

Returns:

The environment is one of the values constants defined in NotificationEnvironment.

Throws:

NotificationException - With reason value NotificationError.ERROR_SESSION_CLOSED if session is not open. NotificationError.ERROR_NOT_REGISTERED if it called before register API.