From OpenHome

(Difference between revisions)

Revision as of 13:39, 11 June 2013

Architectural Overview

The Product service contains a summary of a single product’s capabilities. Control points should begin their interaction with an av.openhome device by searching for the Product service. Presence of various other services can be inferred from the sources and attributes reported.

Actions

Sources

The set of available sources does not vary at run-time (although some source attributes may change). There is always a single source active. Only the active source will play audio or report state updates.

SourceCount

Query the value of the (read-only) SourceCount state variable.

SetSourceIndex

Set the currently active source. The value specified is zero-based and used to index into the source list returned by the SourceXml action / state variable.

SetSourceIndexByName

Set the currently active source. The value specified is matched against the Type attributes from the SourceXml action / state variable.

SourceXml

Query the value of the SourceXml state variable.

SourceXmlChangeCount

Query how often the SourceXml state variable has been updated. This action can be polled by clients that don’t support eventing. Whenever the value returned increases, the SourceXml has been updated so should be queried again.

Network Presentation

Attributes

tbd

Manufacturer

Return the values of the ManufacturerName, ManufacturerInfo, ManufacturerUrl, ManufacturerImageUri state variables. All are read-only so the values returned will not vary at runtime.

Model

Return the values of the ModelName, ModelInfo, ModelUrl, ModelImageUri state variables. All are read-only so the values returned will not vary at runtime.

Product

Return the values of the ProductRoom, ProductName, ProductInfo, ProductUrl, ProductImageUri state variables.

Standby

Return the value of the Standby state variable.

SetStandby

Set the value of the Standby state variable. The SetStandby action provides a means of setting the current standby state of the product.

State Variables

Sources

SourceCount

The number of available sources. Read-only.

SourceIndex

The index of the currently active source. This is zero-based so will be in the range [0..SourceCount-1]

SourceXml

Returns a summary of all sources in the form

   <SourceList>
       <sourcetag>
           <Name>[user name for source]</Name>
           <Type>[system name for source.  Read-only]</Type>
           <Visible>[Boolean.  Whether control points should display source]</Visible>
       </sourcetag>
   </SourceList>

Network Presentation

Attributes

Space delimited set of values. Each value guarantees the availability of a service or resource, saving a control point for searching for each of these in turn. Supported values for attributes include

- Info – the av.openhome.org:Info:1 service is available
- Time – the av.openhome.org:Time:1 service is available
- Volume – the av.openhome.org:Volume:1 service is available
- Sender - the av.openhome.org:Sender:1 service is available
- App:Config=[link] – web UI for device configuration is available at the url [link]

ManufacturerImageUri

Uri for manufacturer’s logo. Read-only.

ManufacturerInfo

Manufacturer information. Read-only

ManufacturerName

Manufacturer name. Read-only.

ManufacturerUrl

URL for manufacturer web site. Read only.

ModelImageUri

Uri for model’s icon. Read-only.

ModelInfo

Model information. Read-only.

ModelName

Model name. Read-only.

ModelUrl

URL for model web site. Read-only.

ProductImageUri

Uri for product. Read-only.

ProductInfo

Product information. Read-only.

ProductName

User-visible product name. By default this is set to ModelName. Note that the UPnP friendly name is derived by combining this with Room name in the form Room : Name

ProductRoom

The name of the room where the Product is located. Set to “Main Room” by default. ProductRoom is used to group the Product with other related Products in the same physical room (e.g. a source with a pre-amp). Products which are physically linked must always share the same ProductRoom name. Room is set to Main Room by default.

ProductUrl

URL for product web site. This may be the UPnP presentation page.

Standby

The standby state of a product (true => standby enabled)

Product Service Description (XML)

