Notification API Guide - C (Thin Core)

Obtain the Notification service framework

The source code for this service framework can be found on the AllSeen Alliance gerrit page as a git project. In addition, the ajtcl project is needed to compile this 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.

Reference code

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

Producer module	Description
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.
NotificationProducerSample	Sample code for creating and sending a notification that exercises the NotificationProducer API. There are two (2) samples: Simple - sends the same notification AC - complements the Air Conditioner ControlPanel sample and sends notifications generated by the changes in the ControlPanel model.

Build a Notification producer

The following steps provide the high-level process to build a Notification producer.

1. Create the base for the AllJoyn application. See the Build an Application using the Thin Library section for instructions.
2. Create a notification content structure and populate the necessary fields.
3. 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[2] customAttributesToSend[2]
   richAudioUrls[2]

Set text per language to be sent

notificationContent.numTexts = 2;
textToSend[0].key = "en";
textToSend[0].value = "Hello AJL World";
textToSend[1].key = "es_SP";
textToSend[1].value = "Hola AJL Munda";
notificationContent.texts = textToSend;

NOTES

• 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.

Custom attributes

notificationContent.numCustomAttributes = 2;
customAttributesToSend[0].key = "key 0";
customAttributesToSend[0].value = "val 0";
customAttributesToSend[1].key = "key 1";
customAttributesToSend[1].value = "val 1";
notificationContent.customAttributes = customAttributesToSend;

Audio URLs

notificationContent.numAudioUrls = 2;
richAudioUrls[0].key = "en";
richAudioUrls[0].value = "http://www.getAudio1.org";
richAudioUrls[1].key = "es_SP";
richAudioUrls[1].value = "http://www.getAudio2.org";
notificationContent.richAudioUrls = richAudioUrls;

Icon URLs

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, &notificationContent,
   messageType, ttl, &serialNum)

NOTES

• 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.

AJNS_Producer_DeleteLastNotification(&busAttachment, messageType);

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 SendNotification call.Use the CancelNotification API to do so. The message's serial number must be included.

AJNS_Producer_CancelNotification(&busAttachment, serialNum)

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 softwarem, see the [Build an Application using the Thin Library][build-app-using-thin-library] section.