Add notification support to MIDlet

Lifecycle of a MIDlet that can receive notifications

The Nokia Notifications Client API allows MIDlets on the device to register and receive notifications from the Nokia Notification Server.

As shown in the following diagram, every MIDlet that can receive notifications goes through three states in its lifecycle:

Offline
Connecting
Online

In practice, when a MIDlet is open, it is expected to be in the online state, which means that it has successfully registered to the Notification Enabler, and the Notification Enabler has established an active connection. When in this state, the MIDlet can receive notifications and call any Nokia Notifications Client API method.

Using the Notification ID

The Nokia Notifications Service API (REST API) supports the following methods for specifying the recipient of the notifications:

Sending a notification to a single user, using the unique Notification ID provided by the MIDlet.
Sending notifications in bulk, using the unique Notification ID provided by the MIDlet.

The Notification ID is unique per MIDlet and user. It provides additional privacy to the MIDlet users by allowing the notifications service to deliver notifications to the MIDlet users with just the Notification ID.

The following diagram shows the implementation in the MIDlet.

The Notification ID is requested by the MIDlet, from the Nokia Notification Server, at run time, as shown in step 1. The MIDlet then sends the Notification ID to the notifications service (step 2), so it can be used as a private delivery method for notifications (steps 3 and 4).

Implementing Notifications in MIDlet

Use the Nokia Notifications Client API in the MIDlet to:

Register the MIDlet to the Notification Enabler.
Retrieve the Notification ID.
Receive the notifications.

Note: The Notification Enabler is responsible for establishing an active connection to the Nokia Notification Server. A single Notification Enabler can handle multiple MIDlets.

Registering, unregistering, and uninstalling MIDlets

The differences between registering, unregistering and uninstalling MIDlets are as follows:

Registering MIDlets: Registering a MIDlet means that the MIDlet appears as Available for the Nokia Notification Server. After registering, the MIDlet is visible in Settings > Notifications > Push notifications. If the switch next to the notification name is disabled, then the MIDlet remains registered, but appears for the Nokia Notification Server as Not Available.

Notifications that are sent with the expires-at parameter that has a value higher than 0 are stored on the Nokia Notification Server for the period defined by the expires-at parameter, and delivered to the MIDlet when the MIDlet is enabled again. However, only the last five messages are stored, and notifications that do not have the expires-at parameter set are not stored.

Notifications are buffered on the Notification Service only when the device has MIDlets that wish to receive notifications (i.e. MIDlets are registered and the switch in Settings > Notifications > Push notifications is enabled), but cannot connect to the server as it is offline, powered OFF, or there is a connectivity problem.

Unregistering MIDlets: Unregistering a MIDlet means that the MIDlet is removed from the list in Settings > Notifications > Push notifications and it cannot receive notifications anymore. The registration is valid until unregister is called.

Uninstalling MIDlets: Uninstalling a MIDlet means that the registration is removed automatically by the Notification Enabler.

Notification errors

The following table lists the errors related to the notification state and other exceptions:

Notification Error	Description
ERROR_APPLICATION_ID_CONFLICT	The Application ID has already been registered by another MIDlet.
ERROR_APPLICATION_ID_INVALID	The Application ID is either empty or more than 255 characters long.
ERROR_AUTHENTICATION_FAILED	The device is not able to fetch the authentication details from the Notification server.
ERROR_CONNECTION_DISABLED_BY_USER	The user has disabled connections like WiFi and cellular network.
ERROR_DISABLED_BY_USER	The user has disabled notifications.
ERROR_NO_NETWORK	The Notification Enabler has lost connection with the Notification server.
ERROR_NONE	No error has occurred.
ERROR_NOT_ALLOWED	The `NotificationSession` is not in the correct state.
ERROR_NOT_KNOWN	Notification error other than the one listed here has occurred.
ERROR_NOT_REGISTERED	The MIDlet is not registered but is calling for a function that requires registration.
ERROR_REGISTER_FAILED	The registration failed because there is not enough space available in the device memory to store the settings.
ERROR_SERVICE_UNAVAILABLE	Notification Server is not available.
ERROR_SESSION_CLOSED	`NotificationSession` function call failed because session was closed.