<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
    <specVersion>
        <major>1</major>
        <minor>0</minor>
    </specVersion>
    <actionList>
        <action>
            <name>Manufacturer</name>
            <argumentList>
                <argument>
                    <name>Name</name>
                    <direction>out</direction>
                    <relatedStateVariable>ManufacturerName</relatedStateVariable>
                </argument>
                <argument>
                    <name>Info</name>
                    <direction>out</direction>
                    <relatedStateVariable>ManufacturerInfo</relatedStateVariable>
                </argument>
                <argument>
                    <name>Url</name>
                    <direction>out</direction>
                    <relatedStateVariable>ManufacturerUrl</relatedStateVariable>
                </argument>
                <argument>
                    <name>ImageUri</name>
                    <direction>out</direction>
                    <relatedStateVariable>ManufacturerImageUri</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>Model</name>
            <argumentList>
                <argument>
                    <name>Name</name>
                    <direction>out</direction>
                    <relatedStateVariable>ModelName</relatedStateVariable>
                </argument>
                <argument>
                    <name>Info</name>
                    <direction>out</direction>
                    <relatedStateVariable>ModelInfo</relatedStateVariable>
                </argument>
                <argument>
                    <name>Url</name>
                    <direction>out</direction>
                    <relatedStateVariable>ModelUrl</relatedStateVariable>
                </argument>
                <argument>
                    <name>ImageUri</name>
                    <direction>out</direction>
                    <relatedStateVariable>ModelImageUri</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>Product</name>
            <argumentList>
                <argument>
                    <name>Room</name>
                    <direction>out</direction>
                    <relatedStateVariable>ProductRoom</relatedStateVariable>
                </argument>
                <argument>
                    <name>Name</name>
                    <direction>out</direction>
                    <relatedStateVariable>ProductName</relatedStateVariable>
                </argument>
                <argument>
                    <name>Info</name>
                    <direction>out</direction>
                    <relatedStateVariable>ProductInfo</relatedStateVariable>
                </argument>
                <argument>
                    <name>Url</name>
                    <direction>out</direction>
                    <relatedStateVariable>ProductUrl</relatedStateVariable>
                </argument>
                <argument>
                    <name>ImageUri</name>
                    <direction>out</direction>
                    <relatedStateVariable>ProductImageUri</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>Standby</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>out</direction>
                    <relatedStateVariable>Standby</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>SetStandby</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>in</direction>
                    <relatedStateVariable>Standby</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>SourceCount</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>out</direction>
                    <relatedStateVariable>SourceCount</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>SourceXml</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>out</direction>
                    <relatedStateVariable>SourceXml</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>SourceIndex</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>out</direction>
                    <relatedStateVariable>SourceIndex</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>SetSourceIndex</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>in</direction>
                    <relatedStateVariable>SourceIndex</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>SetSourceIndexByName</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>in</direction>
                    <relatedStateVariable>SourceName</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>Source</name>
            <argumentList>
                <argument>
                    <name>Index</name>
                    <direction>in</direction>
                    <relatedStateVariable>SourceIndex</relatedStateVariable>
                </argument>
                <argument>
                    <name>SystemName</name>
                    <direction>out</direction>
                    <relatedStateVariable>SourceName</relatedStateVariable>
                </argument>
                <argument>
                    <name>Type</name>
                    <direction>out</direction>
                    <relatedStateVariable>SourceType</relatedStateVariable>
                </argument>
                <argument>
                    <name>Name</name>
                    <direction>out</direction>
                    <relatedStateVariable>SourceName</relatedStateVariable>
                </argument>
                <argument>
                    <name>Visible</name>
                    <direction>out</direction>
                    <relatedStateVariable>SourceVisible</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>Attributes</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>out</direction>
                    <relatedStateVariable>Attributes</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>SourceXmlChangeCount</name>
            <argumentList>
                <argument>
                    <name>Value</name>
                    <direction>out</direction>
                    <relatedStateVariable>SourceXmlChangeCount</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
    </actionList>
    <serviceStateTable>
        <stateVariable sendEvents="yes">
            <name>ManufacturerName</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ManufacturerInfo</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ManufacturerUrl</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ManufacturerImageUri</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ModelName</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ModelInfo</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ModelUrl</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ModelImageUri</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ProductRoom</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ProductName</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ProductInfo</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ProductUrl</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>ProductImageUri</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>Standby</name>
            <dataType>boolean</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>SourceIndex</name>
            <dataType>ui4</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>SourceCount</name>
            <dataType>ui4</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>SourceXml</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>Attributes</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="no">
            <name>SourceXmlChangeCount</name>
            <dataType>ui4</dataType>
        </stateVariable>
        <stateVariable sendEvents="no">
            <name>SourceType</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="no">
            <name>SourceName</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="no">
            <name>SourceVisible</name>
            <dataType>boolean</dataType>
        </stateVariable>
    </serviceStateTable>
</scpd>

@@ Line 1: / Line 1: @@
 = Architectural Overview =
-The Product service contains basic information concerning a single product. It contains information about what kind of device it is: the model, manufacturer, its name, its room, and details concerning each source within the product. Other basic functionality such as control of the product's standby state are also included.
+The Product service contains a summary of a single product’s capabilities.  Control points should begin their interaction with an av.openhome device by searching for the Product service.  Presence of various other services can be inferred from the sources and attributes reported.
-It should be possible for a control point to create a complete map of the home by subscribing to the Product service of every device.
+= Actions =
+== Sources ==
+The set of available sources does not vary at run-time (although some source attributes may change).  There is always a single source active.  Only the active source will play audio or report state updates.
+=== SourceCount ===
+Query the value of the (read-only) SourceCount state variable.
+=== SetSourceIndex ===
+Set the currently active source.  The value specified is zero-based and used to index into the source list returned by the SourceXml action / state variable.
+=== SetSourceIndexByName ===
+Set the currently active source.  The value specified is matched against the Type attributes from the SourceXml action / state variable.
+=== SourceXml ===
+Query the value of the SourceXml state variable.
+=== SourceXmlChangeCount ===
+Query how often the SourceXml state variable has been updated.  This action can be polled by clients that don’t support eventing.  Whenever the value returned increases, the SourceXml has been updated so should be queried again.
 == Network Presentation ==
 === Attributes ===
