Notification Interface Definition - 14.02

Warning: This is not the latest interface definition.

Go here for latest Notification Interface Definition

Introduction

Purpose

This document provides the specification for the AllJoyn™ Notification interface. This interface is used by an AllJoyn application to send events or state update notifications to other devices connected to an end user's home network, such as a Wi-Fi network.

Scope

This document is targeted to the developers for AllJoyn applications.

Release history

Release version What changed
Pre-14.02 Notification interface version 1 was added.
14.02 The following interfaces were added:
* Dismisser interface version 1
* Producer interface version 1

References

Except for supporting information, the following are reference documents found on the AllSeen Alliance web site's Docs/Downloads section.

  • AllJoyn™ Framework Tutorial
  • Introduction to AllJoyn™ Thin Library
  • AllJoyn Data Type Signature
  • AllJoyn™ About Feature Interface Specification

Acronyms and terms

Term Definition
AllJoyn device An entity which has an AllJoyn application installed to send or receive notifications using the Notification service framework interface.
Consumer Device that receives the notification and has a way to notify user such as a mobile phone or TV.
Notification message A message sent by a producer specifying details of the notification including any notification text to be displayed to the user.
Notification service framework Software layer that enables devices to send or receive human-consumable notifications.
Producer Device that generates and sends the notification to a device such as a household appliance.
Sessionless signal A broadcast AllJoyn signal which is received by all devices listening on the end user's home network (such as the Wi-Fi network). The Sessionless signal sessionless signals are broadcast on the network until an associated time-to-live (TTL) value expires. The Notification service framework sends notification messages as sessionless signals over the Wi-Fi network.

Overview

This document captures the design for the Notification service framework, which is a software layer that enables AllJoyn™ devices to send notifications to other AllJoyn devices. These devices are categorized as producers and consumers. Producers produce and send notifications, while consumers consume and display these notifications. An end user's home (Wi-Fi) network can have multiple producers connected and generating notification messages, as well as multiple consumers connected and consuming these messages.

The Notification service framework design supports text notification payload as well as rich notification media (icon and audio). For rich media, the notification message payload can include URL links or AllJoyn object path references to rich notification media. The consumer app receiving the notification message will fetch the rich notification media from the object path or the producer device.

The Notification service framework uses the AllJoyn framework sessionless signal to deliver notification messages. The Notification service framework exposes the Notification Service API for application developers to deliver and receive notification messages. The device OEM uses the Notification service framework Producer API to send notification messages. The Notification service framework sends these notification messages over the AllJoyn sessionless signal transport mechanism and makes them available to consumer devices listening for sessionless signals. The consumer running the Notification service framework registers with the AllJoyn framework to receive notification messages. The application developer for the consumer device uses the Notification service framework Consumer API to register and receive notifications from any producer that is sending notification on the Wi-Fi network.

Architecture

The Notification service framework implements the Notification interface which is the over-the-wire interface to deliver messages from producers to consumers. Application developers making use of the Notification service framework implement against the Notification service framework APIs (producer and consumer side). They do not implement the Notification interface.

Figure 1 illustrates the Notification service framework API and Notification interface on producers and consumers.

notification-arch

Figure: Notification service framework architecture within the AllJoyn framework

Typical call flow

Figure 2 illustrates a typical Notification service framework call flow with a single producer app generating a notification message. The message is then acquired by two consumer apps on the AllJoyn network.

notification-typical-call-flow

Figure: Typical Notification service framework call flow

The AllJoyn framework on the producer device does a sessionless signal broadcast for the notification message. This is received by the AllJoyn framework on the consumer devices. The AllJoyn framework then fetches the notification message over unicast session from the producer AllJoyn core and delivers to the consumer application.

Specification

Notification messages

The notification message comprises a set of fields including message type and message TTL. These notification fields are specified by the producer app when sending notification message as part of Notification service framework Producer API.

Message type and TTL fields

The message type defines the type of notification messages (emergency, warning and information). Multiple types of notification messages can be sent at the same time by a producer. The message TTL defines the validity period of the notification message. Notification messages can be received by consumers that connect during the defined message TTL value.

Messages with the same message type will overwrite each other on the producer, so a consumer that connects to the network after the notification was sent will receive only the last of each message type.

Notification message behavior

The following behavior is supported using the Notification service framework.

  • If another notification message of the same message type is sent by a producer app within the TTL period, the new message overwrites the existing message.
  • If a consumer connects to the network after the TTL period expires, that consumer will not receive the message. For example, when a consumer such as a mobile phone is on the home network and the end user leaves the home; the consumer is no longer on the home network. The mobile phone will not receive notification messages when it reacquires the home network and the TTL of those notifications have expired.

NOTE: The value is only used for message validity on the producer device. The TTL field is not sent as part of the notification message payload data over the end user's home network.

See Notification Service Framework Use Cases for use case scenarios related to notification message behavior.

Dismissing a notification

The dismiss notification is an option for consumers that have received the notification to let the producer know that this notification has been seen and there is no need to continue sending. It also lets other consumers know that the notification can be removed from the user display.

When a consumer attempts to dismiss a notification, the service framework creates a session with the producer using the original sender field sent in the notification.

Using the original sender field confirms that the notification is received by the actual producer and not the super agent in case the consumer received the notification from the super agent.

The producer will then send out a dismiss sessionless signal to notify the rest of the consumers in the network that this notification has been dismissed.

If the producer is not reachable, the consumer will send out the dismiss sessionless signal on its own.

Notification Interface

The Notification interface is announced such that when a device scans the network, it can find all producer devices.

Interface name

Interface name Version Secured
org.alljoyn.Notification 1 no

Properties

Property name Signature List of values Writable Description
Version q Positive integers no Interface version number

