Difference between revisions of "Developer:Davaar:ProductService"
(→Standby) |
|||
| Line 7: | Line 7: | ||
A physical product may contain more than one Product and thus be presented as more than one Product service on the network. An example of this would be a preamplifier with an embedded DS source. In this scenario the two Product services are '''''Linked''''' (internally grouped). Linked Products share certain key parameters such as Standby and Room (ie changing Standby on one Product will automatically change the Standby state on all other Products in that '''''Linked''''' group). | A physical product may contain more than one Product and thus be presented as more than one Product service on the network. An example of this would be a preamplifier with an embedded DS source. In this scenario the two Product services are '''''Linked''''' (internally grouped). Linked Products share certain key parameters such as Standby and Room (ie changing Standby on one Product will automatically change the Standby state on all other Products in that '''''Linked''''' group). | ||
| − | = Network Presentation = | + | == Network Presentation == |
| − | == Attributes == | + | === Attributes === |
Every product has one or more attributes indicating the key features supported by that product. | Every product has one or more attributes indicating the key features supported by that product. | ||
| − | === Attributes Action === | + | ==== Attributes Action ==== |
The Attributes action reports a string containing a comma separated list of all attributes. | The Attributes action reports a string containing a comma separated list of all attributes. | ||
| − | == Manufacturer == | + | === Manufacturer === |
There are '''four''' Manufacturer attributes; '''Name''', '''Info''', '''Url''' and '''ImageUri'''. They are all text strings. | There are '''four''' Manufacturer attributes; '''Name''', '''Info''', '''Url''' and '''ImageUri'''. They are all text strings. | ||
| − | === Name === | + | ==== Name ==== |
Name contains the Manufacturer name (example: "''Linn''"). Name is read only. | Name contains the Manufacturer name (example: "''Linn''"). Name is read only. | ||
| − | === Info === | + | ==== Info ==== |
Info contains more Manufacturer information (example "''Linn Products Ltd''"). Info is read only. | Info contains more Manufacturer information (example "''Linn Products Ltd''"). Info is read only. | ||
| − | === Url === | + | ==== Url ==== |
Url contains the Manufacturer website address (example "''http://www.linn.co.uk''"). Url is read only. | Url contains the Manufacturer website address (example "''http://www.linn.co.uk''"). Url is read only. | ||
| − | === ImageUri === | + | ==== ImageUri ==== |
| − | === Manufacturer Action === | + | ==== Manufacturer Action ==== |
The Manufacturer action returns all four Manufacturer attributes. | The Manufacturer action returns all four Manufacturer attributes. | ||
| − | == Model == | + | === Model === |
There are '''four''' Model attributes; '''Name''', '''Info''', '''Url''' and '''ImageUri'''. | There are '''four''' Model attributes; '''Name''', '''Info''', '''Url''' and '''ImageUri'''. | ||
| − | === Name === | + | ==== Name ==== |
Name contains the Model name (example: "''Majik DS''"). Name is read only. | Name contains the Model name (example: "''Majik DS''"). Name is read only. | ||
| − | === Info === | + | ==== Info ==== |
Info contains more Model information (example "''Linn Hi-Fi component''"). Info is read only. | Info contains more Model information (example "''Linn Hi-Fi component''"). Info is read only. | ||
| − | === Url === | + | ==== Url ==== |
Url contains the Model website address (example "''http://products.linn.co.uk/MajikDS''"). Url is read only. | Url contains the Model website address (example "''http://products.linn.co.uk/MajikDS''"). Url is read only. | ||
| − | === ImageUri === | + | ==== ImageUri ==== |
| − | === Model Action === | + | ==== Model Action ==== |
The Model action returns all four Model attributes. | The Model action returns all four Model attributes. | ||
| − | == Product == | + | === Product === |
There are '''five''' Product attributes; '''Room''', '''Name''', '''Info''', '''Url''' and '''ImageUri'''. They are all text strings. | There are '''five''' Product attributes; '''Room''', '''Name''', '''Info''', '''Url''' and '''ImageUri'''. They are all text strings. | ||
| − | === Room === | + | ==== Room ==== |
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 : Name'''''}. Products which are '''''Linked''''' always share the same Room name. Room is set to '''''Main Room''''' by default. | 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 : Name'''''}. Products which are '''''Linked''''' always share the same Room name. Room is set to '''''Main Room''''' by default. | ||
| − | === Name === | + | ==== Name ==== |
This is the Product name. The Upnp '''''Friendly Name''''' is derived by combining Room and Name in the format {'''''Room : Name'''''}. By default the Name is the same as the Model. | This is the Product name. The Upnp '''''Friendly Name''''' is derived by combining Room and Name in the format {'''''Room : Name'''''}. By default the Name is the same as the Model. | ||
| − | === Info === | + | ==== Info ==== |
Info contains more Product information (example "''Linn Hi-Fi component''"). Info is read only. | Info contains more Product information (example "''Linn Hi-Fi component''"). Info is read only. | ||
| − | === Url === | + | ==== Url ==== |
Url is read only. | Url is read only. | ||
| − | === ImageUri === | + | ==== ImageUri ==== |
ImageUri is read only. | ImageUri is read only. | ||
| − | === Product Action === | + | ==== Product Action ==== |
The Product action returns all five Product attributes. | The Product action returns all five Product attributes. | ||
| − | = Standby Control= | + | == Standby Control== |
| − | == Standby== | + | === 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. | 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. | ||
| − | == Standby Actions== | + | === Standby Actions=== |
| − | === Standby=== | + | ==== Standby==== |
The Standby action reports the current standby state of the product. | The Standby action reports the current standby state of the product. | ||
| − | === SetStandby=== | + | ==== SetStandby==== |
The SetStandby action provides a means of setting the current standby state of the product. | The SetStandby action provides a means of setting the current standby state of the product. | ||
| − | = Source Control = | + | == Source Control === |
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] | 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 == | + | === 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. | 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. | ||
| − | == SourceCount == | + | === SourceCount === |
SourceCount returns the number of sources that exist in the Product (ie the source list size). SourceCount is read only. | SourceCount returns the number of sources that exist in the Product (ie the source list size). SourceCount is read only. | ||
| − | == Source Specific Parameters == | + | === Source Specific Parameters === |
Each source has four fundamental parameters, '''SourceSystemName''', '''SourceName''', '''SourceVisible''' and '''SourceType'''. | Each source has four fundamental parameters, '''SourceSystemName''', '''SourceName''', '''SourceVisible''' and '''SourceType'''. | ||
| − | === SourceSystemName === | + | ==== 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. | 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 ==== |
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. | 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 ==== |
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. | 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 ==== |
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. | 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. | ||
| Line 116: | Line 116: | ||
Note - ''a source's "visibility" does not affect its ability to be selected/activated via the functions SetSourceIndex and SetCurrentSourceByName.'' | Note - ''a source's "visibility" does not affect its ability to be selected/activated via the functions SetSourceIndex and SetCurrentSourceByName.'' | ||
| − | ==Source Actions== | + | ===Source Actions=== |
| − | ===SourceXml Action=== | + | ====SourceXml Action==== |
The SourceXml action returns a list of all source specific parameters, for every source, in XML format. | The SourceXml action returns a list of all source specific parameters, for every source, in XML format. | ||
| − | ===SourceXmlChangeCount Action=== | + | ====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. | 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=== | + | ====Source Action==== |
The Source action returns all source specific parameters for a given source index. | The Source action returns all source specific parameters for a given source index. | ||
Revision as of 18:04, 23 November 2010
Contents
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.
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.
A physical product may contain more than one Product and thus be presented as more than one Product service on the network. An example of this would be a preamplifier with an embedded DS source. In this scenario the two Product services are Linked (internally grouped). Linked Products share certain key parameters such as Standby and Room (ie changing Standby on one Product will automatically change the Standby state on all other Products in that Linked group).
Network Presentation
Attributes
Every product has one or more attributes indicating the key features supported by that product.
Attributes Action
The Attributes action reports a string containing a comma separated list of all attributes.
Manufacturer
There are four Manufacturer attributes; Name, Info, Url and ImageUri. They are all text strings.
Name
Name contains the Manufacturer name (example: "Linn"). Name is read only.
Info
Info contains more Manufacturer information (example "Linn Products Ltd"). Info is read only.
Url
Url contains the Manufacturer website address (example "http://www.linn.co.uk"). Url is read only.
ImageUri
Manufacturer Action
The Manufacturer action returns all four Manufacturer attributes.
Model
There are four Model attributes; Name, Info, Url and ImageUri.
Name
Name contains the Model name (example: "Majik DS"). Name is read only.
Info
Info contains more Model information (example "Linn Hi-Fi component"). Info is read only.
Url
Url contains the Model website address (example "http://products.linn.co.uk/MajikDS"). Url is read only.
ImageUri
Model Action
The Model action returns all four Model attributes.
Product
There are five Product attributes; Room, Name, Info, Url and ImageUri. They are all text strings.
Room
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 : Name}. Products which are Linked always share the same Room name. Room is set to Main Room by default.
Name
This is the Product name. The Upnp Friendly Name is derived by combining Room and Name in the format {Room : Name}. By default the Name is the same as the Model.
Info
Info contains more Product information (example "Linn Hi-Fi component"). Info is read only.
Url
Url is read only.
ImageUri
ImageUri is read only.
Product Action
The Product action returns all five Product attributes.
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.
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 Control =
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.
SourceCount
SourceCount returns the number of sources that exist in the Product (ie the source list size). SourceCount is read only.
Source Specific Parameters
Each source has four fundamental parameters, SourceSystemName, SourceName, SourceVisible and SourceType.
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.
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.
API Reference
Product Service Description (XML)
Migration Guide
Upnp Action Name Changes
None.
Obsolete Functions
The following actions, which relate to configuration, have been removed from the Product service:
Network Attribute Actions
- SetName
- SetRoom
Source Control Actions
- SetStartupSourceIndex
- StartupSourceIndex
- SetStartupSourceIndexByName
- SetStartupSourceEnabled
- StartupSourceEnabled
Source Specific Actions
- SetSourceVisible
- SetSourceName
- SourceAttributes