-Every product has one or more attributes indicating additional features offered by that product beyond those provided by its sources
+tbd
 === Manufacturer ===
-There are '''four''' Manufacturer parameters; '''Name''', '''Info''', '''Url''' and '''ImageUri'''. They are all text strings.
+Return the values of the ManufacturerName, ManufacturerInfo, ManufacturerUrl, ManufacturerImageUri state variables.  All are read-only so the values returned will not vary at runtime.
-==== Name ====
-Name contains the Manufacturer name. Name is read only.
-==== Info ====
-Info contains more Manufacturer information. Info is read only.
-==== Url ====
-Url contains the Manufacturer website address. Url is read only.
-==== ImageUri ====
-ImageUri contains a link to the Manufacturer image (i.e. logo). ImageUri is read only.
 === Model ===
+Return the values of the ModelName, ModelInfo, ModelUrl, ModelImageUri state variables.  All are read-only so the values returned will not vary at runtime.
-There are '''four''' Model parameters; '''Name''', '''Info''', '''Url''' and '''ImageUri'''.
-==== Name ====
-Name contains the Model name. Name is read only.
-==== Info ====
-Info contains more Model information. Info is read only.
-==== Url ====
-Url contains the Model website address. Url is read only.
-==== ImageUri ====
-ImageUri contains a link to the Model image (i.e. icon). ImageUri is read only.
 === Product ===
-There are '''five''' Product parameters; '''Room''', '''Name''', '''Info''', '''Url''' and '''ImageUri'''. They are all text strings.
+Return the values of the ProductRoom, ProductName, ProductInfo, ProductUrl, ProductImageUri state variables.
-==== Room ====
+== Standby ==
-This is the name of the room where the Product is located. Room is used to group the Product with other Products in the same physical room. The Upnp '''''Friendly Name''''' is derived by combining Room and Name in the format {'''''Room&nbsp;: Name'''''}. Products which are '''''Linked''''' always share the same Room name. Room is set to '''''Main Room''''' by default.
+=== Standby ===
+Return the value of the Standby state variable.
+=== SetStandby ===
+Set the value of the Standby state variable.
+The SetStandby action provides a means of setting the current standby state of the product.
-==== Name ====
-This is the Product name. The Upnp '''''Friendly Name''''' is derived by combining Room and Name in the format {'''''Room&nbsp;: Name'''''}. By default the Name is the same as the Model.
-==== Info ====
-Info contains more Product information. Info is read only.
-==== Url ====
-Url contains the Product website address (i.e. UPnP presentation page). Url is read only.
-==== ImageUri ====
-ImageUri contains a link to the Product image (i.e. icon). ImageUri is read only.
-== Standby Control==
-=== Standby===
-This is the Standby state of the physical product. Standby can be changed using the SetStandby function. Products which are '''''Linked''''' always share the same Standby state.
-== Source Control ==
-=== Source List===
-The Product service maintains a list of all sources within the Product. The size of this list is fixed for each Product and reported by the SourceCount function. Each source can then be referenced by its unique source index* in the list. Only one source, and thus one index, can be active at any given time. When a new source is selected the previous source is automatically deactivated before activating the new source. [* source index is zero based, ie 0,1,2,3,4,5..n, where n=listsize-1]
-=== Source Index ===
-The current (ie currently active) source can be changed by source index or source name. The function SetSourceIndex is used to change the current source by index. If the index is out of range an error will be reported. SetSourceIndexByName is used to change to the source whose name matches that specified. If a source of the specified name does not exist, the source will not change and no error will be reported.
+= State Variables =
+== Sources ==
 === SourceCount ===