Signals

Signal name Parameters Sessionless Description
Name / Signature
Notify (listed below) yes AllJoyn signal carrying notification message.
notifMsg / q See Data types

Data types

Signature Definition Signature Description
notificationMsg version short Version of the Notification protocol.
msgId integer Unique identification assigned to the notification message by the Notification service framework.
msgType short Type of notification message.
* 0 - Emergency
* 1 - Warning
* 2 - Information
deviceId string Globally unique identifier for a given AllJoyn-enabled device.
deviceName string Name for a given AllJoyn-enabled device.
appId array of bytes Globally unique identifier for a given AllJoyn application.
appName string Name for a given AllJoyn-enabled device.
List attributes Set of attribute and value pair. This is used to hold optional fields in the notification message payload. See Attributes.
List customAttributes Set of attribute and value pair. This can be used by the OEMs to add OEM-specific fields to the notification message.
langText langTag string Language associated with the notification text. This is set as per RFC 5646.
text string Notification message text in UTF-8 character encoding.
attributes attrName string Name of the attribute.
attrValue variant Value of the attribute.
customAttributes attrName string Name of the attribute.
attrValue variant Value of the attribute.

NOTE: If the richIconUrl, richAudioUrl, richIconObjectPath, richAudioObjectPath, or respObjectPath fields were specified by the producer app for a notification message, the Notification service framework sends this information as attributes in the attributes field, as per Attributes.

Attributes

Attribute Values
Rich Notification Url * attrName=0
* attrValue=
* variant signature=s
* value=
Rich Notification Audio Url * attrName=1
* attrValue=
* variant signature=a{ss}
* value=List
Rich Notification Icon Object Path * attrName=2
* attrValue=
* variant signature=o
* value=
Rich Notification Audio Object Path * attrName=3
* attrValue=
* variant signature=o
* value=
Response Object Path * attrName=4
* attrValue=
* variant signature=o
* value=
Original Sender * attrName=5
* attrValue=
* variant signature=s
* value=

Introspection XML

The following XML provides the Notification interface introspection XML.

<?xml version="1.0" encoding="UTF-8" ?>
<node xsi:noNamespaceSchemaLocation="https://www.allseenalliance.org/schemas/introspect.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <interface name="org.alljoyn.Notification">
      <property name="Version" type="q" access="read"/>
      <signal name="notify">
         <arg name="version" type="q"/>
         <arg name="msgId" type="i"/>
         <arg name="msgType" type="q"/>
         <arg name="deviceId" type="s"/>
         <arg name="deviceName" type="s"/>
         <arg name="appId" type="ay"/>
         <arg name="appName" type="s"/>
         <arg name="attributes" type="a{iv}"/>
         <arg name="customAttributes" type="a{ss}"/>
         <arg name="langText" type="a(ss)"/>
      </signal>
   </interface>
</node>

Notification Producer Interface

The Notification Producer interface is announced such that, when a device scans the network, it can find all producer devices.

Interface name

Interface name Version Secured
org.alljoyn.Notification.Producer 1 no

Properties

Property name Signature List of values Writable Description
Version q Positive integers no Interface version number

Methods

Method name Parameters Description
Name / Data type
Dismiss msgId / integer A way to notify the producer that a notification was dismissed.

Introspection XML

The following XML provides the Notification Producer interface introspection XML.

<?xml version="1.0" encoding="UTF-8" ?>
<node xsi:noNamespaceSchemaLocation="https://www.alljoyn.org/schemas/introspect.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <interface name="org.alljoyn.Notification.Producer">
      <method name="Dismiss">
         <arg name="msgId" type="i" direction="in"/>
      </method>
      <property name="Version" type="q" access="read"/>
   </interface>
</node>

Dismisser Interface

The Dismiss sessionless signals are sent to notify other consumers on the proximal network that a notification has been dismissed.

Interface name

Interface name Version Secured
org.alljoyn.Notification.Dismisser 1 no

Properties

Property name Signature List of values Writable Description
Version q Positive integers no Interface version number

Signals

Signal name Parameters Sessionless Description
Name / Signature
Dismiss (listed below) yes A way to notify consumers that the notification has been dismissed.
msgId / i
appId / array of bytes

Introspect XML

The following XML provides the Notification Dismisser interface introspection XML.

<?xml version="1.0" encoding="UTF-8" ?>
<node xsi:noNamespaceSchemaLocation="https://www.alljoyn.org/schemas/introspect.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <interface name="org.alljoyn.Notification.Dismisser">
      <signal name="Dismiss">
         <arg name="msgId" type="i" direction="in"/>
         <arg name="appId" type="ay" direction="in"/>
      </signal>
      <property name="Version" type="q" access="read"/>
   </interface>
</node>

Notification Service Framework Use Cases

Device connecting within and outside the TTL period

Figure 3 illustrates two consumers (television and tablet) connecting within the notification message TTL period and a third consumer (smartphone) connecting after the TTL period. The first two consumers receive the notification message, the third consumer does not.

NOTE: The AllJoyn core block represents the collective AllJoyn framework functionality on various producers and consumers.

notification-use-case-ttl-period

Figure: Notification message behavior within and outside the TTL period

Notification message handling based on message types

Figure 4 illustrates how a notification message overwrites a notification message of the same type, and how notification messages of different types can coexist using the AllJoyn framework.

NOTE: The AllJoyn core block represents the collective AllJoyn framework functionality on various producers and consumers.

notification-use-case-msg_handling

Figure: Notification message handling based on message type

Notifications dismissed when producer is on network

Figure 5 illustrates the flow of dismissing a notification from the consumer until it is received by other consumers on the network.

notification-use-case-dismissed-notification-producer

Figure: Notifications that are dismissed when the producer is on the network