Notifications (notification.h)

Functions to control the notification system on the device.

An application can send requests for the following primary types of notification:

a notify (using the notification_notify() function)
an alert (using the notification_alert() function)

Both notify and alert may contain several data members that affect the characteristics of the notification, defined in the notification_message_t structure. At a minimum, the notification_message_t structure must include item_id, which identifies the notification message. The additional arguments used are:

title
subtitle
request_id
prompt_choices (alert only)
sound_url (notify only)
invocation_target (notify only)
invocation_payload (notify only)
invocation_payload_uri (notify only)
invocation_type (notify only)
invocation_action (notify only)

These arguments, including item_id, are defined in greater detail in their respective notification_message_set_*() functions. If a member isn't given a value, a default value is assigned. As indicated in the above list, some members are specific to either notify or alert notifications. Furthermore, some functions, such as notification_cancel(), require only certain members from the notification_message_t structure. In these instances, you can still provide any additional members, but these are simply ignored if not used by a function. See individual notification_message_set_*() functions for details regarding the corresponding member's valid implementations.

Both notify and alert can have lingering effects, such as the display of a badge on an application icon or the activation of an LED. These may be dealt with by the notification_cancel() or the notification_delete() functions. We recommend that you call the notification_cancel() function when your application launches, to remove any continuing notification signals.

There are settings that define the behavior of notification messages. Examples of basic settings that apply to notification messages include:

Sound alert: Whether to play a sound for this application
SoundUrl: Defines a default sound
LED: Whether an LED light is activated by the notification caller
Badge: Whether the notification should display badges on icons by default. This is most commonly represented as a red symbol on the corner of the application icon.
UIB: Whether items should be added to the Notifications account in the BlackBerry Hub. Invocation parameters define what happens when a user clicks the item in the Hub.
Display: Whether a dialog notification will occur. This doesn't affect alert messages.

For notify messages, settings define the means by which the message is displayed and the volume of information displayed in the message. These settings determine whether a message displays large amounts of information, displays smaller amounts, or does't display any information at all. We recommend that you fill out as much information as possible.

Third party applications can't control the notification settings they receive. The default notification settings allow applications to put notifications into the Notifications account of the Hub. A notification will be placed into the Hub if and only if the notification includes a title and/or a subtitle. Your application can create a badge-only notification by sending a notify message that doesn't contain a title or a subtitle.

Alert messages are also affected by settings, but give more control to the application that sends them. Display methods may be determined by the information provided in the message. For example, by providing a title and adding prompt choices (through the notification_message_add_prompt_choice() function), you can guarantee that a dialog will be displayed, which can communicate a user's response back to the application.

Settings are defined per application. There's one set of default settings for all notifications from an application.

Since:: BlackBerry 10.0.0