About Feature Interface Definitions

Release History

To access a previous version of this document, click the release version link below.

Release versionDateWhat changed
14.022/28/2014About interface version 1 was added.
14.066/30/2014No updates.
14.06 Update 19/29/2014Updated the document title and Overview chapter title (changed from Specification to Definition)Added the release version number to the document title for version tracking.Added a note in the Definition Overview chapter to address the AllSeen Alliance Compliance and Certification program.Added a Mandatory column for method and signal parameters to support the AllSeen Alliance Compliance and Certification program.
14.1212/17/2014Changed DeviceName from required to not requiredAdditional clarification specifying the AppId must be 128-bit UUID as specified in RFC 4122Cleanup to make requirements for methods and signals more clearIcon interface was added. The icon interface has been part of AllJoyn™ and the About Feature since 14.02; however, the interface definition documentation was not added until 14.12.

Definition Overview

The About interface is to be implemented by an application on a target device. This interface allows the app to advertise itself so other apps can discover it. The following figure illustrates the relationship between a client app and a service app.

Figure: About feature architecture within the AllJoyn™ framework

NOTE: All methods and signals are considered mandatory to support the AllSeen Alliance Compliance and Certification program.

Discovery

A client can discover the app via an announcement, which is a sessionless signal containing the basic app information like app name, device name, manufacturer, and model number. The announcement also contains the list of object paths and service framework interfaces to allow the client to determine whether the app provides functionality of interest.

In addition to the sessionless announcement, the About interface also provides the on-demand method calls to retrieve all the available metadata about the app that are not published in the announcement.

Discovery Call Flows

Typical discovery flow

The following figure illustrates a typical call flow for a client to discover a service app. The client merely relies on the sessionless announcement to decide whether to connect to the service app to use its service framework offering.

Figure: Typical discovery flow (client discovers a service app)

Nontypical discovery flow

The following figure illustrates a call flow for a client to discover a service app and make a request for more detailed information.

Figure: Nontypical discovery call flow

Error Handling

The method calls in the About interface will use the AllJoyn error message handling feature (ER_BUS_REPLY_IS_ERROR_MESSAGE) to set the error name and error message.

Error nameError message
org.alljoyn.Error.LanguageNotSupportedThe language specified is not supported

About Interface

Interface nameVersionSecuredObject path
org.alljoyn.About1no/About

Properties

Property nameSignatureList of valuesRead/WriteDescription
VersionqPositive integersRead OnlyInterface version number

Methods

The following methods are exposed by a BusObject that implements the org.alljoyn.About interface.

a{sv} GetAboutData('s')

Message arguments

ArgumentParameter nameSignatureList of valuesDescription
0languageTagsIETF language tags specified by RFC 5646.The desired language.

Reply arguments

ArgumentParameter nameReturn signatureDescription
0AboutDataa{sv}A dictionary of the available metadata fields. If language tag is not specified (i.e., “”), metadata fields based on default language are returned.

Error reply

ErrorDescription
org.alljoyn.Error.LanguageNotSupportedReturned if a language tag is not supported

Description

Retrieve the list of available AboutData fields based on the language tag. see About data interface fields

About data interface fields

The following table lists the names of the metadata fields. The fields with a yes value in the Announced column will also be published via the Announce signal. See Signals for more information.

Field nameMandatoryAnnouncedLocalizedSignatureDescription
AppIdyesyesnoayA 128-bit globally unique identifier for the application. The AppId shall be a universally unique identifier as specified in RFC 4122.
DefaultLanguageyesyesnosThe default language supported by the device. Specified as an IETF language tag listed in RFC 5646.
DeviceNamenoyesyessName of the device set by platform-specific means (such as Linux and Android).
DeviceIdyesyesnosDevice identifier set by platform-specific means.
AppNameyesyesyessApplication name assigned by the app manufacturer (developer or the OEM).
ManufactureryesyesyessThe manufacturer’s name of the app.
ModelNumberyesyesnosThe app model number.
SupportedLanguagesyesnonoasList of supported languages.
DescriptionyesnoyessDetailed description expressed in language tags as in RFC 5646.
DateOfManufacturenononosDate of manufacture using format YYYY-MM-DD (known as XML DateTime format).
SoftwareVersionyesnonosSoftware version of the app.
AJSoftwareVersionyesnonosCurrent version of the AllJoyn SDK used by the application.
HardwareVersionnononosHardware version of the device on which the app is running.
SupportUrlnononosSupport URL (populated by the manufacturer).

a(oas) GetObjectDescription()

Message arguments

None.

Reply arguments

ArgumentParameter nameReturn signatureDescription
0objectDescriptiona(oas)Return the array of object paths and the list of supported interfaces provided by each object.

Description

Retrieve the object paths and the list of all interfaces implemented by each of objects.

Signals

The following signals are emitted by a BusObject that implements the org.alljoyn.About interface.

Announce('qqa(oas)a{sv}')

Announce signal is a Sessionless signal

Message arguments

ArgumentParameter nameSignatureList of valuesDescription
0versionqpositiveVersion number of the About interface.
1portqpositiveSession port the app will listen on incoming sessions.
2objectDescriptiona(oas)Populated based on announced interfacesArray of object paths and the list of supported interfaces provided by each object.
3aboutDataa{sv}array of key/value pairsAll the fields listed in About data interface fields with a yes value in the Announced column are provided in this signal.

AllJoyn Introspection XML

ExplainExplain<node name="/About" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.allseenalliance.org/schemas/introspect.xsd"> <interface name="org.alljoyn.About"> <property name="Version" type="q" access="read"/> <method name="GetAboutData"> <arg name="languageTag" type="s" direction="in"/> <arg name="aboutData" type="a{sv}" direction="out"/> </method> <method name="GetObjectDescription"> <arg name="objectDescription" type="a(oas)" direction="out"/> </method> <signal name="Announce"> <arg name="version" type="q"/> <arg name="port" type="q"/> <arg name="objectDescription" type="a(oas)"/> <arg name="metaData" type="a{sv}"/> </signal> </interface> </node>

Icon Interface

Interface nameVersionSecuredObject path
org.alljoyn.Icon1no/About/DeviceIcon

Properties

Property nameSignatureList of valuesRead/WriteDescription
VersionqPositive integersRead OnlyInterface version number
MimeTypesThe Mime type corresponding to the icon’s binary contentRead OnlyMime type for the icon
SizeuThe size in bytes of the icons binary contentRead OnlySize of the Icon

Methods

The following methods are exposed by a BusObject that implements the org.alljoyn.Icon interface.

s GetUrl()

Message arguments

None.

Reply arguments

ArgumentParameter nameReturn signatureDescription
0urlsThe URL if the icon is hosted on the cloud

Description

Retrieve the URL of the icon if the icon is hosted on the cloud.

ay GetContent()

ArgumentParameter nameReturn signatureDescription
0contentayThe binary content for the icon

Signals

None.

AllJoyn Introspection XML

ExplainExplain<node name="/About/DeviceIcon" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.alljoyn.org/schemas/introspect.xsd"> <interface name="org.alljoyn.Icon"> <property name="Version" type="q" access="read"/> <property name="MimeType" type="s" access="read"/> <property name="Size" type="u" access="read"/> <method name="GetUrl"> <arg type="s" direction="out"/> </method> <method name="GetContent"> <arg type="ay" direction="out"/> </method> </interface> </node>