AllJoyn™ Notification Framework API Guide – C (Thin Core)
Obtain the Notification service framework
If the target platform already supports the AllJoyn™ Thin Library framework, follow the target platform documentation for detailed setup and download instructions.
If the target platform does not support the AllJoyn Thin Library framework porting work is required to support this target. See the Introduction to AllJoyn Thin Library for more information about the AllJoyn Thin Library framework.
The reference code consists of a module that implements a Notification producer layer and a module that implements code to create and send a notification.
Notification producer modules
|NotificationCommon||Common code for the Notification service framework that is shared by the Notification Producer and Notification Consumer.|
|NotificationProducer||A module in the Notification service framework that is used by a developer/OEM to build an application that exposes the ability to send notifications that are received by Notification Consumers.|
|NotificationProducerSampleUtil||Sample code for Linux platform that extends the NotificationProducerSample to allow for console input from the user.|
Sample code for creating and sending a notification that exercises the NotificationProducer API. There are two (2) samples:
Build a Notification producer
The following steps provide the high-level process to build a Notification producer.
- Create the base for the AllJoyn application. See the Build an Application using the Thin Library section for instructions.
- Create a notification content structure and populate the necessary fields.
- Send the notification specifying its content, message type, and time to live (TTL) value.
Implementing a Notification Producer
Create the base for the AllJoyn application
See the Build an Application using the Thin Library section for instructions.
Create a notification content structure and populate the necessary fields
Create a notification content structure and helper structures
static AJNS_NotificationContent notificationContent; struct AJNS_DictionaryEntry textToSend customAttributesToSend richAudioUrls
Set text per language to be sent
notificationContent.numTexts = 2; textToSend.key = "en"; textToSend.value = "Hello AJL World"; textToSend.key = "es_SP"; textToSend.value = "Hola AJL Munda"; notificationContent.texts = textToSend;
- The string assigned to the "value" variable will travel to every instance of a Notification consumer. It is important that this text be correct and complete so the Notification Consumer side will correctly display the information.
- For the sake of completeness and integrity of overall device's user experience, it is recommended to have the textToSend array match the SupportedLanguages list published by the About feature and provisioned for the PropertyStore in the application.
Notification content optional parameters
The following optional parameters can be added to the notification content.
notificationContent.numCustomAttributes = 2; customAttributesToSend.key = "key 0"; customAttributesToSend.value = "val 0"; customAttributesToSend.key = "key 1"; customAttributesToSend.value = "val 1"; notificationContent.customAttributes = customAttributesToSend;
notificationContent.numAudioUrls = 2; richAudioUrls.key = "en"; richAudioUrls.value = "http://www.getAudio1.org"; richAudioUrls.key = "es_SP"; richAudioUrls.value = "http://www.getAudio2.org"; notificationContent.richAudioUrls = richAudioUrls;
notificationContent.richIconUrl = "http://www.getIcon1.org";
Icon object path
notificationContent.richIconObjectPath = "/icon/MyDevice";
Audio object path
notificationContent.richAudioObjectPath = "/audio/MyDevice";
Control panel service response object path
notificationContent.controlPanelServiceObjectPath = "/ControlPanel/MyDevice/mainpanel";
Send the notification
After the notification content is created, you can send a notification with the created content. Any notification you send must include the notification content, message type, and TTL for the message.
You can optionally provide a pointer to the serial number that will be updated with the outgoing AllJoyn signal's message serial number.
The serial number is required to cancel a notification prior to the TTL expiration. See Cancel a specific notification message for more information
uint16_t messageType = AJNS_NOTIFICATION_MESSAGE_TYPE_INFO; uint32_t ttl = 20000; uint32_t serialNum; AJNS_Producer_SendNotification(&busAttachment, ¬ificationContent, messageType, ttl, &serialNum)
- Other fields in the notification will be added by the Notification producer to identify the sender. In particular, the AppID, AppName, DeviceId, and DeviceName will be obtained from the PropertyStore.
- You will need the serial number if you wish to later cancel the notification prior to the TTL expiry using the CancelNotification API.
Delete the last notification message
Once a notification was sent out and the application writer would like to cancel it before the TTL expiration, for example, if the notification was sent for an event that no longer occurs, use the DeleteLastNotification API to delete the last notification for a given message type.
Cancel a specific notification message
An alternative to deleting the last notification message for
a particular message type is to cancel a specific notification
message by its serial number that was returned by the
call.Use the CancelNotification API to do so. The message's
serial number must be included.
Compile the code
The process to compile varies depending on the host and target platform. Each host and platform needs may require a specific directory and file layout, build toolchains, procedures, and supported AllJoyn service frameworks. Refer to the target platform documentation that contains instructions on how to organize and set up the build process to incorporate the necessary files to compile your Thin Library application.
For more details on how to combine this AllJoyn service framework with other AllJoyn service framework software, see the [Build an Application using the Thin Library][build-app-using-thin-library] section.