Simonc at 09:14, 17 August 2018

2018-08-17T09:14:44Z

← Older revision		Revision as of 09:14, 17 August 2018
Line 4:		Line 4:

	The Pins service provides access both device-specific and account-wide pins. Both classes of pin can be read from or invoked on a device. Device-specific pins can also be edited; account-wide pins may be editable via a device but should also have edit APIs in the service or location that provides general account support.		The Pins service provides access both device-specific and account-wide pins. Both classes of pin can be read from or invoked on a device. Device-specific pins can also be edited; account-wide pins may be editable via a device but should also have edit APIs in the service or location that provides general account support.
		+
		+	= Supported Content =
		+	Reference code contains support for the following [[Av:Developer:PinInvokers \| pinnable content]].

	= State Variables =		= State Variables =

Simonc: Created page with "= Overview = A pin is a set of instructions to switch source or play one or more tracks on a device. Some pins will have wholly predictable results (e.g. switch to Analog2, play..."

2018-08-17T09:10:11Z

Created page with "= Overview = A pin is a set of instructions to switch source or play one or more tracks on a device. Some pins will have wholly predictable results (e.g. switch to Analog2, play..."

New page

= Overview =

A pin is a set of instructions to switch source or play one or more tracks on a device. Some pins will have wholly predictable results (e.g. switch to Analog2, play named playlist); others may be more dynamic (e.g. play the latest podcast from a given feed or a curated playlist of the week from a streaming service).

The Pins service provides access both device-specific and account-wide pins. Both classes of pin can be read from or invoked on a device. Device-specific pins can also be edited; account-wide pins may be editable via a device but should also have edit APIs in the service or location that provides general account support.

= State Variables =
== DeviceMax ==
The maximum number of device-specific pins supported

== AccountMax ==
The maximum number of account-wide pins supported

== Modes ==
JSON array of strings identifying the different styles of pins supported

== CloudConnected ==
<tt>true</tt> if a connection is available to cloud-backed master copy of account pins (i.e. when account pins are editable); <tt>false</tt> otherwise.

== IdArray ==
JSON array of identifiers (unsigned integer) for all pins.
 Device pins are listed first, followed by Account pins. i.e. array will always have <tt>DeviceMax</tt> + <tt>AccountMax</tt> entries.
 Identifiers will normally be unique; <tt>0</tt> is a special case which signifies an empty pin.

= Actions =
== GetDeviceMax ==
Read the <tt>DeviceMax</tt> property.

== GetAccountMax ==
Read the <tt>AccountMax</tt> property.

== GetModes ==
Read the <tt>Modes</tt> property.

== GetCloudConnected ==
Read the <tt>CloudConnected</tt> property.

== GetIdArray ==
Read the <tt>IdArray</tt> property.

== ReadList ==
Input: JSON integer array, specifying ids of pins to be read.
 Output: JSON array of pins
<code>
[
{
"id": {unsigned integer, unique across device & account pins},
"mode": "where track(s) will be fetched from",
"type": "instructs the device how to interpret the uri below",
"uri": "absolute uri",
"title": "Short text, may be user-visible",
"description": "Longer text, may be user-visible",
"artworkUri": "absolute uri to image",
"shuffle": {boolean}
},
{ ... }
]
</code>

== InvokeIndex ==
Invoke the pin at the specified index in <tt>IdArray</tt>. This will stop anything that is currently playing and may clear any current playlist.

== InvokeId ==
Invoke the pin with the specified id. This will stop anything that is currently playing and may clear any current playlist.

== InvokeUri ==
Invoke a pin using data (mode, type, uri, shuffle) from a control point. Should be used by any control point that wants to determine which account to read pins from. (Note however that pins which themselves require cloud support to load cannot be loaded by the device - control points would have to load them directly into a playlist instead.) This will stop anything that is currently playing and may clear any current playlist.

== SetDevice ==
Set a device pin, specifying the mode, type, uri, title, description, artworkUri and shuffle plus index into the set of device pins.
 Any pin currently assigned at the specified index will be replaced.
 Any playing content is unaffected (i.e. invoking then replacing a pin leaves the old representation of the pin playing).
index must be in the range <tt>[0..DeviceMax)</tt>.
 Some errors are notified in response to this action. Success should only be assumed when an update is evented to IdArray showing a change in id at the specified index.

== SetAccount ==
Set an account pin, specifying the mode, type, uri, title, description, artworkUri and shuffle plus index into the set of device pins.
 Any pin currently assigned at the specified index will be replaced.
 Any playing content is unaffected (i.e. invoking then replacing a pin leaves the old representation of the pin playing).
index must be in the range <tt>[0..AccountMax)</tt>.
 Requests to update an account pin are proxied to a remote server so are likely to be slower and have greater chance of failure.
 Some errors are notified in response to this action. Success should only be assumed when an update is evented to <tt>IdArray</tt> showing a change in id at <tt>DeviceMax + index</tt>.

== Clear ==
Clear any content in the pin with the specified id.
 As with Set, changes to device pins are implemented locally; changes to account pins are proxied to a remote server.
 Some errors are notified in response to this action. Success should only be assumed when an update is evented to the sequence number for the specified id.

== Swap ==
Swap contents of the 2 pins at the specified indices.
 Pins can only be swapped within either device or account lists.

= Technical Details =
<code>
Domain : av.openhome.org
Name : Pins
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>GetDeviceMax</name>
<argumentList>
<argument>
<name>DeviceMax</name>
<direction>out</direction>
<relatedStateVariable>DeviceMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetAccountMax</name>
<argumentList>
<argument>
<name>AccountMax</name>
<direction>out</direction>
<relatedStateVariable>AccountMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetModes</name>
<argumentList>
<argument>
<name>Modes</name>
<direction>out</direction>
<relatedStateVariable>Modes</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetIdArray</name>
<argumentList>
<argument>
<name>IdArray</name>
<direction>out</direction>
<relatedStateVariable>IdArray</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>GetCloudConnected</name>
<argumentList>
<argument>
<name>CloudConnected</name>
<direction>out</direction>
<relatedStateVariable>CloudConnected</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>ReadList</name>
<argumentList>
<argument>
<name>Ids</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>List</name>
<direction>out</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>InvokeId</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>InvokeIndex</name>
<argumentList>
<argument>
<name>Index</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>InvokeUri</name>
<argumentList>
<argument>
<name>Mode</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Type</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Uri</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Shuffle</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetDevice</name>
<argumentList>
<argument>
<name>Index</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
<argument>
<name>Mode</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Type</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Uri</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Title</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>ArtworkUri</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Shuffle</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetAccount</name>
<argumentList>
<argument>
<name>Index</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
<argument>
<name>Mode</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Type</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Uri</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Title</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Description</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>ArtworkUri</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
</argument>
<argument>
<name>Shuffle</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Clear</name>
<argumentList>
<argument>
<name>Id</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Swap</name>
<argumentList>
<argument>
<name>Index1</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
<argument>
<name>Index2</name>
<direction>in</direction>
<relatedStateVariable>A_ARG_TYPE_Uint</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>DeviceMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>AccountMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Modes</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>IdArray</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>CloudConnected</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_String</name>
<dataType>string</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_Uint</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="no">
<name>A_ARG_TYPE_Bool</name>
<dataType>boolean</dataType>
</stateVariable>
</serviceStateTable>
</scpd>

Av:Developer:PinsService - Revision history

Simonc at 09:14, 17 August 2018

Simonc: Created page with "= Overview = A pin is a set of instructions to switch source or play one or more tracks on a device. Some pins will have wholly predictable results (e.g. switch to Analog2, play..."