OpenHome - User contributions [en]

OhMediaDevelopers

2015-02-17T13:10:15Z

Davidd: /* Network Services */

= Network Services =
ohMedia defines the following network services:
* [[Av:Developer:ProductService | Product]]. The core of a renderer and the only mandatory service. The state of this service allows control points to infer which other services are present on a device. In more complex installations it allows devices to mapped into a multi-room hi-fi system
* [[Av:Developer:PlaylistService | Playlist]]. An ordered list of tracks to be played.
* [[Av:Developer:RadioService | Radio]]. Browse and select from a list of favourite internet radio, podcast and listen again presets.
* [[Av:Developer:InfoService | Info]]. Report information about currently playing track.
* [[Av:Developer:TimeService | Time]]. Report information about progress through a track.
* [[Av:Developer:VolumeService | Volume]]. Control volume on a renderer or a connected pre-amp.
* [[Av:Developer:SenderService | Sender]]. Indicate presence and state of a Songcast sender.
* [[Av:Developer:ReceiverService | Receiver]]. Control a Songcast receiver.
* [[Av:Developer:CredentialsService | Credentials]]. Securely manage login details for external services supported by a device.
* NetworkMonitor. Measures network performance.
* [[Av:Developer:PlaylistManagerService | PlaylistManager]]. Included in media servers. Allows playlists to be shared between renderers and saved for future reuse.

= UPnP =
All ohMedia products publish and/or consume network services using UPnP. This is enabled by [[OhNet | ohNet]] - a cross-platform UPnP stack suitable for use in control points and devices. ohNet is open source, liberally licensed and intended for use in external products.

= Songcast =
Songcast enables synchronised playing of audio from an unbounded number of ohMedia renderers. Audio can be sent from an ohMedia renderer or from a desktop computer using the Songcast application.

