From OpenHome

(Difference between revisions)
Jump to: navigation, search
(→External document dependencies)
(→Table 3.1. widgetService element description)
Line 99: Line 99:
The widgetService element contains the definition of a service available on the Widget.
The widgetService element contains the definition of a service available on the Widget.
-
=== Table 3.1. widgetService element description ===
+
==== Table 3.1. widgetService element description ====
-
{|style="border-collapse: separate; border-spacing: 0; border-width: 1px; border-style: solid; border-color: #000; padding: 3"
+
{|
|-
|-
-
!style="border-style: solid; border-width: 0 1px 1px 0"| '''Element'''  
+
!|'''Element'''  
-
!style="border-style: solid; border-width: 0 0 1px 0"| '''Description'''
+
!| '''Description'''
|-
|-
-
|style="border-style: solid; border-width: 0 1px 0 0"| widgetService
+
| widgetService
-
|style="border-style: solid; border-width: 0"| Contains the definition of a Widget's service. This
+
| Contains the definition of a Widget's service. This
element begins and ends a Widget Service XML
element begins and ends a Widget Service XML
file.
file.
Line 113: Line 113:
-
{| border="2" cellpadding="20" cellspacing="0"
+
The widgetService element has several child elements. They are defined as follows:
-
|+ align="bottom" style="color:#e76700;" |''Table 3.1 widgetService element description''
+
-
|-
+
-
|'''Element'''
+
-
|'''Description'''
+
-
|-
+
-
|widgetService
+
-
|Contains the definition of a Widget's service. This elements begins and ends a Widget Service XML file.
+
-
|}
+
-
Element Description
+
==== Table 3.2. widgetService child elements description ====
-
widgetService Contains the definition of a Widget's service. This
+
 
-
element begins and ends a Widget Service XML
+
{|
-
file.
+
|-
-
The widgetService element has several child elements. They are defined as follows:
+
|description
-
Table 3.2. widgetService child elements description
+
|Contains a plain text description of your Widget, its
-
Element Description
+
-
description Contains a plain text description of your Widget, its
+
service and the properties the service provides. It
service and the properties the service provides. It
appears as a programmer API comment above the
appears as a programmer API comment above the
class definitions in both the auto-generated Proxy
class definitions in both the auto-generated Proxy
and Provider files.
and Provider files.
 +
|-
 +
|version
 +
|Contains a plain text description of your Widget, its
 +
service and the properties the service provides. It
 +
appears as a programmer API comment above the
 +
class definitions in both the auto-generated Proxy
 +
and Provider files.
 +
|}
 +
version Contains the major and minor version numbers of
version Contains the major and minor version numbers of
the OpenHome XSD used to validate your XML.
the OpenHome XSD used to validate your XML.

Revision as of 11:57, 1 March 2012

Contents

Introduction

This document is for Widget manufacturers using OpenHome to define Widget services and properties. The services and properties are defined in XML, following the schema published by OpenHome.

Note

Note The OpenHome SDK contains a copy of the WidgetService.xsd used for validation. OpenHome may occasionally update the XSD definition to include new Widget properties. When these become available, OpenHome will publish the new XSD documents on openhome.org. All new XSD documents will be included in new releases of the SDK.


To help you produce your Widget Service XML file, this document provides descriptions of each element you can use in your own Widget Service XML file. A sample Widget Service XML file is used throughout the document.


Prerequisites

To begin defining your Widget Service XML you must in possession of the following items:

  • technical details about the properties your Widget physically provides
  • the OpenHome SDK, specifically the WidgetService.xsd file


Related documents

The XML you define is used in several areas of Widget development. Refer to the following documents to see how the XML is used:


Widget Service XML

The Widget Service XML file is used to define the features that your Widget provides to users.

Each of these features is described as a property in the Widget Service XML. This may be a simple light Widget offering an on/off — or power — property, or a more complicated Widget offering volume, bass, and treble properties.

Your Widget Service XML file can contain as many properties as are necessary to describe the full range of the Widget's feature set. Your Widget Service XML must contain at least one property.

Internal structure

The Widget Service XML file is validated against an XSD. The XSD is included in the OpenHome SDK.

Snippet 1 shows an abstract hierarchy of the elements used in a Widget Service XML file. 

widgetservice
  description
  version
      major
      minor
  propertylist
      property
          name
          description
          dataType
          access
          allowedValueList*
              allowedValue
          allowedValueRange*
              minimum*
              maximum*
              step*

Snippet 1: An abstract view of a Widget Service XML, showing the structure of the various elements used. Elements marked * are optional.

The structure of the XML is defined by OpenHome. You cannot change it and expect your Widget to operate on an OpenHome network. However, some of the files you generate from it can be customized.


External document dependencies

Your Widget Service XML is used in several areas of Widget development. Several files are automatically generated from this one. Driver authors and UI developers both depend heavily on the code generated from your Widget Service XML. It is therefore essential that you write a well-formed Widget Service XML, conforming to the schema defined in the WidgetService.xsd.

The diagram below shows the significance of the Widget Service XML in relation to the generated files used by other developers to define and publish your Widget on an OpenHome network:

Figure 1: The OpenHome document hierarcy, showing the files you can generate from the Widget Service XML.


The JavaScript proxies and the UI HTML and JavaScript files are used by Web UI developers to style and customize the UI that will run on an OpenHome Node.

The C# Provider is used by Widget driver authors to help them write the code required to operate the Widget.

The C# Proxy is used by developers to produce a C# control point application which can be used in place of the standard Web UI.

XML elements

The following tables explain each XML element that can appear in a Widget Service XML file. Descriptions of each element are provided alongside to explain their use. An example of the elements in use is provided in the appendix.

Note

Unless otherwise stated, each of the following elements is mandatory and must appear in your Widget Service XML.

widgetService

The widgetService element contains the definition of a service available on the Widget.

Table 3.1. widgetService element description

Element Description
widgetService Contains the definition of a Widget's service. This

element begins and ends a Widget Service XML file.


The widgetService element has several child elements. They are defined as follows:


Table 3.2. widgetService child elements description

description Contains a plain text description of your Widget, its

service and the properties the service provides. It appears as a programmer API comment above the class definitions in both the auto-generated Proxy and Provider files.

version Contains a plain text description of your Widget, its

service and the properties the service provides. It appears as a programmer API comment above the class definitions in both the auto-generated Proxy and Provider files.

version Contains the major and minor version numbers of the OpenHome XSD used to validate your XML. propertylist Contains the list of properties you want to make available on the Widget. Each entry in this list describes a single property using the property element.

Retrieved from "http://wiki.openhome.org/wiki/OhWidget_Service_XML_Definition"