+The number of available sources.  Read-only.
+=== SourceIndex ===
+The index of the currently active source.  This is zero-based so will be in the range [0..SourceCount-1]
+=== SourceXml ===
+Returns a summary of all sources in the form
-SourceCount returns the number of sources that exist in the Product (ie the source list size). SourceCount is read only.
+    <SourceList>
+        <sourcetag>
+            <Name>[user name for source]</Name>
+            <Type>[system name for source.  Read-only]</Type>
+            <Visible>[Boolean.  Whether control points should display source]</Visible>
+        </sourcetag>
+    </SourceList>
+== Network Presentation ==
+=== Attributes ===
+Space delimited set of values.  Each value guarantees the availability of a service or resource, saving a control point for searching for each of these in turn.  Supported values for attributes include
+ - Info – the av.openhome.org:Info:1 service is available
+ - Time – the av.openhome.org:Time:1 service is available
+ - Volume – the av.openhome.org:Volume:1 service is available
+ - Sender - the av.openhome.org:Sender:1 service is available
+ - App:Config=[link] – web UI for device configuration is available at the url [link]
+=== ManufacturerImageUri ===
+Uri for manufacturer’s logo.  Read-only.
+=== ManufacturerInfo ===
+Manufacturer information.  Read-only
+=== ManufacturerName ===
+Manufacturer name.  Read-only.
+=== ManufacturerUrl ===
+URL for manufacturer web site.  Read only.
+=== ModelImageUri ===
+Uri for model’s icon.  Read-only.
+=== ModelInfo ===
+Model information.  Read-only.
+=== ModelName ===
+Model name.  Read-only.
+=== ModelUrl ===
+URL for model web site.  Read-only.
+=== ProductImageUri ===
+Uri for product.  Read-only.
+=== ProductInfo ===
+Product information.  Read-only.
+=== ProductName ===
+User-visible product name.  By default this is set to ModelName.
+Note that the UPnP friendly name is derived by combining this with Room name in the form Room : Name
+=== ProductRoom ===
+The name of the room where the Product is located.  Set to “Main Room” by default.
+ProductRoom is used to group the Product with other related Products in the same physical room (e.g. a source with a pre-amp).  Products which are physically linked must always share the same ProductRoom name. Room is set to Main Room by default.
+=== ProductUrl ===
+URL for product web site.  This may be the UPnP presentation page.
-=== Source Specific Parameters ===
+== Standby ==
-Every source has four fundamental parameters, '''SourceSystemName''', '''SourceName''', '''SourceVisible''' and '''SourceType'''.
+=== Standby ===
+The standby state of a product (true => standby enabled)
-==== SourceSystemName ====
-SourceSystemName is a unique name string used to identify each source. SourceSystemName is read only. It can only be read via the '''Source''' action.
-==== SourceName ====
-SourceName is a unique name string assigned to each source. In the default state, for a given source index, SourceName matches SourceSystemName. It can be read via the '''Source''' action, or the '''SourceXml''' action.
-==== SourceType ====
-SourceType is a unique type string assigned to each source. SourceType is read only. It can be read via the '''Source''' action, or the '''SourceXml''' action.
-==== SourceVisible ====
-SourceVisible is a unique flag assigned to each source. This flag is used to indicate whether the source is to be displayed (front panel, GUI etc) when browsing through the source list. It can be read via the '''Source''' action, or the '''SourceXml''' action.
-Note - ''a source's "visibility" does not affect its ability to be selected/activated via the functions SetSourceIndex and SetCurrentSourceByName.''
-= Actions=
-== Network Presentation Actions==
-=== Attributes Action ===
-The Attributes action reports a string containing a space separated list of all attributes.
-=== Manufacturer Action ===
-The Manufacturer action returns all four Manufacturer parameters.
-=== Model Action ===
-The Model action returns all four Model parameters.
-=== Product Action ===
-The Product action returns all five Product parameters.
-== Standby Actions==
-=== Standby===
-The Standby action reports the current standby state of the product.
-=== SetStandby===
-The SetStandby action provides a means of setting the current standby state of the product.
-==Source Actions==
-===SourceXml Action===
-The SourceXml action returns a list of all source specific parameters, for every source, in XML format.
-===SourceXmlChangeCount Action===
-The SourceXmlChangeCount action returns a count indicating the number of times SourceXml has been updated since power on. This is useful for control points that do not support eventing.
-===Source Action===
-The Source action returns all source specific parameters for a given source index.
-= Technical Details =
-<code>
-    Domain  : av.openhome.org
-    Name    : Product
-    Version : 1
-</code>
-== Product Service Description (XML) ==
+= Product Service Description (XML) =
 <syntaxhighlight lang="xml">
 <?xml version="1.0" encoding="utf-8"?>

From OpenHome

Revision as of 13:39, 11 June 2013

Contents

Architectural Overview

Actions

Sources

SourceCount

SetSourceIndex

SetSourceIndexByName

SourceXml

SourceXmlChangeCount

Network Presentation

Attributes

Manufacturer

Model

Product

Standby

Standby

SetStandby

State Variables

Sources

SourceCount

SourceIndex

SourceXml

Network Presentation

Attributes

ManufacturerImageUri

ManufacturerInfo

ManufacturerName

ManufacturerUrl

ModelImageUri

ModelInfo

ModelName

ModelUrl

ProductImageUri

ProductInfo

ProductName

ProductRoom

ProductUrl

Standby

Standby

Product Service Description (XML)