The [https://github.com/openhome/ohSongcast ohSongcast] github repo provides a cross-platform C++ library offering much of the code needed to write a songcast sender.
The Songcast protocols are also documented:
* [[Av:Developer:Songcast:Ohm | OHM/OHU protocol specification]]
* [[Av:Developer:Songcast:Ohz | OHZ protocol specification]]

= Topology =
ohMedia models a home as a number of hi-fi systems, which are located in rooms.

A hi-fi system is modelled as a hierarchical tree of products, where a product is defined as a single physical box that is located in a room, has a unique name within the room, has at least one output and any number of inputs.

A product is modelled through the [[Av:Developer:ProductService | Product]] service specification.

When a control point wants to construct a model of a user's home they use the Topology algorithm:
* discover all the products in the home that have a Product service
* group the discovered products based on the room they are in
* create a hierarchical tree structure by matching source names to product names *
* discover source functionality based on source type
* discover additional functionality based on product attributes
Example implementations of the Topology algorithm are available in C# and C++ from the [https://github.com/openhome/ohTopology ohTopology] github repo.

A detailed description of the ohTopology software can be found [[Av:Developer:ohTopologyDescription | here]].

= Streaming Services =
Both Linn's DS and [[OhMediaPlayer | ohMediaPlayer]] include reference implementations for the following streaming services:
* [[TidalStreamingService | Tidal]]

OhMediaDevelopers

2015-02-17T13:09:18Z

Davidd: /* Network Services */

= Network Services =
ohMedia defines the following network services:
* [[Av:Developer:ProductService | Product]]. The core of a renderer and the only mandatory service. The state of this service allows control points to infer which other services are present on a device. In more complex installations it allows devices to mapped into a multi-room hi-fi system
* [[Av:Developer:PlaylistService | Playlist]]. An ordered list of tracks to be played.
* [[Av:Developer:RadioService | Radio]]. Browse and select from a list of favourite internet radio, podcast and listen again presets.
* [[Av:Developer:InfoService | Info]]. Report information about currently playing track.
* [[Av:Developer:TimeService | Time]]. Report information about progress through a track.
* [[Av:Developer:VolumeService | Volume]]. Control volume on a renderer or a connected pre-amp.
* [[Av:Developer:SenderService | Sender]]. Indicate presence and state of a Songcast sender.
* [[Av:Developer:ReceiverService | Receiver]]. Control a Songcast receiver.
* [[Av:Developer:CredentialsService | Credentials]]. Securely manage login details for external services supported by a device.
* [[Av:Developer:NetworkMonitorService | NetworkMonitor]]. Measures network performance.
* [[Av:Developer:PlaylistManagerService | PlaylistManager]]. Included in media servers. Allows playlists to be shared between renderers and saved for future reuse.

= UPnP =
All ohMedia products publish and/or consume network services using UPnP. This is enabled by [[OhNet | ohNet]] - a cross-platform UPnP stack suitable for use in control points and devices. ohNet is open source, liberally licensed and intended for use in external products.

= Songcast =
Songcast enables synchronised playing of audio from an unbounded number of ohMedia renderers. Audio can be sent from an ohMedia renderer or from a desktop computer using the Songcast application.

The [https://github.com/openhome/ohSongcast ohSongcast] github repo provides a cross-platform C++ library offering much of the code needed to write a songcast sender.
The Songcast protocols are also documented:
* [[Av:Developer:Songcast:Ohm | OHM/OHU protocol specification]]
* [[Av:Developer:Songcast:Ohz | OHZ protocol specification]]

= Topology =
ohMedia models a home as a number of hi-fi systems, which are located in rooms.

A hi-fi system is modelled as a hierarchical tree of products, where a product is defined as a single physical box that is located in a room, has a unique name within the room, has at least one output and any number of inputs.

A product is modelled through the [[Av:Developer:ProductService | Product]] service specification.

When a control point wants to construct a model of a user's home they use the Topology algorithm:
* discover all the products in the home that have a Product service
* group the discovered products based on the room they are in
* create a hierarchical tree structure by matching source names to product names *
* discover source functionality based on source type
* discover additional functionality based on product attributes
Example implementations of the Topology algorithm are available in C# and C++ from the [https://github.com/openhome/ohTopology ohTopology] github repo.

A detailed description of the ohTopology software can be found [[Av:Developer:ohTopologyDescription | here]].

= Streaming Services =
Both Linn's DS and [[OhMediaPlayer | ohMediaPlayer]] include reference implementations for the following streaming services:
* [[TidalStreamingService | Tidal]]

Av:Developer:CredentialsService

2015-01-09T11:31:09Z

Davidd: /* ReLogin */

= Overview =

The Credentials provides access to username, password and current status of all remote services that require unique logins.
 If a device's [[Developer:ProductService|Product]] service reports an attribute 'Credentials', then that device is guaranteed to bear the Credentials service.

= State Variables =
== Ids ==
Space separated list of identifiers for services whose credentials can be set.
 Set on startup; does not change at runtime.

== PublicKey ==
RSA public key that must be used to encrypt any/all passwords.
 When encrypting ensure PKCS1 OAEP padding is used.
 May be blank on startup; will not vary once set. With the exception of the <tt>Ids</tt> state variable, the rest of the service cannot usefully be used before this is set.

== SequenceNumber ==
Increases whenever any aspect of state for any user of credentials listed in <tt>Ids</tt> changes. The client is responsible for polling each Id they are interested in to determine what has changed.

= Actions =
== Set ==
Set the username and password for a given service. The password must be encrypted using the RSA public key in the <tt>PublicKey</tt> state variable.
 Calling this action automatically enables the service.
 Note that some processing may happen asynchronously. If any of username, password or enabled states are changed for the service, <tt>SequenceNumber</tt> will automatically change.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.

== Clear ==
Remove both username and password for a given service.
 Note that some processing may happen asynchronously. If any of username, password or enabled states are changed for the service, <tt>SequenceNumber</tt> will automatically change.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.

== SetEnabled ==
Set or clear the enabled state of a service. Disabling a service temporarily prevents its use by a device but allows the device to retain the username/password for later use (if the service is re-enabled by calling <tt>SetEnabled()</tt> again).
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.

== Get ==
Retrieve username, password, status and enabled state for a service.
 Username, password and enabled will only change in response to invocations of the Credentials service. The password is encrypted so is not suitable for user display. Clients can infer whether a password has been set by checking whether the value returned has non-zero length.
 Status may change in response to runtime events. e.g. If an account expires, the status may change to include the error returned by the remote service provider. Status is only set for error cases - a blank status indicates that a service is functioning correctly. The exact format of status content varies between services.
 Data contains any other service-specific information. The format of content varies between services.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.

== Login ==
Read a token indicating that a registered user has logged in to a remote service. This allows control points to access data that is specific to a certain user account without requiring access to the (sensitive) password for that account. The data returned may vary between credential-consuming services; the control point is responsible for knowing how to interpret it.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.
 Returns a 801 fault code if the login was attempted but failed.

== ReLogin ==
Refresh an existing token returned from <tt>Login()</tt>. This should only be called after the remote service has indicated that the current token has expired and is no longer valid.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.
 Returns a 801 fault code if a new login was attempted but failed.

== GetIds ==
Read the value of the <tt>Ids</tt> state variable.

== GetPublicKey ==
Read the value of the <tt>PublicKey</tt> state variable.

== GetSequenceNumber ==
Read the value of the <tt>SequenceNumber</tt> state variable.

= Technical Details =
<code>
Domain : av.openhome.org
Name : Credentials
Version : 1
</code>

== Service Description (XML) ==
<syntaxhighlight lang="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>Set</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>UserName</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Password</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Binary</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Clear</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetEnabled</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Enabled</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Get</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>UserName</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Password</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_Binary</relatedStateVariable>
</argument>
<argument>
<name>Enabled</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
<argument>
<name>Status</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Data</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Login</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReLogin</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>CurrentToken</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>NewToken</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetIds</name>
<argumentList>
<argument>
<name>Ids</name>
<direction>out</direction>
<relatedStateVariable>Ids</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetPublicKey</name>
<argumentList>
<argument>
<name>PublicKey</name>
<direction>out</direction>
<relatedStateVariable>PublicKey</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetSequenceNumber</name>
<argumentList>
<argument>
<name>SequenceNumber</name>
<direction>out</direction>
<relatedStateVariable>SequenceNumber</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>Ids</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PublicKey</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>SequenceNumber</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_String</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_Binary</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_Bool</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

Av:Developer:CredentialsService

2014-12-03T17:04:21Z

Davidd: /* PublicKey */

= Overview =

The Credentials provides access to username, password and current status of all remote services that require unique logins.
 If a device's [[Developer:ProductService|Product]] service reports an attribute 'Credentials', then that device is guaranteed to bear the Credentials service.

= State Variables =
== Ids ==
Space separated list of identifiers for services whose credentials can be set.
 Set on startup; does not change at runtime.

== PublicKey ==
RSA public key that must be used to encrypt any/all passwords.
 When encrypting ensure PKCS1 OAEP padding is used.
 May be blank on startup; will not vary once set. The rest of the service cannot usefully be used before this is set.

== SequenceNumber ==
Increases whenever any aspect of state for any user of credentials listed in <tt>Ids</tt> changes. The client is responsible for polling each Id they are interested in to determine what has changed.

= Actions =
== Set ==
Set the username and password for a given service. The password must be encrypted using the RSA public key in the <tt>PublicKey</tt> state variable.
 Calling this action automatically enables the service.
 Note that some processing may happen asynchronously. If any of username, password or enabled states are changed for the service, <tt>SequenceNumber</tt> will automatically change.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.

== Clear ==
Remove both username and password for a given service.
 Note that some processing may happen asynchronously. If any of username, password or enabled states are changed for the service, <tt>SequenceNumber</tt> will automatically change.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.

== SetEnabled ==
Set or clear the enabled state of a service. Disabling a service temporarily prevents its use by a device but allows the device to retain the username/password for later use (if the service is re-enabled by calling <tt>SetEnabled()</tt> again).
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.

== Get ==
Retrieve username, password, status and enabled state for a service.
 Username, password and enabled will only change in response to invocations of the Credentials service. The password is encrypted so is not suitable for user display. Clients can infer whether a password has been set by checking whether the value returned has non-zero length.
 Status may change in response to runtime events. e.g. If an account expires, the status may change to include the error returned by the remote service provider. Status is only set for error cases - a blank status indicates that a service is functioning correctly. The exact format of status content varies between services.
 Data contains any other service-specific information. The format of content varies between services.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.

== Login ==
Read a token indicating that a registered user has logged in to a remote service. This allows control points to access data that is specific to a certain user account without requiring access to the (sensitive) password for that account. The data returned may vary between credential-consuming services; the control point is responsible for knowing how to interpret it.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.
 Returns a 801 fault code if the login was attempted but failed.

== ReLogin ==
Refresh an existing token returned from <tt>Login()</tt>. This should only be called after teh remote service has indicated that the current token has expired and is no longer valid.
 Returns a 800 fault code if the <tt>Id</tt> argument is invalid.
 Returns a 801 fault code if a new login was attempted but failed.

== GetIds ==
Read the value of the <tt>Ids</tt> state variable.

== GetPublicKey ==
Read the value of the <tt>PublicKey</tt> state variable.

== GetSequenceNumber ==
Read the value of the <tt>SequenceNumber</tt> state variable.

= Technical Details =
<code>
Domain : av.openhome.org
Name : Credentials
Version : 1
</code>

== Service Description (XML) ==
<syntaxhighlight lang="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>Set</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>UserName</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Password</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Clear</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetEnabled</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Enabled</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Get</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>UserName</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Password</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Enabled</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
<argument>
<name>Status</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Data</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Login</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReLogin</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>CurrentToken</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>NewToken</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetIds</name>
<argumentList>
<argument>
<name>Ids</name>
<direction>out</direction>
<relatedStateVariable>Ids</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetPublicKey</name>
<argumentList>
<argument>
<name>PublicKey</name>
<direction>out</direction>
<relatedStateVariable>PublicKey</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetSequenceNumber</name>
<argumentList>
<argument>
<name>SequenceNumber</name>
<direction>out</direction>
<relatedStateVariable>SequenceNumber</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>Ids</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PublicKey</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>SequenceNumber</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_String</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_Bool</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

Av:Developer:ProductService

2014-06-16T12:24:35Z

Davidd: /* SourceXml */

= 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 <tt>Product</tt> service. Presence of various other services can be inferred from the sources and attributes this reports.

= State Variables =
== Sources ==
=== SourceCount ===
The number of available sources. Must be greater than 0. Does not vary at run-time.

=== SourceIndex ===
The index of the currently active source. This is zero-based so will be in the range <tt>[0..SourceCount-1]</tt>
=== SourceXml ===
Returns a summary of all sources in the form

<syntaxhighlight lang="xml">
<SourceList>
<Source>
<Name>[user name for source]</Name>
<Type>[Type of the source. Read-only. See below for supported types]</Type>
<Visible>[Boolean. Whether control points should display source]</Visible>
</sourcetag>
</SourceList>
</syntaxhighlight>

Supported values for source Type are,

- Playlist - the av.openhome.org:Playlist:1 service must be available
- Radio - the av.openhome.org:Radio:1 service must be available
- Receiver - the av.openhome.org:Receiver:1 service must be available
- UpnpAv - the upnp.org:MediaRenderer:1 device must be available
- NetAux - Specifies 3rd party, non OpenHome controllable, network protocols such as AirPlay
- Analog - Specifies an analog external input
- Digital - Specifies a digital external input
- Hdmi - Specifies a HDMI external input

== 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 must be available
- Time – the av.openhome.org:Time:1 service must be available
- Volume – the av.openhome.org:Volume:1 service must be available
- Sender - the av.openhome.org:Sender:1 service must be available
- App:Config=[link] – web UI for device configuration must be available at the url [link]

=== ManufacturerImageUri ===
Uri for manufacturer’s logo. Does not vary at run-time.
=== ManufacturerInfo ===
Manufacturer information. Does not vary at run-time.
=== ManufacturerName ===
Manufacturer name. Does not vary at run-time.
=== ManufacturerUrl ===
URL for manufacturer web site. Does not vary at run-time.
=== ModelImageUri ===
Uri for model’s icon. Does not vary at run-time.
=== ModelInfo ===
Model information. Does not vary at run-time.
=== ModelName ===
Model name. Does not vary at run-time.
=== ModelUrl ===
URL for model web site. Does not vary at run-time.
=== ProductImageUri ===
Uri for product image. Does not vary at run-time.

=== ProductInfo ===
Product information. Does not vary at run-time.
=== ProductName ===
User-visible product name. By default this is set to <tt>ModelName</tt>.
 Note that the UPnP friendly name is derived by combining this with Room name in the form <tt>Room : Name</tt>
=== 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 <tt>ProductRoom</tt> name.

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

== Standby ==
=== Standby ===
The standby state of a product (true => standby enabled)
 Behaviour when <tt>Standby</tt> is enabled is implementation defined. Devices can choose whether to remain network-controllable. If a device is still network-controllable, invoking the <tt>Play</tt> action on any source must disable <tt>Standby</tt>.

= 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.
=== Source ===
Given the index of a source, query the values of its name, system name, type and visibility.
=== SetSourceIndex ===
Set the currently active source. The value specified is zero-based and used to index into the source list returned by the <tt>SourceXml</tt> action / state variable.
=== SetSourceIndexByName ===
Set the currently active source. The value specified is matched against the <tt>Name</tt> attributes from the <tt>SourceXml</tt> action / state variable.
 Note that this action is deprecated.
=== SourceXml ===
Query the value of the <tt>SourceXml</tt> state variable.
=== SourceXmlChangeCount ===
Query how often the <tt>SourceXml</tt> state variable has been updated. This action can be polled by clients that don’t support eventing. Whenever the value returned increases, the <tt>SourceXml</tt> has been updated so should be queried again.

== Network Presentation ==
=== Attributes ===
Return the value of the <tt>Attributes</tt> state variable.
=== Manufacturer ===
Return the values of the <tt>ManufacturerName</tt>, <tt>ManufacturerInfo</tt>, <tt>ManufacturerUrl</tt>, <tt>ManufacturerImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Model ===
Return the values of the <tt>ModelName</tt>, <tt>ModelInfo</tt>, <tt>ModelUrl</tt>, <tt>ModelImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Product ===
Return the values of the <tt>ProductRoom</tt>, <tt>ProductName</tt>, <tt>ProductInfo</tt>, <tt>ProductUrl</tt>, <tt>ProductImageUri</tt> state variables.

== Standby ==
=== Standby ===
Return the value of the <tt>Standby</tt> state variable.
=== SetStandby ===
Set the value of the <tt>Standby</tt> state variable.
The SetStandby action provides a means of setting the current standby state of the product.

= Product Service Description (XML) =
<syntaxhighlight lang="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>
</syntaxhighlight>

Av:Developer:ProductService

2014-06-16T12:16:53Z

Davidd: /* SourceCount */

= 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 <tt>Product</tt> service. Presence of various other services can be inferred from the sources and attributes this reports.

= State Variables =
== Sources ==
=== SourceCount ===
The number of available sources. Must be greater than 0. Does not vary at run-time.

=== SourceIndex ===
The index of the currently active source. This is zero-based so will be in the range <tt>[0..SourceCount-1]</tt>
=== SourceXml ===
Returns a summary of all sources in the form

<syntaxhighlight lang="xml">
<SourceList>
<Source>
<Name>[user name for source]</Name>
<Type>[Type of the source. Read-only. See below for supported types]</Type>
<Visible>[Boolean. Whether control points should display source]</Visible>
</sourcetag>
</SourceList>
</syntaxhighlight>

Supported values for source Type are,

- Playlist - the av.openhome.org:Playlist:1 service must be available
- Radio - the av.openhome.org:Radio:1 service must be available
- Receiver - the av.openhome.org:Receiver:1 service must be available
- UpnpAv - the upnp.org:MediaRenderer:1 device must be available
- NetAux - Specifies 3rd party, non UPnP controllable, network protocols such as AirPlay
- Analog - Specifies an analog external input
- Digital - Specifies a digital external input
- Hdmi - Specifies a HDMI external input

== 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 must be available
- Time – the av.openhome.org:Time:1 service must be available
- Volume – the av.openhome.org:Volume:1 service must be available
- Sender - the av.openhome.org:Sender:1 service must be available
- App:Config=[link] – web UI for device configuration must be available at the url [link]

=== ManufacturerImageUri ===
Uri for manufacturer’s logo. Does not vary at run-time.
=== ManufacturerInfo ===
Manufacturer information. Does not vary at run-time.
=== ManufacturerName ===
Manufacturer name. Does not vary at run-time.
=== ManufacturerUrl ===
URL for manufacturer web site. Does not vary at run-time.
=== ModelImageUri ===
Uri for model’s icon. Does not vary at run-time.
=== ModelInfo ===
Model information. Does not vary at run-time.
=== ModelName ===
Model name. Does not vary at run-time.
=== ModelUrl ===
URL for model web site. Does not vary at run-time.
=== ProductImageUri ===
Uri for product image. Does not vary at run-time.

=== ProductInfo ===
Product information. Does not vary at run-time.
=== ProductName ===
User-visible product name. By default this is set to <tt>ModelName</tt>.
 Note that the UPnP friendly name is derived by combining this with Room name in the form <tt>Room : Name</tt>
=== 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 <tt>ProductRoom</tt> name.

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

== Standby ==
=== Standby ===
The standby state of a product (true => standby enabled)
 Behaviour when <tt>Standby</tt> is enabled is implementation defined. Devices can choose whether to remain network-controllable. If a device is still network-controllable, invoking the <tt>Play</tt> action on any source must disable <tt>Standby</tt>.

= 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.
=== Source ===
Given the index of a source, query the values of its name, system name, type and visibility.
=== SetSourceIndex ===
Set the currently active source. The value specified is zero-based and used to index into the source list returned by the <tt>SourceXml</tt> action / state variable.
=== SetSourceIndexByName ===
Set the currently active source. The value specified is matched against the <tt>Name</tt> attributes from the <tt>SourceXml</tt> action / state variable.
 Note that this action is deprecated.
=== SourceXml ===
Query the value of the <tt>SourceXml</tt> state variable.
=== SourceXmlChangeCount ===
Query how often the <tt>SourceXml</tt> state variable has been updated. This action can be polled by clients that don’t support eventing. Whenever the value returned increases, the <tt>SourceXml</tt> has been updated so should be queried again.

== Network Presentation ==
=== Attributes ===
Return the value of the <tt>Attributes</tt> state variable.
=== Manufacturer ===
Return the values of the <tt>ManufacturerName</tt>, <tt>ManufacturerInfo</tt>, <tt>ManufacturerUrl</tt>, <tt>ManufacturerImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Model ===
Return the values of the <tt>ModelName</tt>, <tt>ModelInfo</tt>, <tt>ModelUrl</tt>, <tt>ModelImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Product ===
Return the values of the <tt>ProductRoom</tt>, <tt>ProductName</tt>, <tt>ProductInfo</tt>, <tt>ProductUrl</tt>, <tt>ProductImageUri</tt> state variables.

== Standby ==
=== Standby ===
Return the value of the <tt>Standby</tt> state variable.
=== SetStandby ===
Set the value of the <tt>Standby</tt> state variable.
The SetStandby action provides a means of setting the current standby state of the product.

= Product Service Description (XML) =
<syntaxhighlight lang="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>
</syntaxhighlight>

Av:Developer:ProductService

2014-06-16T12:16:01Z

Davidd: /* SourceXml */

= 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 <tt>Product</tt> service. Presence of various other services can be inferred from the sources and attributes this reports.

= State Variables =
== Sources ==
=== SourceCount ===
The number of available sources. Does not vary at run-time.
=== SourceIndex ===
The index of the currently active source. This is zero-based so will be in the range <tt>[0..SourceCount-1]</tt>
=== SourceXml ===
Returns a summary of all sources in the form

<syntaxhighlight lang="xml">
<SourceList>
<Source>
<Name>[user name for source]</Name>
<Type>[Type of the source. Read-only. See below for supported types]</Type>
<Visible>[Boolean. Whether control points should display source]</Visible>
</sourcetag>
</SourceList>
</syntaxhighlight>

Supported values for source Type are,

- Playlist - the av.openhome.org:Playlist:1 service must be available
- Radio - the av.openhome.org:Radio:1 service must be available
- Receiver - the av.openhome.org:Receiver:1 service must be available
- UpnpAv - the upnp.org:MediaRenderer:1 device must be available
- NetAux - Specifies 3rd party, non UPnP controllable, network protocols such as AirPlay
- Analog - Specifies an analog external input
- Digital - Specifies a digital external input
- Hdmi - Specifies a HDMI external input

== 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 must be available
- Time – the av.openhome.org:Time:1 service must be available
- Volume – the av.openhome.org:Volume:1 service must be available
- Sender - the av.openhome.org:Sender:1 service must be available
- App:Config=[link] – web UI for device configuration must be available at the url [link]

=== ManufacturerImageUri ===
Uri for manufacturer’s logo. Does not vary at run-time.
=== ManufacturerInfo ===
Manufacturer information. Does not vary at run-time.
=== ManufacturerName ===
Manufacturer name. Does not vary at run-time.
=== ManufacturerUrl ===
URL for manufacturer web site. Does not vary at run-time.
=== ModelImageUri ===
Uri for model’s icon. Does not vary at run-time.
=== ModelInfo ===
Model information. Does not vary at run-time.
=== ModelName ===
Model name. Does not vary at run-time.
=== ModelUrl ===
URL for model web site. Does not vary at run-time.
=== ProductImageUri ===
Uri for product image. Does not vary at run-time.

=== ProductInfo ===
Product information. Does not vary at run-time.
=== ProductName ===
User-visible product name. By default this is set to <tt>ModelName</tt>.
 Note that the UPnP friendly name is derived by combining this with Room name in the form <tt>Room : Name</tt>
=== 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 <tt>ProductRoom</tt> name.

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

== Standby ==
=== Standby ===
The standby state of a product (true => standby enabled)
 Behaviour when <tt>Standby</tt> is enabled is implementation defined. Devices can choose whether to remain network-controllable. If a device is still network-controllable, invoking the <tt>Play</tt> action on any source must disable <tt>Standby</tt>.

= 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.
=== Source ===
Given the index of a source, query the values of its name, system name, type and visibility.
=== SetSourceIndex ===
Set the currently active source. The value specified is zero-based and used to index into the source list returned by the <tt>SourceXml</tt> action / state variable.
=== SetSourceIndexByName ===
Set the currently active source. The value specified is matched against the <tt>Name</tt> attributes from the <tt>SourceXml</tt> action / state variable.
 Note that this action is deprecated.
=== SourceXml ===
Query the value of the <tt>SourceXml</tt> state variable.
=== SourceXmlChangeCount ===
Query how often the <tt>SourceXml</tt> state variable has been updated. This action can be polled by clients that don’t support eventing. Whenever the value returned increases, the <tt>SourceXml</tt> has been updated so should be queried again.

== Network Presentation ==
=== Attributes ===
Return the value of the <tt>Attributes</tt> state variable.
=== Manufacturer ===
Return the values of the <tt>ManufacturerName</tt>, <tt>ManufacturerInfo</tt>, <tt>ManufacturerUrl</tt>, <tt>ManufacturerImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Model ===
Return the values of the <tt>ModelName</tt>, <tt>ModelInfo</tt>, <tt>ModelUrl</tt>, <tt>ModelImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Product ===
Return the values of the <tt>ProductRoom</tt>, <tt>ProductName</tt>, <tt>ProductInfo</tt>, <tt>ProductUrl</tt>, <tt>ProductImageUri</tt> state variables.

== Standby ==
=== Standby ===
Return the value of the <tt>Standby</tt> state variable.
=== SetStandby ===
Set the value of the <tt>Standby</tt> state variable.
The SetStandby action provides a means of setting the current standby state of the product.

= Product Service Description (XML) =
<syntaxhighlight lang="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>
</syntaxhighlight>

Av:Developer:ProductService

2014-06-16T12:14:21Z

Davidd: /* SourceXml */

= 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 <tt>Product</tt> service. Presence of various other services can be inferred from the sources and attributes this reports.

= State Variables =
== Sources ==
=== SourceCount ===
The number of available sources. Does not vary at run-time.
=== SourceIndex ===
The index of the currently active source. This is zero-based so will be in the range <tt>[0..SourceCount-1]</tt>
=== SourceXml ===
Returns a summary of all sources in the form

<syntaxhighlight lang="xml">
<SourceList>
<Source>
<Name>[user name for source]</Name>
<Type>[Type of the source. Read-only. See below for supported types]</Type>
<Visible>[Boolean. Whether control points should display source]</Visible>
</sourcetag>
</SourceList>
</syntaxhighlight>

Supported values for source Type are,

- Playlist - the av.openhome.org:Playlist:1 service must be available
- Radio - the av.openhome.org:Radio:1 service must be available
- Receiver - the av.openhome.org:Receiver:1 service must be available
- UpnpAv - the upnp.org:AVTransport:1, upnp.org:RenderingControl:1, and upnp.org:ConnectionManager:1 services must be available
- NetAux - used for non UPnP network protocols such as AirPlay
- Analog - Specifies an analog external input
- Digital - Specifies a digital external input
- Hdmi - Specifies a HDMI external input

== 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 must be available
- Time – the av.openhome.org:Time:1 service must be available
- Volume – the av.openhome.org:Volume:1 service must be available
- Sender - the av.openhome.org:Sender:1 service must be available
- App:Config=[link] – web UI for device configuration must be available at the url [link]

=== ManufacturerImageUri ===
Uri for manufacturer’s logo. Does not vary at run-time.
=== ManufacturerInfo ===
Manufacturer information. Does not vary at run-time.
=== ManufacturerName ===
Manufacturer name. Does not vary at run-time.
=== ManufacturerUrl ===
URL for manufacturer web site. Does not vary at run-time.
=== ModelImageUri ===
Uri for model’s icon. Does not vary at run-time.
=== ModelInfo ===
Model information. Does not vary at run-time.
=== ModelName ===
Model name. Does not vary at run-time.
=== ModelUrl ===
URL for model web site. Does not vary at run-time.
=== ProductImageUri ===
Uri for product image. Does not vary at run-time.

=== ProductInfo ===
Product information. Does not vary at run-time.
=== ProductName ===
User-visible product name. By default this is set to <tt>ModelName</tt>.
 Note that the UPnP friendly name is derived by combining this with Room name in the form <tt>Room : Name</tt>
=== 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 <tt>ProductRoom</tt> name.

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

== Standby ==
=== Standby ===
The standby state of a product (true => standby enabled)
 Behaviour when <tt>Standby</tt> is enabled is implementation defined. Devices can choose whether to remain network-controllable. If a device is still network-controllable, invoking the <tt>Play</tt> action on any source must disable <tt>Standby</tt>.

= 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.
=== Source ===
Given the index of a source, query the values of its name, system name, type and visibility.
=== SetSourceIndex ===
Set the currently active source. The value specified is zero-based and used to index into the source list returned by the <tt>SourceXml</tt> action / state variable.
=== SetSourceIndexByName ===
Set the currently active source. The value specified is matched against the <tt>Name</tt> attributes from the <tt>SourceXml</tt> action / state variable.
 Note that this action is deprecated.
=== SourceXml ===
Query the value of the <tt>SourceXml</tt> state variable.
=== SourceXmlChangeCount ===
Query how often the <tt>SourceXml</tt> state variable has been updated. This action can be polled by clients that don’t support eventing. Whenever the value returned increases, the <tt>SourceXml</tt> has been updated so should be queried again.

== Network Presentation ==
=== Attributes ===
Return the value of the <tt>Attributes</tt> state variable.
=== Manufacturer ===
Return the values of the <tt>ManufacturerName</tt>, <tt>ManufacturerInfo</tt>, <tt>ManufacturerUrl</tt>, <tt>ManufacturerImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Model ===
Return the values of the <tt>ModelName</tt>, <tt>ModelInfo</tt>, <tt>ModelUrl</tt>, <tt>ModelImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Product ===
Return the values of the <tt>ProductRoom</tt>, <tt>ProductName</tt>, <tt>ProductInfo</tt>, <tt>ProductUrl</tt>, <tt>ProductImageUri</tt> state variables.

== Standby ==
=== Standby ===
Return the value of the <tt>Standby</tt> state variable.
=== SetStandby ===
Set the value of the <tt>Standby</tt> state variable.
The SetStandby action provides a means of setting the current standby state of the product.

= Product Service Description (XML) =
<syntaxhighlight lang="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>
</syntaxhighlight>

Av:Developer:ProductService

2014-06-16T12:13:33Z

Davidd: /* SourceXml */

= 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 <tt>Product</tt> service. Presence of various other services can be inferred from the sources and attributes this reports.

= State Variables =
== Sources ==
=== SourceCount ===
The number of available sources. Does not vary at run-time.
=== SourceIndex ===
The index of the currently active source. This is zero-based so will be in the range <tt>[0..SourceCount-1]</tt>
=== SourceXml ===
Returns a summary of all sources in the form

<syntaxhighlight lang="xml">
<SourceList>
<Source>
<Name>[user name for source]</Name>
<Type>[Type of the source. Read-only. See below for supported types]</Type>
<Visible>[Boolean. Whether control points should display source]</Visible>
</sourcetag>
</SourceList>
</syntaxhighlight>

Supported values for source Type are,

- Playlist - the av.openhome.org:Playlist:1 service must be available
- Radio - the av.openhome.org:Radio:1 service must be available
- Receiver - the av.openhome.org:Receiver:1 service must be available
- UpnpAv - the upnp.org:AVTransport:1, upnp.org:RenderingControl:1, and upnp.org:ConnectionManager:1 services must be available
* <tt>NetAux</tt> - used for non UPnP network protocols such as AirPlay
* <tt>Analog</tt> - no control. Specifies an analog external input
* <tt>Digital</tt> - no control. Specifies a digital external input
* <tt>Hdmi</tt> - no control. Specifies a HDMI external input

== 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 must be available
- Time – the av.openhome.org:Time:1 service must be available
- Volume – the av.openhome.org:Volume:1 service must be available
- Sender - the av.openhome.org:Sender:1 service must be available
- App:Config=[link] – web UI for device configuration must be available at the url [link]

=== ManufacturerImageUri ===
Uri for manufacturer’s logo. Does not vary at run-time.
=== ManufacturerInfo ===
Manufacturer information. Does not vary at run-time.
=== ManufacturerName ===
Manufacturer name. Does not vary at run-time.
=== ManufacturerUrl ===
URL for manufacturer web site. Does not vary at run-time.
=== ModelImageUri ===
Uri for model’s icon. Does not vary at run-time.
=== ModelInfo ===
Model information. Does not vary at run-time.
=== ModelName ===
Model name. Does not vary at run-time.
=== ModelUrl ===
URL for model web site. Does not vary at run-time.
=== ProductImageUri ===
Uri for product image. Does not vary at run-time.

=== ProductInfo ===
Product information. Does not vary at run-time.
=== ProductName ===
User-visible product name. By default this is set to <tt>ModelName</tt>.
 Note that the UPnP friendly name is derived by combining this with Room name in the form <tt>Room : Name</tt>
=== 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 <tt>ProductRoom</tt> name.

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

== Standby ==
=== Standby ===
The standby state of a product (true => standby enabled)
 Behaviour when <tt>Standby</tt> is enabled is implementation defined. Devices can choose whether to remain network-controllable. If a device is still network-controllable, invoking the <tt>Play</tt> action on any source must disable <tt>Standby</tt>.

= 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.
=== Source ===
Given the index of a source, query the values of its name, system name, type and visibility.
=== SetSourceIndex ===
Set the currently active source. The value specified is zero-based and used to index into the source list returned by the <tt>SourceXml</tt> action / state variable.
=== SetSourceIndexByName ===
Set the currently active source. The value specified is matched against the <tt>Name</tt> attributes from the <tt>SourceXml</tt> action / state variable.
 Note that this action is deprecated.
=== SourceXml ===
Query the value of the <tt>SourceXml</tt> state variable.
=== SourceXmlChangeCount ===
Query how often the <tt>SourceXml</tt> state variable has been updated. This action can be polled by clients that don’t support eventing. Whenever the value returned increases, the <tt>SourceXml</tt> has been updated so should be queried again.

== Network Presentation ==
=== Attributes ===
Return the value of the <tt>Attributes</tt> state variable.
=== Manufacturer ===
Return the values of the <tt>ManufacturerName</tt>, <tt>ManufacturerInfo</tt>, <tt>ManufacturerUrl</tt>, <tt>ManufacturerImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Model ===
Return the values of the <tt>ModelName</tt>, <tt>ModelInfo</tt>, <tt>ModelUrl</tt>, <tt>ModelImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Product ===
Return the values of the <tt>ProductRoom</tt>, <tt>ProductName</tt>, <tt>ProductInfo</tt>, <tt>ProductUrl</tt>, <tt>ProductImageUri</tt> state variables.

== Standby ==
=== Standby ===
Return the value of the <tt>Standby</tt> state variable.
=== SetStandby ===
Set the value of the <tt>Standby</tt> state variable.
The SetStandby action provides a means of setting the current standby state of the product.

= Product Service Description (XML) =
<syntaxhighlight lang="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>
</syntaxhighlight>

Av:Developer:ProductService

2014-06-16T12:10:45Z

Davidd: /* SourceXml */

= 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 <tt>Product</tt> service. Presence of various other services can be inferred from the sources and attributes this reports.

= State Variables =
== Sources ==
=== SourceCount ===
The number of available sources. Does not vary at run-time.
=== SourceIndex ===
The index of the currently active source. This is zero-based so will be in the range <tt>[0..SourceCount-1]</tt>
=== SourceXml ===
Returns a summary of all sources in the form

<syntaxhighlight lang="xml">
<SourceList>
<Source>
<Name>[user name for source]</Name>
<Type>[Type of the source. Read-only. See below for supported types]</Type>
<Visible>[Boolean. Whether control points should display source]</Visible>
</sourcetag>
</SourceList>
</syntaxhighlight>

Supported values for source Type are,

* <tt>Playlist</tt> - the av.openhome.org:Playlist:1 service must be present
* <tt>Radio</tt> - controlled via the Radio service
* <tt>Receiver</tt> - controlled via the Receiver service
* <tt>UpnpAv</tt> - controlled via the AVTransport service
* <tt>NetAux</tt> - used for non UPnP network protocols such as AirPlay
* <tt>Analog</tt> - no control. Specifies an analog external input
* <tt>Digital</tt> - no control. Specifies a digital external input
* <tt>Hdmi</tt> - no control. Specifies a HDMI external input

== 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 must be available
- Time – the av.openhome.org:Time:1 service must be available
- Volume – the av.openhome.org:Volume:1 service must be available
- Sender - the av.openhome.org:Sender:1 service must be available
- App:Config=[link] – web UI for device configuration must be available at the url [link]

=== ManufacturerImageUri ===
Uri for manufacturer’s logo. Does not vary at run-time.
=== ManufacturerInfo ===
Manufacturer information. Does not vary at run-time.
=== ManufacturerName ===
Manufacturer name. Does not vary at run-time.
=== ManufacturerUrl ===
URL for manufacturer web site. Does not vary at run-time.
=== ModelImageUri ===
Uri for model’s icon. Does not vary at run-time.
=== ModelInfo ===
Model information. Does not vary at run-time.
=== ModelName ===
Model name. Does not vary at run-time.
=== ModelUrl ===
URL for model web site. Does not vary at run-time.
=== ProductImageUri ===
Uri for product image. Does not vary at run-time.

=== ProductInfo ===
Product information. Does not vary at run-time.
=== ProductName ===
User-visible product name. By default this is set to <tt>ModelName</tt>.
 Note that the UPnP friendly name is derived by combining this with Room name in the form <tt>Room : Name</tt>
=== 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 <tt>ProductRoom</tt> name.

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

== Standby ==
=== Standby ===
The standby state of a product (true => standby enabled)
 Behaviour when <tt>Standby</tt> is enabled is implementation defined. Devices can choose whether to remain network-controllable. If a device is still network-controllable, invoking the <tt>Play</tt> action on any source must disable <tt>Standby</tt>.

= 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.
=== Source ===
Given the index of a source, query the values of its name, system name, type and visibility.
=== SetSourceIndex ===
Set the currently active source. The value specified is zero-based and used to index into the source list returned by the <tt>SourceXml</tt> action / state variable.
=== SetSourceIndexByName ===
Set the currently active source. The value specified is matched against the <tt>Name</tt> attributes from the <tt>SourceXml</tt> action / state variable.
 Note that this action is deprecated.
=== SourceXml ===
Query the value of the <tt>SourceXml</tt> state variable.
=== SourceXmlChangeCount ===
Query how often the <tt>SourceXml</tt> state variable has been updated. This action can be polled by clients that don’t support eventing. Whenever the value returned increases, the <tt>SourceXml</tt> has been updated so should be queried again.

== Network Presentation ==
=== Attributes ===
Return the value of the <tt>Attributes</tt> state variable.
=== Manufacturer ===
Return the values of the <tt>ManufacturerName</tt>, <tt>ManufacturerInfo</tt>, <tt>ManufacturerUrl</tt>, <tt>ManufacturerImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Model ===
Return the values of the <tt>ModelName</tt>, <tt>ModelInfo</tt>, <tt>ModelUrl</tt>, <tt>ModelImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Product ===
Return the values of the <tt>ProductRoom</tt>, <tt>ProductName</tt>, <tt>ProductInfo</tt>, <tt>ProductUrl</tt>, <tt>ProductImageUri</tt> state variables.

== Standby ==
=== Standby ===
Return the value of the <tt>Standby</tt> state variable.
=== SetStandby ===
Set the value of the <tt>Standby</tt> state variable.
The SetStandby action provides a means of setting the current standby state of the product.

= Product Service Description (XML) =
<syntaxhighlight lang="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>
</syntaxhighlight>

Av:Developer:ProductService

2014-06-16T12:09:45Z

Davidd: /* Attributes */

= 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 <tt>Product</tt> service. Presence of various other services can be inferred from the sources and attributes this reports.

= State Variables =
== Sources ==
=== SourceCount ===
The number of available sources. Does not vary at run-time.
=== SourceIndex ===
The index of the currently active source. This is zero-based so will be in the range <tt>[0..SourceCount-1]</tt>
=== SourceXml ===
Returns a summary of all sources in the form

<syntaxhighlight lang="xml">
<SourceList>
<Source>
<Name>[user name for source]</Name>
<Type>[Type of the source. Read-only. See below for supported types]</Type>
<Visible>[Boolean. Whether control points should display source]</Visible>
</sourcetag>
</SourceList>
</syntaxhighlight>

Supported source types are,

* <tt>Playlist</tt> - controlled via the Playlist service
* <tt>Radio</tt> - controlled via the Radio service
* <tt>Receiver</tt> - controlled via the Receiver service
* <tt>UpnpAv</tt> - controlled via the AVTransport service
* <tt>NetAux</tt> - used for non UPnP network protocols such as AirPlay
* <tt>Analog</tt> - no control. Specifies an analog external input
* <tt>Digital</tt> - no control. Specifies a digital external input
* <tt>Hdmi</tt> - no control. Specifies a HDMI external input

== 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 must be available
- Time – the av.openhome.org:Time:1 service must be available
- Volume – the av.openhome.org:Volume:1 service must be available
- Sender - the av.openhome.org:Sender:1 service must be available
- App:Config=[link] – web UI for device configuration must be available at the url [link]

=== ManufacturerImageUri ===
Uri for manufacturer’s logo. Does not vary at run-time.
=== ManufacturerInfo ===
Manufacturer information. Does not vary at run-time.
=== ManufacturerName ===
Manufacturer name. Does not vary at run-time.
=== ManufacturerUrl ===
URL for manufacturer web site. Does not vary at run-time.
=== ModelImageUri ===
Uri for model’s icon. Does not vary at run-time.
=== ModelInfo ===
Model information. Does not vary at run-time.
=== ModelName ===
Model name. Does not vary at run-time.
=== ModelUrl ===
URL for model web site. Does not vary at run-time.
=== ProductImageUri ===
Uri for product image. Does not vary at run-time.

=== ProductInfo ===
Product information. Does not vary at run-time.
=== ProductName ===
User-visible product name. By default this is set to <tt>ModelName</tt>.
 Note that the UPnP friendly name is derived by combining this with Room name in the form <tt>Room : Name</tt>
=== 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 <tt>ProductRoom</tt> name.

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

== Standby ==
=== Standby ===
The standby state of a product (true => standby enabled)
 Behaviour when <tt>Standby</tt> is enabled is implementation defined. Devices can choose whether to remain network-controllable. If a device is still network-controllable, invoking the <tt>Play</tt> action on any source must disable <tt>Standby</tt>.

= 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.
=== Source ===
Given the index of a source, query the values of its name, system name, type and visibility.
=== SetSourceIndex ===
Set the currently active source. The value specified is zero-based and used to index into the source list returned by the <tt>SourceXml</tt> action / state variable.
=== SetSourceIndexByName ===
Set the currently active source. The value specified is matched against the <tt>Name</tt> attributes from the <tt>SourceXml</tt> action / state variable.
 Note that this action is deprecated.
=== SourceXml ===
Query the value of the <tt>SourceXml</tt> state variable.
=== SourceXmlChangeCount ===
Query how often the <tt>SourceXml</tt> state variable has been updated. This action can be polled by clients that don’t support eventing. Whenever the value returned increases, the <tt>SourceXml</tt> has been updated so should be queried again.

== Network Presentation ==
=== Attributes ===
Return the value of the <tt>Attributes</tt> state variable.
=== Manufacturer ===
Return the values of the <tt>ManufacturerName</tt>, <tt>ManufacturerInfo</tt>, <tt>ManufacturerUrl</tt>, <tt>ManufacturerImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Model ===
Return the values of the <tt>ModelName</tt>, <tt>ModelInfo</tt>, <tt>ModelUrl</tt>, <tt>ModelImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Product ===
Return the values of the <tt>ProductRoom</tt>, <tt>ProductName</tt>, <tt>ProductInfo</tt>, <tt>ProductUrl</tt>, <tt>ProductImageUri</tt> state variables.

== Standby ==
=== Standby ===
Return the value of the <tt>Standby</tt> state variable.
=== SetStandby ===
Set the value of the <tt>Standby</tt> state variable.
The SetStandby action provides a means of setting the current standby state of the product.

= Product Service Description (XML) =
<syntaxhighlight lang="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>
</syntaxhighlight>

Av:Developer:ProductService

2014-06-16T11:20:59Z

Davidd: /* SourceXml */

= 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 <tt>Product</tt> service. Presence of various other services can be inferred from the sources and attributes this reports.

= State Variables =
== Sources ==
=== SourceCount ===
The number of available sources. Does not vary at run-time.
=== SourceIndex ===
The index of the currently active source. This is zero-based so will be in the range <tt>[0..SourceCount-1]</tt>
=== SourceXml ===
Returns a summary of all sources in the form

<syntaxhighlight lang="xml">
<SourceList>
<Source>
<Name>[user name for source]</Name>
<Type>[Type of the source. Read-only. See below for supported types]</Type>
<Visible>[Boolean. Whether control points should display source]</Visible>
</sourcetag>
</SourceList>
</syntaxhighlight>

Supported source types are,

* <tt>Playlist</tt> - controlled via the Playlist service
* <tt>Radio</tt> - controlled via the Radio service
* <tt>Receiver</tt> - controlled via the Receiver service
* <tt>UpnpAv</tt> - controlled via the AVTransport service
* <tt>NetAux</tt> - used for non UPnP network protocols such as AirPlay
* <tt>Analog</tt> - no control. Specifies an analog external input
* <tt>Digital</tt> - no control. Specifies a digital external input
* <tt>Hdmi</tt> - no control. Specifies a HDMI external input

== 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. Does not vary at run-time.
=== ManufacturerInfo ===
Manufacturer information. Does not vary at run-time.
=== ManufacturerName ===
Manufacturer name. Does not vary at run-time.
=== ManufacturerUrl ===
URL for manufacturer web site. Does not vary at run-time.
=== ModelImageUri ===
Uri for model’s icon. Does not vary at run-time.
=== ModelInfo ===
Model information. Does not vary at run-time.
=== ModelName ===
Model name. Does not vary at run-time.
=== ModelUrl ===
URL for model web site. Does not vary at run-time.
=== ProductImageUri ===
Uri for product image. Does not vary at run-time.

=== ProductInfo ===
Product information. Does not vary at run-time.
=== ProductName ===
User-visible product name. By default this is set to <tt>ModelName</tt>.
 Note that the UPnP friendly name is derived by combining this with Room name in the form <tt>Room : Name</tt>
=== 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 <tt>ProductRoom</tt> name.

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

== Standby ==
=== Standby ===
The standby state of a product (true => standby enabled)
 Behaviour when <tt>Standby</tt> is enabled is implementation defined. Devices can choose whether to remain network-controllable. If a device is still network-controllable, invoking the <tt>Play</tt> action on any source must disable <tt>Standby</tt>.

= 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.
=== Source ===
Given the index of a source, query the values of its name, system name, type and visibility.
=== SetSourceIndex ===
Set the currently active source. The value specified is zero-based and used to index into the source list returned by the <tt>SourceXml</tt> action / state variable.
=== SetSourceIndexByName ===
Set the currently active source. The value specified is matched against the <tt>Name</tt> attributes from the <tt>SourceXml</tt> action / state variable.
 Note that this action is deprecated.
=== SourceXml ===
Query the value of the <tt>SourceXml</tt> state variable.
=== SourceXmlChangeCount ===
Query how often the <tt>SourceXml</tt> state variable has been updated. This action can be polled by clients that don’t support eventing. Whenever the value returned increases, the <tt>SourceXml</tt> has been updated so should be queried again.

== Network Presentation ==
=== Attributes ===
Return the value of the <tt>Attributes</tt> state variable.
=== Manufacturer ===
Return the values of the <tt>ManufacturerName</tt>, <tt>ManufacturerInfo</tt>, <tt>ManufacturerUrl</tt>, <tt>ManufacturerImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Model ===
Return the values of the <tt>ModelName</tt>, <tt>ModelInfo</tt>, <tt>ModelUrl</tt>, <tt>ModelImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Product ===
Return the values of the <tt>ProductRoom</tt>, <tt>ProductName</tt>, <tt>ProductInfo</tt>, <tt>ProductUrl</tt>, <tt>ProductImageUri</tt> state variables.

== Standby ==
=== Standby ===
Return the value of the <tt>Standby</tt> state variable.
=== SetStandby ===
Set the value of the <tt>Standby</tt> state variable.
The SetStandby action provides a means of setting the current standby state of the product.

= Product Service Description (XML) =
<syntaxhighlight lang="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>
</syntaxhighlight>

Av:Developer:ProductService

2014-06-16T11:19:14Z

Davidd: /* SourceXml */

= 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 <tt>Product</tt> service. Presence of various other services can be inferred from the sources and attributes this reports.

= State Variables =
== Sources ==
=== SourceCount ===
The number of available sources. Does not vary at run-time.
=== SourceIndex ===
The index of the currently active source. This is zero-based so will be in the range <tt>[0..SourceCount-1]</tt>
=== SourceXml ===
Returns a summary of all sources in the form

<syntaxhighlight lang="xml">
<SourceList>
<Source>
<Name>[user name for source]</Name>
<Type>[Type of the source. Read-only. See below for supported types]</Type>
<Visible>[Boolean. Whether control points should display source]</Visible>
</sourcetag>
</SourceList>
</syntaxhighlight>

Supported source types are,

* Playlist - controlled via the Playlist service
* Radio - controlled via the Radio service
* Receiver - controlled via the Receiver service
* UpnpAv - controlled via the AVTransport service
* NetAux - used for non UPnP network protocols such as AirPlay
* Analog - no control. Specifies an analog external input
* Digital - no control. Specifies a digital external input
* Hdmi - no control. Specifies a HDMI external input

== 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. Does not vary at run-time.
=== ManufacturerInfo ===
Manufacturer information. Does not vary at run-time.
=== ManufacturerName ===
Manufacturer name. Does not vary at run-time.
=== ManufacturerUrl ===
URL for manufacturer web site. Does not vary at run-time.
=== ModelImageUri ===
Uri for model’s icon. Does not vary at run-time.
=== ModelInfo ===
Model information. Does not vary at run-time.
=== ModelName ===
Model name. Does not vary at run-time.
=== ModelUrl ===
URL for model web site. Does not vary at run-time.
=== ProductImageUri ===
Uri for product image. Does not vary at run-time.

=== ProductInfo ===
Product information. Does not vary at run-time.
=== ProductName ===
User-visible product name. By default this is set to <tt>ModelName</tt>.
 Note that the UPnP friendly name is derived by combining this with Room name in the form <tt>Room : Name</tt>
=== 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 <tt>ProductRoom</tt> name.

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

== Standby ==
=== Standby ===
The standby state of a product (true => standby enabled)
 Behaviour when <tt>Standby</tt> is enabled is implementation defined. Devices can choose whether to remain network-controllable. If a device is still network-controllable, invoking the <tt>Play</tt> action on any source must disable <tt>Standby</tt>.

= 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.
=== Source ===
Given the index of a source, query the values of its name, system name, type and visibility.
=== SetSourceIndex ===
Set the currently active source. The value specified is zero-based and used to index into the source list returned by the <tt>SourceXml</tt> action / state variable.
=== SetSourceIndexByName ===
Set the currently active source. The value specified is matched against the <tt>Name</tt> attributes from the <tt>SourceXml</tt> action / state variable.
 Note that this action is deprecated.
=== SourceXml ===
Query the value of the <tt>SourceXml</tt> state variable.
=== SourceXmlChangeCount ===
Query how often the <tt>SourceXml</tt> state variable has been updated. This action can be polled by clients that don’t support eventing. Whenever the value returned increases, the <tt>SourceXml</tt> has been updated so should be queried again.

== Network Presentation ==
=== Attributes ===
Return the value of the <tt>Attributes</tt> state variable.
=== Manufacturer ===
Return the values of the <tt>ManufacturerName</tt>, <tt>ManufacturerInfo</tt>, <tt>ManufacturerUrl</tt>, <tt>ManufacturerImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Model ===
Return the values of the <tt>ModelName</tt>, <tt>ModelInfo</tt>, <tt>ModelUrl</tt>, <tt>ModelImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Product ===
Return the values of the <tt>ProductRoom</tt>, <tt>ProductName</tt>, <tt>ProductInfo</tt>, <tt>ProductUrl</tt>, <tt>ProductImageUri</tt> state variables.

== Standby ==
=== Standby ===
Return the value of the <tt>Standby</tt> state variable.
=== SetStandby ===
Set the value of the <tt>Standby</tt> state variable.
The SetStandby action provides a means of setting the current standby state of the product.

= Product Service Description (XML) =
<syntaxhighlight lang="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>
</syntaxhighlight>

Av:Developer:ProductService

2014-06-16T11:19:07Z

Davidd: /* SourceXml */

= 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 <tt>Product</tt> service. Presence of various other services can be inferred from the sources and attributes this reports.

= State Variables =
== Sources ==
=== SourceCount ===
The number of available sources. Does not vary at run-time.
=== SourceIndex ===
The index of the currently active source. This is zero-based so will be in the range <tt>[0..SourceCount-1]</tt>
=== SourceXml ===
Returns a summary of all sources in the form

<syntaxhighlight lang="xml">
<SourceList>
<Source>
<Name>[user name for source]</Name>
<Type>[Type of the source. Read-only. See below for supported types]</Type>
<Visible>[Boolean. Whether control points should display source]</Visible>
</sourcetag>
</SourceList>
</syntaxhighlight>

Supported source types are,

* Playlist - controlled via the Playlist service
* Radio - controlled via the Radio service
* Receiver - controlled via the Receiver service
* UpnpAv - controlled via the AVTransport service
* NetAux - used for non UPnP network protocols such as AirPlay
* Analog - no control. Specifies an analog external input
* Digital - no control. Specifies a digital external input
* Hdmi - no control. Specifies a HDMI external input

== 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. Does not vary at run-time.
=== ManufacturerInfo ===
Manufacturer information. Does not vary at run-time.
=== ManufacturerName ===
Manufacturer name. Does not vary at run-time.
=== ManufacturerUrl ===
URL for manufacturer web site. Does not vary at run-time.
=== ModelImageUri ===
Uri for model’s icon. Does not vary at run-time.
=== ModelInfo ===
Model information. Does not vary at run-time.
=== ModelName ===
Model name. Does not vary at run-time.
=== ModelUrl ===
URL for model web site. Does not vary at run-time.
=== ProductImageUri ===
Uri for product image. Does not vary at run-time.

=== ProductInfo ===
Product information. Does not vary at run-time.
=== ProductName ===
User-visible product name. By default this is set to <tt>ModelName</tt>.
 Note that the UPnP friendly name is derived by combining this with Room name in the form <tt>Room : Name</tt>
=== 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 <tt>ProductRoom</tt> name.

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

== Standby ==
=== Standby ===
The standby state of a product (true => standby enabled)
 Behaviour when <tt>Standby</tt> is enabled is implementation defined. Devices can choose whether to remain network-controllable. If a device is still network-controllable, invoking the <tt>Play</tt> action on any source must disable <tt>Standby</tt>.

= 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.
=== Source ===
Given the index of a source, query the values of its name, system name, type and visibility.
=== SetSourceIndex ===
Set the currently active source. The value specified is zero-based and used to index into the source list returned by the <tt>SourceXml</tt> action / state variable.
=== SetSourceIndexByName ===
Set the currently active source. The value specified is matched against the <tt>Name</tt> attributes from the <tt>SourceXml</tt> action / state variable.
 Note that this action is deprecated.
=== SourceXml ===
Query the value of the <tt>SourceXml</tt> state variable.
=== SourceXmlChangeCount ===
Query how often the <tt>SourceXml</tt> state variable has been updated. This action can be polled by clients that don’t support eventing. Whenever the value returned increases, the <tt>SourceXml</tt> has been updated so should be queried again.

== Network Presentation ==
=== Attributes ===
Return the value of the <tt>Attributes</tt> state variable.
=== Manufacturer ===
Return the values of the <tt>ManufacturerName</tt>, <tt>ManufacturerInfo</tt>, <tt>ManufacturerUrl</tt>, <tt>ManufacturerImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Model ===
Return the values of the <tt>ModelName</tt>, <tt>ModelInfo</tt>, <tt>ModelUrl</tt>, <tt>ModelImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Product ===
Return the values of the <tt>ProductRoom</tt>, <tt>ProductName</tt>, <tt>ProductInfo</tt>, <tt>ProductUrl</tt>, <tt>ProductImageUri</tt> state variables.

== Standby ==
=== Standby ===
Return the value of the <tt>Standby</tt> state variable.
=== SetStandby ===
Set the value of the <tt>Standby</tt> state variable.
The SetStandby action provides a means of setting the current standby state of the product.

= Product Service Description (XML) =
<syntaxhighlight lang="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>
</syntaxhighlight>

Av:Developer:ProductService

2014-06-16T11:10:41Z

Davidd: /* SourceXml */

= 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 <tt>Product</tt> service. Presence of various other services can be inferred from the sources and attributes this reports.

= State Variables =
== Sources ==
=== SourceCount ===
The number of available sources. Does not vary at run-time.
=== SourceIndex ===
The index of the currently active source. This is zero-based so will be in the range <tt>[0..SourceCount-1]</tt>
=== SourceXml ===
Returns a summary of all sources in the form

<syntaxhighlight lang="xml">
<SourceList>
<Source>
<Name>[user name for source]</Name>
<Type>[Type of the source. Read-only. See below for supported types]</Type>
<Visible>[Boolean. Whether control points should display source]</Visible>
</sourcetag>
</SourceList>
</syntaxhighlight>

== 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. Does not vary at run-time.
=== ManufacturerInfo ===
Manufacturer information. Does not vary at run-time.
=== ManufacturerName ===
Manufacturer name. Does not vary at run-time.
=== ManufacturerUrl ===
URL for manufacturer web site. Does not vary at run-time.
=== ModelImageUri ===
Uri for model’s icon. Does not vary at run-time.
=== ModelInfo ===
Model information. Does not vary at run-time.
=== ModelName ===
Model name. Does not vary at run-time.
=== ModelUrl ===
URL for model web site. Does not vary at run-time.
=== ProductImageUri ===
Uri for product image. Does not vary at run-time.

=== ProductInfo ===
Product information. Does not vary at run-time.
=== ProductName ===
User-visible product name. By default this is set to <tt>ModelName</tt>.
 Note that the UPnP friendly name is derived by combining this with Room name in the form <tt>Room : Name</tt>
=== 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 <tt>ProductRoom</tt> name.

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

== Standby ==
=== Standby ===
The standby state of a product (true => standby enabled)
 Behaviour when <tt>Standby</tt> is enabled is implementation defined. Devices can choose whether to remain network-controllable. If a device is still network-controllable, invoking the <tt>Play</tt> action on any source must disable <tt>Standby</tt>.

= 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.
=== Source ===
Given the index of a source, query the values of its name, system name, type and visibility.
=== SetSourceIndex ===
Set the currently active source. The value specified is zero-based and used to index into the source list returned by the <tt>SourceXml</tt> action / state variable.
=== SetSourceIndexByName ===
Set the currently active source. The value specified is matched against the <tt>Name</tt> attributes from the <tt>SourceXml</tt> action / state variable.
 Note that this action is deprecated.
=== SourceXml ===
Query the value of the <tt>SourceXml</tt> state variable.
=== SourceXmlChangeCount ===
Query how often the <tt>SourceXml</tt> state variable has been updated. This action can be polled by clients that don’t support eventing. Whenever the value returned increases, the <tt>SourceXml</tt> has been updated so should be queried again.

== Network Presentation ==
=== Attributes ===
Return the value of the <tt>Attributes</tt> state variable.
=== Manufacturer ===
Return the values of the <tt>ManufacturerName</tt>, <tt>ManufacturerInfo</tt>, <tt>ManufacturerUrl</tt>, <tt>ManufacturerImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Model ===
Return the values of the <tt>ModelName</tt>, <tt>ModelInfo</tt>, <tt>ModelUrl</tt>, <tt>ModelImageUri</tt> state variables. All are read-only so the values returned will not vary at runtime.
=== Product ===
Return the values of the <tt>ProductRoom</tt>, <tt>ProductName</tt>, <tt>ProductInfo</tt>, <tt>ProductUrl</tt>, <tt>ProductImageUri</tt> state variables.

== Standby ==
=== Standby ===
Return the value of the <tt>Standby</tt> state variable.
=== SetStandby ===
Set the value of the <tt>Standby</tt> state variable.
The SetStandby action provides a means of setting the current standby state of the product.

= Product Service Description (XML) =
<syntaxhighlight lang="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>
</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-08-17T16:19:50Z

Davidd: /* PlaylistSetName */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks in an individual playlist. Each playlist and each track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id should contain the metadata for the track. Otherwise the udn should be empty and the metadata id should contain DidlLite describing the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

Likewise there are two ways to delete the tracks in a playlist. But you can only delete the playlists themselves individually.

== IdArray and TokenIdArray ==

The PlaylistManager service has two evented state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

Returns a list of artwork images a control point can associate with a playlist.

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadList ==

Given a list of playlist ids, report their associated Name, Description and ImageId in the following XML form:

<syntaxhighlight lang="xml">

<PlaylistList>
<Entry>
<Id></Id>
<Name></Name>
<Description></Description>
<ImageId></ImageId>
</Entry>
</PlaylistList>

</syntaxhighlight>

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistSetName ==

Sets the Name of the specified playlist.

== PlaylistSetDescription ==

Sets the Description of the specified playlist.

== PlaylistSetImageId ==

Sets the ImageId of the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id. To insert at the beginning of the list use the special playlist id of 0.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<Playlist>
<Track>
<Udn></Udn>
<Metadata></Metadata>
</Track>
</Playlist>

</syntaxhighlight>

== Insert ==

Insert a track after the specified track id. To insert at the beginning of the list use the special track id of 0.

== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadList</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>PlaylistList</name>
<direction>out</direction>
<relatedStateVariable>PlaylistList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistSetName</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistSetDescription</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistSetImageId</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistMove</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-08-17T16:19:16Z

Davidd: /* PlaylistUpdate */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks in an individual playlist. Each playlist and each track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id should contain the metadata for the track. Otherwise the udn should be empty and the metadata id should contain DidlLite describing the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

Likewise there are two ways to delete the tracks in a playlist. But you can only delete the playlists themselves individually.

== IdArray and TokenIdArray ==

The PlaylistManager service has two evented state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

Returns a list of artwork images a control point can associate with a playlist.

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadList ==

Given a list of playlist ids, report their associated Name, Description and ImageId in the following XML form:

<syntaxhighlight lang="xml">

<PlaylistList>
<Entry>
<Id></Id>
<Name></Name>
<Description></Description>
<ImageId></ImageId>
</Entry>
</PlaylistList>

</syntaxhighlight>

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistSetName ==

Sets the Name of the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id. To insert at the beginning of the list use the special playlist id of 0.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<Playlist>
<Track>
<Udn></Udn>
<Metadata></Metadata>
</Track>
</Playlist>

</syntaxhighlight>

== Insert ==

Insert a track after the specified track id. To insert at the beginning of the list use the special track id of 0.

== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadList</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>PlaylistList</name>
<direction>out</direction>
<relatedStateVariable>PlaylistList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistSetName</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistSetDescription</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistSetImageId</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistMove</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-08-17T16:18:46Z

Davidd: /* PlaylistManager Service Description (XML) */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks in an individual playlist. Each playlist and each track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id should contain the metadata for the track. Otherwise the udn should be empty and the metadata id should contain DidlLite describing the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

Likewise there are two ways to delete the tracks in a playlist. But you can only delete the playlists themselves individually.

== IdArray and TokenIdArray ==

The PlaylistManager service has two evented state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

Returns a list of artwork images a control point can associate with a playlist.

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadList ==

Given a list of playlist ids, report their associated Name, Description and ImageId in the following XML form:

<syntaxhighlight lang="xml">

<PlaylistList>
<Entry>
<Id></Id>
<Name></Name>
<Description></Description>
<ImageId></ImageId>
</Entry>
</PlaylistList>

</syntaxhighlight>

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==

Updates the Name, Description and ImageId for the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id. To insert at the beginning of the list use the special playlist id of 0.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<Playlist>
<Track>
<Udn></Udn>
<Metadata></Metadata>
</Track>
</Playlist>

</syntaxhighlight>

== Insert ==

Insert a track after the specified track id. To insert at the beginning of the list use the special track id of 0.

== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadList</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>PlaylistList</name>
<direction>out</direction>
<relatedStateVariable>PlaylistList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistSetName</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistSetDescription</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistSetImageId</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistMove</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-08-17T10:48:22Z

Davidd: /* PlaylistManager Service Description (XML) */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks in an individual playlist. Each playlist and each track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id should contain the metadata for the track. Otherwise the udn should be empty and the metadata id should contain DidlLite describing the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

Likewise there are two ways to delete the tracks in a playlist. But you can only delete the playlists themselves individually.

== IdArray and TokenIdArray ==

The PlaylistManager service has two evented state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

Returns a list of artwork images a control point can associate with a playlist.

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadList ==

Given a list of playlist ids, report their associated Name, Description and ImageId in the following XML form:

<syntaxhighlight lang="xml">

<PlaylistList>
<Entry>
<Id></Id>
<Name></Name>
<Description></Description>
<ImageId></ImageId>
</Entry>
</PlaylistList>

</syntaxhighlight>

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==

Updates the Name, Description and ImageId for the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id. To insert at the beginning of the list use the special playlist id of 0.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<Playlist>
<Track>
<Udn></Udn>
<Metadata></Metadata>
</Track>
</Playlist>

</syntaxhighlight>

== Insert ==

Insert a track after the specified track id. To insert at the beginning of the list use the special track id of 0.

== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadList</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>PlaylistList</name>
<direction>out</direction>
<relatedStateVariable>PlaylistList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistMove</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-08-17T10:45:59Z

Davidd: /* Architectural Overview */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks in an individual playlist. Each playlist and each track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id should contain the metadata for the track. Otherwise the udn should be empty and the metadata id should contain DidlLite describing the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

Likewise there are two ways to delete the tracks in a playlist. But you can only delete the playlists themselves individually.

== IdArray and TokenIdArray ==

The PlaylistManager service has two evented state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

Returns a list of artwork images a control point can associate with a playlist.

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadList ==

Given a list of playlist ids, report their associated Name, Description and ImageId in the following XML form:

<syntaxhighlight lang="xml">

<PlaylistList>
<Entry>
<Id></Id>
<Name></Name>
<Description></Description>
<ImageId></ImageId>
</Entry>
</PlaylistList>

</syntaxhighlight>

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==

Updates the Name, Description and ImageId for the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id. To insert at the beginning of the list use the special playlist id of 0.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<Playlist>
<Track>
<Udn></Udn>
<Metadata></Metadata>
</Track>
</Playlist>

</syntaxhighlight>

== Insert ==

Insert a track after the specified track id. To insert at the beginning of the list use the special track id of 0.

== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadList</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>PlaylistList</name>
<direction>out</direction>
<relatedStateVariable>PlaylistList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-08-17T10:44:26Z

Davidd: /* Architectural Overview */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks in an individual playlist. Each playlist and each track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata should contain the metadata for the track. Otherwise the udn should be empty and the metadata should contain DidlLite describing the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

Likewise there are two ways to delete the tracks in a playlist. But you can only delete the playlists themselves individually.

== IdArray and TokenIdArray ==

The PlaylistManager service has two evented state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

Returns a list of artwork images a control point can associate with a playlist.

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadList ==

Given a list of playlist ids, report their associated Name, Description and ImageId in the following XML form:

<syntaxhighlight lang="xml">

<PlaylistList>
<Entry>
<Id></Id>
<Name></Name>
<Description></Description>
<ImageId></ImageId>
</Entry>
</PlaylistList>

</syntaxhighlight>

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==

Updates the Name, Description and ImageId for the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id. To insert at the beginning of the list use the special playlist id of 0.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<Playlist>
<Track>
<Udn></Udn>
<Metadata></Metadata>
</Track>
</Playlist>

</syntaxhighlight>

== Insert ==

Insert a track after the specified track id. To insert at the beginning of the list use the special track id of 0.

== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadList</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>PlaylistList</name>
<direction>out</direction>
<relatedStateVariable>PlaylistList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-08-17T10:08:22Z

Davidd: /* PlaylistManager Service Description (XML) */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks in an individual playlist. Each playlist and each track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id should contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

Likewise there are two ways to delete the tracks in a playlist. But you can only delete the playlists themselves individually.

== IdArray and TokenIdArray ==

The PlaylistManager service has two evented state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

Returns a list of artwork images a control point can associate with a playlist.

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadList ==

Given a list of playlist ids, report their associated Name, Description and ImageId in the following XML form:

<syntaxhighlight lang="xml">

<PlaylistList>
<Entry>
<Id></Id>
<Name></Name>
<Description></Description>
<ImageId></ImageId>
</Entry>
</PlaylistList>

</syntaxhighlight>

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==

Updates the Name, Description and ImageId for the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id. To insert at the beginning of the list use the special playlist id of 0.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<Playlist>
<Track>
<Udn></Udn>
<Metadata></Metadata>
</Track>
</Playlist>

</syntaxhighlight>

== Insert ==

Insert a track after the specified track id. To insert at the beginning of the list use the special track id of 0.

== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadList</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>PlaylistList</name>
<direction>out</direction>
<relatedStateVariable>PlaylistList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-08-17T10:07:09Z

Davidd: /* PlaylistReadMetadata */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks in an individual playlist. Each playlist and each track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id should contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

Likewise there are two ways to delete the tracks in a playlist. But you can only delete the playlists themselves individually.

== IdArray and TokenIdArray ==

The PlaylistManager service has two evented state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

Returns a list of artwork images a control point can associate with a playlist.

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadList ==

Given a list of playlist ids, report their associated Name, Description and ImageId in the following XML form:

<syntaxhighlight lang="xml">

<PlaylistList>
<Entry>
<Id></Id>
<Name></Name>
<Description></Description>
<ImageId></ImageId>
</Entry>
</PlaylistList>

</syntaxhighlight>

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==

Updates the Name, Description and ImageId for the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id. To insert at the beginning of the list use the special playlist id of 0.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<Playlist>
<Track>
<Udn></Udn>
<Metadata></Metadata>
</Track>
</Playlist>

</syntaxhighlight>

== Insert ==

Insert a track after the specified track id. To insert at the beginning of the list use the special track id of 0.

== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-08-17T10:06:43Z

Davidd: /* PlaylistReadMetadata */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks in an individual playlist. Each playlist and each track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id should contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

Likewise there are two ways to delete the tracks in a playlist. But you can only delete the playlists themselves individually.

== IdArray and TokenIdArray ==

The PlaylistManager service has two evented state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

Returns a list of artwork images a control point can associate with a playlist.

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==

Given a list of playlist ids, report their associated Name, Description and ImageId in the following XML form:

<syntaxhighlight lang="xml">

<PlaylistList>
<Entry>
<Id></Id>
<Name></Name>
<Description></Description>
<ImageId></ImageId>
</Entry>
</PlaylistList>

</syntaxhighlight>

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==

Updates the Name, Description and ImageId for the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id. To insert at the beginning of the list use the special playlist id of 0.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<Playlist>
<Track>
<Udn></Udn>
<Metadata></Metadata>
</Track>
</Playlist>

</syntaxhighlight>

== Insert ==

Insert a track after the specified track id. To insert at the beginning of the list use the special track id of 0.

== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-08-17T10:06:12Z

Davidd: /* PlaylistReadMetadata */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks in an individual playlist. Each playlist and each track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id should contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

Likewise there are two ways to delete the tracks in a playlist. But you can only delete the playlists themselves individually.

== IdArray and TokenIdArray ==

The PlaylistManager service has two evented state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

Returns a list of artwork images a control point can associate with a playlist.

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==

Given a list of playlist ids, report their associated name, description and imageId in the following XML form:

<syntaxhighlight lang="xml">

<PlaylistList>
<Entry>
<Id></Id>
<Name></Name>
<Description></Description>
<ImageId></ImageId>
</Entry>
</PlaylistList>

</syntaxhighlight>

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==

Updates the Name, Description and ImageId for the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id. To insert at the beginning of the list use the special playlist id of 0.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<Playlist>
<Track>
<Udn></Udn>
<Metadata></Metadata>
</Track>
</Playlist>

</syntaxhighlight>

== Insert ==

Insert a track after the specified track id. To insert at the beginning of the list use the special track id of 0.

== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:22:06Z

Davidd: /* PlaylistInsert */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

Returns a list of artwork images a control point can associate with a playlist.

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==

Given a playlist id, report its associated Metadata.

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==

Updates the Name, Description and ImageId for the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id. To insert at the beginning of the list use the special playlist id of 0.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<TrackList>
<Entry>
<Id></Id>
<Metadata></Metadata>
</Entry>
</TrackList>

</syntaxhighlight>

== Insert ==

Insert a track after the specified track id. To insert at the beginning of the list use the special track id of 0.

== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:21:47Z

Davidd: /* Insert */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

Returns a list of artwork images a control point can associate with a playlist.

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==

Given a playlist id, report its associated Metadata.

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==

Updates the Name, Description and ImageId for the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<TrackList>
<Entry>
<Id></Id>
<Metadata></Metadata>
</Entry>
</TrackList>

</syntaxhighlight>

== Insert ==

Insert a track after the specified track id. To insert at the beginning of the list use the special track id of 0.

== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:20:35Z

Davidd: /* ImagesXml */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

Returns a list of artwork images a control point can associate with a playlist.

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==

Given a playlist id, report its associated Metadata.

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==

Updates the Name, Description and ImageId for the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<TrackList>
<Entry>
<Id></Id>
<Metadata></Metadata>
</Entry>
</TrackList>

</syntaxhighlight>

== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:19:48Z

Davidd: /* PlaylistInsert */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==

Given a playlist id, report its associated Metadata.

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==

Updates the Name, Description and ImageId for the specified playlist.

== PlaylistInsert ==

Inserts an empty playlist with the specified Name, Description and ImageId after the specified playlist id.

== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<TrackList>
<Entry>
<Id></Id>
<Metadata></Metadata>
</Entry>
</TrackList>

</syntaxhighlight>

== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:19:04Z

Davidd: /* PlaylistUpdate */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==

Given a playlist id, report its associated Metadata.

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==

Updates the Name, Description and ImageId for the specified playlist.

== PlaylistInsert ==
== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<TrackList>
<Entry>
<Id></Id>
<Metadata></Metadata>
</Entry>
</TrackList>

</syntaxhighlight>

== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:16:29Z

Davidd: /* Metadata */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==

Returns the Metadata describing the PlaylistManager.

== ImagesXml ==

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==

Given a playlist id, report its associated Metadata.

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<TrackList>
<Entry>
<Id></Id>
<Metadata></Metadata>
</Entry>
</TrackList>

</syntaxhighlight>

== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:15:08Z

Davidd: /* PlaylistRead */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==

Given a playlist id, report its associated Metadata.

== PlaylistRead ==

Given a playlist id, report its associated Name, Description and ImageId.

== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<TrackList>
<Entry>
<Id></Id>
<Metadata></Metadata>
</Entry>
</TrackList>

</syntaxhighlight>

== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:14:39Z

Davidd: /* PlaylistReadMetadata */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==

Given a playlist id, report its associated Metadata.

== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<TrackList>
<Entry>
<Id></Id>
<Metadata></Metadata>
</Entry>
</TrackList>

</syntaxhighlight>

== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:13:39Z

Davidd: /* ReadList */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==
== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==

Given a playlist id and a space separated list of track Id's, report their associated Metadata in the following xml form:

<syntaxhighlight lang="xml">

<TrackList>
<Entry>
<Id></Id>
<Metadata></Metadata>
</Entry>
</TrackList>

</syntaxhighlight>

== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:13:00Z

Davidd: /* Read */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==
== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==

Given a playlist id and a track Id, report its associated Metadata.

== ReadList ==
== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:11:06Z

Davidd: /* ImagesXml */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==

<syntaxhighlight lang="xml">

<ImageList>
<Entry>
<Id></Id>
<Uri></Uri>
</Entry>
</ImageList>

</syntaxhighlight>

== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==
== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==
== ReadList ==
== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:10:07Z

Davidd: /* PlaylistsMax */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==
== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==
== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==

Report the maximum number of playlists in the playlists id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==
== ReadList ==
== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:09:42Z

Davidd: /* TracksMax */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==
== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==
== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==
== TracksMax ==

Report the maximum number of tracks in a playlist id array. This remains constant while a particular OpenHome device remains registerted on the network, but may vary between different models of OpenHome device from different manufacturers. A value of 0 indicates no limit.

== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==
== ReadList ==
== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:08:39Z

Davidd: /* PlaylistDeleteId */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==
== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==
== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==

Delete from the list of playlists the playlist with the specified Id.

== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==
== TracksMax ==
== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==
== ReadList ==
== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:08:17Z

Davidd: /* PlaylistDeleteAll */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==
== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==
== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==
== PlaylistDeleteAll ==

Clears all the playlists.

== PlaylistsMax ==
== TracksMax ==
== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==
== ReadList ==
== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:08:01Z

Davidd: /* DeleteAll */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==
== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==
== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==
== PlaylistDeleteAll ==
== PlaylistsMax ==
== TracksMax ==
== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==
== ReadList ==
== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

Clears the specified playlist.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:07:49Z

Davidd: /* DeleteId */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==
== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==
== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==
== PlaylistDeleteAll ==
== PlaylistsMax ==
== TracksMax ==
== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==
== ReadList ==
== Insert ==
== DeleteId ==

Delete from the specified playlist the track with the specified Id.

== DeleteAll ==

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:07:16Z

Davidd: /* PlaylistReadArray */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==
== PlaylistReadArray ==

Report the current id array for the specified playlist.

The IdArray is an ordered array of ids that represent each track in the playlist.

== PlaylistReadMetadata ==
== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==
== PlaylistDeleteAll ==
== PlaylistsMax ==
== TracksMax ==
== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==
== ReadList ==
== Insert ==
== DeleteId ==
== DeleteAll ==

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:05:32Z

Davidd: /* PlaylistArraysChanged */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==
== PlaylistReadArray ==
== PlaylistReadMetadata ==
== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==
== PlaylistDeleteAll ==
== PlaylistsMax ==
== TracksMax ==
== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==

Check to see if the id array or token array has changed since gathering the specified Token. This Token must have been previously collected from the PlaylistArrays action.

This mechanism is provided specifically for clients unable to partake in UPnP eventing.

== Read ==
== ReadList ==
== Insert ==
== DeleteId ==
== DeleteAll ==

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:04:59Z

Davidd: /* PlaylistArrays */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==
== PlaylistReadArray ==
== PlaylistReadMetadata ==
== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==
== PlaylistDeleteAll ==
== PlaylistsMax ==
== TracksMax ==
== PlaylistArrays ==

Report the current id array and token array.

The IdArray is an ordered array of ids that represent each playlist in the list of playlists.

This action also reports a Token, which can be used to quickly detect if the id array or token array has changed since it was last read (see PlaylistArraysChanged).

== PlaylistArraysChanged ==
== Read ==
== ReadList ==
== Insert ==
== DeleteId ==
== DeleteAll ==

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T10:02:31Z

Davidd: /* Actions */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

== Metadata ==
== ImagesXml ==
== PlaylistReadArray ==
== PlaylistReadMetadata ==
== PlaylistRead ==
== PlaylistUpdate ==
== PlaylistInsert ==
== PlaylistDeleteId ==
== PlaylistDeleteAll ==
== PlaylistsMax ==
== TracksMax ==
== PlaylistArrays ==
== PlaylistArraysChanged ==
== Read ==
== ReadList ==
== Insert ==
== DeleteId ==
== DeleteAll ==

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T09:57:22Z

Davidd: /* Architectural Overview */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Actions =

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T09:53:33Z

Davidd: /* Playlist IdArray */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

When you acquire the IdArray, through the action PlaylistReadArray, you immediately know the number and order of the ids in the playlist. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlist changes is inefficient and will give a poor user experience. In order to quickly display playlist updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlist. Changes to the order of ids in the playlist require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T09:50:59Z

Davidd: /* IdArray and TokenIdArray */

= Architectural Overview =

The PlaylistManager service provides the ability to create and maintain playlists.

The PlaylistManager service provides access to a list of playlists, which in turn, contain a list of tracks.

Using the PlaylistManager service you can read, insert and delete playlists as well as read, insert and delete tracks from an individual playlist. Each playlist and track within a playlist is given a unique id.

To insert a playlist, provide the id of the playlist you wish to insert 'after' and the associated metadata, (name, description and image id). An empty playlist is inserted into the correct position and the id of the new playlist is returned. To insert in the first position, insert after the special id of 0.

To insert a track, provide the id of the playlist and the id of the track you wish to insert 'after' and the associated udn and metadata id. The track is inserted and the id of the new track is returned. To insert in the first position. insert after the special id of 0. If the track originated from a media server the udn should contain the udn of the media server and the metadata id contain the id contained in the DidlLite of the track. Otherwise the udn should be empty and the metadata id contain DidlLite describing of the track.

There are two ways to read the list of playlists or the list of tracks in a playlist. The first reads a single entry and the second reads a list of entries.

There are two ways to delete the playlists or the the tracks in a playlist. The first deletes a single entry and the second deletes a list of entries.

== IdArray and TokenIdArray ==

The PlaylistManager service has two eventide state variable called IdArray and TokenArray. Both arrays are base64 encoded arrays of 32 bit, big endian unsigned integers. Each Id and Token represents a playlist in the list of playlists. An empty array indicates an empty list if playlists. A Change in Token for a playlist indicates that the playlist contents has changed.

Whether you acquire the IdArray and TokenArray via events or polling, you immediately know the number and order of the ids of the playlists, as well as whether an individual playlist has changed. What you don't necessarily know is the metadata for those ids.

As the metadata for a large number of playlists can easily be several megabytes of xml, blindly fetching all the metadata every time the playlists change is inefficient and will give a poor user experience. In order to quickly display playlists updates and ensure interoperability with other control points on the network, it is strongly recommended that you maintain the following two data structures:

* A copy of the latest IdArray and TokenArray
* A cache mapping id's to their associated metadata.

With this decoupled approach, you only need to fetch the metadata for the ids added to the playlists. Changes to the order of ids in the playlists require no action.

As a further enhancement, when an insert completes successfully, you know both the metadata (as you supplied it), and the new id (returned by the PlaylistManager on completion of the insert action). This information can be directly inserted into the cache, saving subsequent unnecessary retrieval.

== Playlist IdArray ==

The obtain a playlist's IdArray, provide the id of the playlist to the action PlaylistReadArray. The IdArray returned is a base64 encoded array of 32 bit, big endian unsigned integers. Each Id represents a track in the playlist. An empty IdArray indicates an empty playlist.

== Events ==

A short while (approx 300ms) after any change to the list of playlists, the PlaylistManager will event all subscribers the current IdArray and TokenArray. The eventing of these state variables is moderated to prevent excessive updates.

A short while (approx 300ms) after any changes to a playlist, the PlaylistManager will event all subscribers the current TokenArray. The eventing of this state variable is moderated to prevent excessive updates.

== Polling ==

For control points that can't subscribe to events, two additional actions are provided. The first, PlaylistArrays, reads the IdArray and TokenArray directly. This action also returns an ArraysToken, which should be saved and periodically passed to a second action, PlaylistArraysChanged, which reports whether or not your copy of IdArray and TokenArray are out of date. If they are, calling PlaylistArrays again will ensure you have up to date versions.

= Technical Details =
<code>
Domain : av.openhome.org
Name : PlaylistManager
Version : 1
</code>

== PlaylistManager Service Description (XML) ==
<syntaxhighlight lang="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>Metadata</name>
<argumentList>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>ImagesXml</name>
<argumentList>
<argument>
<name>ImagesXml</name>
<direction>out</direction>
<relatedStateVariable>ImagesXml</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>PlaylistReadArray</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Array</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistReadMetadata</name>
<argumentList>
<argument>
<name>IdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistRead</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>out</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>out</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>out</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistUpdate</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistInsert</name>
<argumentList>
<argument>
<name>AfterId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Name</name>
<direction>in</direction>
<relatedStateVariable>Name</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>Description</relatedStateVariable>
</argument>
<argument>
<name>ImageId</name>
<direction>in</direction>
<relatedStateVariable>ImageId</relatedStateVariable>
</argument>
<argument>
<name>NewId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteId</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistDeleteAll</name>
</action>
<action>
<name>PlaylistsMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>PlaylistsMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>TracksMax</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>TracksMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArrays</name>
<argumentList>
<argument>
<name>Token</name>
<direction>out</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
<argument>
<name>TokenArray</name>
<direction>out</direction>
<relatedStateVariable>TokenArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>PlaylistArraysChanged</name>
<argumentList>
<argument>
<name>Token</name>
<direction>in</direction>
<relatedStateVariable>ArraysToken</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>IdArrayChanged</relatedStateVariable>
</argument>
</argumentList>
</action>

<action>
<name>Read</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Metadata</name>
<direction>out</direction>
<relatedStateVariable>Metadata</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>TrackIdList</name>
<direction>in</direction>
<relatedStateVariable>IdList</relatedStateVariable>
</argument>
<argument>
<name>TrackList</name>
<direction>out</direction>
<relatedStateVariable>TrackList</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Insert</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>AfterTrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Udn</name>
<direction>in</direction>
<relatedStateVariable>Udn</relatedStateVariable>
</argument>
<argument>
<name>MetadataId</name>
<direction>in</direction>
<relatedStateVariable>MetadataId</relatedStateVariable>
</argument>
<argument>
<name>NewTrackId</name>
<direction>out</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteId</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>DeleteAll</name>
<argumentList>
<argument>
<name>TrackId</name>
<direction>in</direction>
<relatedStateVariable>Id</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>

<serviceStateTable>

<stateVariable sendEvents="yes">
<name>Metadata</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>ImagesXml</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TokenArray</name>
<dataType>bin.base64</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>PlaylistsMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>TracksMax</name>
<dataType>ui4</dataType>
</stateVariable>

<stateVariable sendEvents="no">
<name>PlaylistList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Id</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Name</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Description</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ImageId</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>TrackList</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>Udn</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>MetadataId</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>ArraysToken</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>IdArrayChanged</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

</syntaxhighlight>

Av:Developer:PlaylistManagerService

2011-07-27T09:43:51Z

Davidd: Created page with "= Architectural Overview = The PlaylistManager service provides the ability to create and maintain playlists. The PlaylistManager service provides access to a list of playlists..."