From OpenHome

(Difference between revisions)
Jump to: navigation, search
(→Connecting)
(→Enabled)
 
(14 intermediate revisions not shown)
Line 1: Line 1:
-
= Architectural Overview =
+
= Overview =
 +
The Sender service indicates the presence of a Songcast sender and provides information concerning that sender.
-
The Sender service indicates the presence of an Openhome sender and provides information concerning that sender.
+
A Songcast sender broadcasts music on a network in a way that is playable by a Songcast [[Developer:ReceiverService|receiver]].
-
An Openhome sender broadcasts music on a network in a way that is playable by an Openhome [[Developer:ReceiverService|receiver]].
+
If a device's Product service reports an attribute source of type 'Sender', then that device is guaranteed to bear the Sender service.  Alternatively, Songcast senders can be discovered independently of the Product service by simply searching for devices bearing the Sender service.
-
Openhome senders should be discovered independently of the standard algorithm for discovering Openhome products and sources. An independent search should be made for devices bearing the Sender service.
+
= State Variables =
-
 
+
-
= Actions =
+
== Attributes ==
== Attributes ==
-
Reports a space separated list of attributes that identify additional functionality that can be found on the same device as this Sender.
+
Reserved for future use.
-
 
+
== Audio ==
-
Currently defined attributes are:
+
<tt>true</tt> if audio is currently available from this Sender; <tt>false</tt> otherwise.
-
 
+
-
* Info - this device reports on the current media using the Info service
+
-
* Time - this device reports on the current media using the Time service
+
-
 
+
-
== Audio ==  
+
-
Reports whether audio is currently present on this sender.
+
-
 
+
== Metadata ==
== Metadata ==
-
Provides a representation of this audio item in DIDL-Lite format.
+
Provides basic information about the sender in DIDL-Lite format.
 +
<syntaxhighlight lang="xml">
 +
<DIDL-Lite xmlns:dc="http://purl.org/dc/elements/1.1/"
 +
          xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/"
 +
          xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/">
 +
    <item id="0" restricted="True">
 +
        <dc:title>[sender_name]</dc:title>"
 +
        <res protocolInfo="ohz:*:*:[m|u]">ohz://239.255.255.250:51972/[device_udn]</res>
 +
        <upnp:albumArtURI>[full_uri]</upnp:albumArtURI>
 +
        <upnp:class>object.item.audioItem</upnp:class>
 +
    </item>
 +
</DIDL-Lite>
 +
</syntaxhighlight>
 +
Note that protocolInfo takes the form <tt>ohz:*:*:m</tt> or <tt>ohz:*:*:u</tt> depending on whether multicast or unicast mode is enabled
== PresentationUrl ==
== PresentationUrl ==
-
Reports the Url of a presentation page for further information concerning the sender, or for controlling the sender in some application-specific way.
+
Reports the url of a presentation page for further information concerning the sender, or for controlling the sender in some application-specific way.
 +
If the sender has no presentation page, <tt>PresentationUrl</tt> is empty.
 +
== Status ==
 +
Deprecated.  Use <tt>Status2</tt> instead.
-
If the sender has no presentation page, the PresentationUrl should be empty.
+
* Enabled - sender enabled by user configuration and not blocked
-
 
+
* Blocked - audio from another sender detected on the same channel (mis-configuration)
-
== Status ==
+
* Disabled - sender disabled by user configuration
 +
== Status2 ==
Reports the status of the sender (normally only for debugging purposes):
Reports the status of the sender (normally only for debugging purposes):
* Sending - currently sending audio over the network
* Sending - currently sending audio over the network
-
* Ready - ready to send audio but no listeners
+
* Ready - capable of sending audio but no listeners.  Use <tt>Audio</tt> to determine whether audio would be sent immediately a listener joins.
* Blocked - audio from another sender detected on the same channel (mis-configuration)
* Blocked - audio from another sender detected on the same channel (mis-configuration)
-
* Inactive - no audio source currently assigned to this sender
+
* Inactive - sender device is playing content which cannot be broadcast
* Disabled - sender disabled by user configuration
* Disabled - sender disabled by user configuration
 +
== Enabled ==
 +
<tt>true</tt> if the device bearing this service is capable of acting as a Songcast sender (i.e. Songcast sending is enabled and the sender is not blocked due to a multicast port clash); <tt>false</tt> otherwise.
-
= Technical Details =
+
= Actions =
 +
== Attributes ==
 +
Return the value of the <tt>Attributes</tt> state variable
 +
== Audio ==
 +
Return the value of the <tt>Audio</tt> state variable
 +
== Metadata ==
 +
Return the value of the <tt>Metadata</tt> state variable
 +
== PresentationUrl ==
 +
Return the value of the <tt>PresentationUrl</tt> state variable
 +
== Status ==
 +
Return the value of the <tt>Status</tt> state variable
 +
 
 +
= Sender Service Description (XML) =
<code>
<code>
     Domain  : av.openhome.org
     Domain  : av.openhome.org
     Name    : Sender
     Name    : Sender
-
     Version : 1
+
     Version : 2
</code>
</code>
-
[http://oss.linn.co.uk/trac/browser/Main/LibUpnpCil/Services/Openhome/Sender1.xml Sender Service Description (XML)]
 
-
 
-
== Connecting ==
 
-
 
-
In the openhome multicast protocol, receivers must be connected to senders in order to receive streaming audio.
 
-
 
-
In order to connect and disconnect senders from receivers, there are two conceptual approaches you could take.  You can either order a particular receiver to play a particular sender, or you can order a sender to start sending to one or more receivers.  From a user perspective, these are very different approaches, however from an implementation standpoint, both of these are equivalent and are carried out by invoking the SetSender action on the receiver service, passing the Uri and Metadata of the sender (which can be obtained from the sender service metadata state variable).  This will bring the receiver to a state where it is ready to listen to the sender, and can be started/stopped by invoking the Play and Stop actions.  The Play action will automatically switch source on the receiving DS if this source is not currently selected.
 
-
Both of these approaches, of course, first require maintaining an up-to-date list of senders and receivers from [[Developer#Topology|Topology]]:
+
<syntaxhighlight lang="xml">
 +
<?xml version="1.0"?>
 +
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
 +
  <specVersion>
 +
    <major>1</major>
 +
    <minor>0</minor>
 +
  </specVersion>
-
The receivers list is maintained by using [[Developer#Topology|Topology]] to watch sources being added/removed and checking whether the source has Type equal to "Receiver".
+
  <actionList>
 +
    <action>
 +
      <name>PresentationUrl</name>
 +
      <argumentList>
 +
        <argument>
 +
          <name>Value</name>
 +
          <direction>out</direction>
 +
          <relatedStateVariable>PresentationUrl</relatedStateVariable>
 +
        </argument>
 +
      </argumentList>
 +
    </action>
 +
    <action>
 +
      <name>Metadata</name>
 +
      <argumentList>
 +
        <argument>
 +
          <name>Value</name>
 +
          <direction>out</direction>
 +
          <relatedStateVariable>Metadata</relatedStateVariable>
 +
        </argument>
 +
      </argumentList>
 +
    </action>
 +
    <action>
 +
      <name>Audio</name>
 +
      <argumentList>
 +
        <argument>
 +
          <name>Value</name>
 +
          <direction>out</direction>
 +
          <relatedStateVariable>Audio</relatedStateVariable>
 +
        </argument>
 +
      </argumentList>
 +
    </action>
 +
    <action>
 +
      <name>Status</name>
 +
      <argumentList>
 +
        <argument>
 +
          <name>Value</name>
 +
          <direction>out</direction>
 +
          <relatedStateVariable>Status</relatedStateVariable>
 +
        </argument>
 +
      </argumentList>
 +
    </action>
 +
    <action>
 +
      <name>Status2</name>
 +
      <argumentList>
 +
        <argument>
 +
          <name>Value</name>
 +
          <direction>out</direction>
 +
          <relatedStateVariable>Status2</relatedStateVariable>
 +
        </argument>
 +
      </argumentList>
 +
    </action>
 +
    <action>
 +
      <name>Enabled</name>
 +
      <argumentList>
 +
        <argument>
 +
          <name>Value</name>
 +
          <direction>out</direction>
 +
          <relatedStateVariable>Enabled</relatedStateVariable>
 +
        </argument>
 +
      </argumentList>
 +
    </action>
 +
    <action>
 +
      <name>Attributes</name>
 +
      <argumentList>
 +
        <argument>
 +
          <name>Value</name>
 +
          <direction>out</direction>
 +
          <relatedStateVariable>Attributes</relatedStateVariable>
 +
        </argument>
 +
      </argumentList>
 +
    </action>
 +
  </actionList>
-
The senders list is maintained via SSDP discovery of any sender services which do not have a status of disabled.
+
  <serviceStateTable>
 +
    <stateVariable sendEvents="yes">
 +
      <name>PresentationUrl</name>
 +
      <dataType>string</dataType>
 +
    </stateVariable>
 +
    <stateVariable sendEvents="yes">
 +
      <name>Metadata</name>
 +
      <dataType>string</dataType>
 +
    </stateVariable>
 +
    <stateVariable sendEvents="yes">
 +
      <name>Audio</name>
 +
      <dataType>boolean</dataType>
 +
    </stateVariable>
 +
    <stateVariable sendEvents="yes">
 +
      <name>Status</name>
 +
      <dataType>string</dataType>
 +
      <allowedValueList>
 +
        <allowedValue>Enabled</allowedValue>
 +
        <allowedValue>Disabled</allowedValue>
 +
        <allowedValue>Blocked</allowedValue>
 +
      </allowedValueList>
 +
    </stateVariable>
 +
    <stateVariable sendEvents="yes">
 +
      <name>Status2</name>
 +
      <dataType>string</dataType>
 +
      <allowedValueList>
 +
        <allowedValue>Sending</allowedValue>
 +
        <allowedValue>Ready</allowedValue>
 +
        <allowedValue>Blocked</allowedValue>
 +
        <allowedValue>Inactive</allowedValue>
 +
        <allowedValue>Disabled</allowedValue>
 +
      </allowedValueList>
 +
    </stateVariable>
 +
    <stateVariable sendEvents="yes">
 +
      <name>Enabled</name>
 +
      <dataType>boolean</dataType>
 +
    </stateVariable>
 +
    <stateVariable sendEvents="yes">
 +
      <name>Attributes</name>
 +
      <dataType>string</dataType>
 +
    </stateVariable>
 +
  </serviceStateTable>
 +
</scpd>
 +
</syntaxhighlight>

Latest revision as of 10:30, 26 April 2017

Contents

Overview

The Sender service indicates the presence of a Songcast sender and provides information concerning that sender.

A Songcast sender broadcasts music on a network in a way that is playable by a Songcast receiver.

If a device's Product service reports an attribute source of type 'Sender', then that device is guaranteed to bear the Sender service. Alternatively, Songcast senders can be discovered independently of the Product service by simply searching for devices bearing the Sender service.

State Variables

Attributes

Reserved for future use.

Audio

true if audio is currently available from this Sender; false otherwise.

Metadata

Provides basic information about the sender in DIDL-Lite format. 

<DIDL-Lite xmlns:dc="http://purl.org/dc/elements/1.1/"
           xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/"
           xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/">
    <item id="0" restricted="True">
        <dc:title>[sender_name]</dc:title>"
        <res protocolInfo="ohz:*:*:[m|u]">ohz://239.255.255.250:51972/[device_udn]</res>
        <upnp:albumArtURI>[full_uri]</upnp:albumArtURI>
        <upnp:class>object.item.audioItem</upnp:class>
    </item>
</DIDL-Lite>

Note that protocolInfo takes the form ohz:*:*:m or ohz:*:*:u depending on whether multicast or unicast mode is enabled

PresentationUrl

Reports the url of a presentation page for further information concerning the sender, or for controlling the sender in some application-specific way. If the sender has no presentation page, PresentationUrl is empty.

Status

Deprecated. Use Status2 instead.

  • Enabled - sender enabled by user configuration and not blocked
  • Blocked - audio from another sender detected on the same channel (mis-configuration)
  • Disabled - sender disabled by user configuration

Status2

Reports the status of the sender (normally only for debugging purposes):

  • Sending - currently sending audio over the network
  • Ready - capable of sending audio but no listeners. Use Audio to determine whether audio would be sent immediately a listener joins.
  • Blocked - audio from another sender detected on the same channel (mis-configuration)
  • Inactive - sender device is playing content which cannot be broadcast
  • Disabled - sender disabled by user configuration

Enabled

true if the device bearing this service is capable of acting as a Songcast sender (i.e. Songcast sending is enabled and the sender is not blocked due to a multicast port clash); false otherwise.

Actions

Attributes

Return the value of the Attributes state variable

Audio

Return the value of the Audio state variable

Metadata

Return the value of the Metadata state variable

PresentationUrl

Return the value of the PresentationUrl state variable

Status

Return the value of the Status state variable

Sender Service Description (XML) 

   Domain  : av.openhome.org
   Name    : Sender
   Version : 2


<?xml version="1.0"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
  <specVersion>
    <major>1</major>
    <minor>0</minor>
  </specVersion>
 
  <actionList>
    <action>
      <name>PresentationUrl</name>
      <argumentList>
        <argument>
          <name>Value</name>
          <direction>out</direction>
          <relatedStateVariable>PresentationUrl</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>Metadata</name>
      <argumentList>
        <argument>
          <name>Value</name>
          <direction>out</direction>
          <relatedStateVariable>Metadata</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>Audio</name>
      <argumentList>
        <argument>
          <name>Value</name>
          <direction>out</direction>
          <relatedStateVariable>Audio</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>Status</name>
      <argumentList>
        <argument>
          <name>Value</name>
          <direction>out</direction>
          <relatedStateVariable>Status</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>Status2</name>
      <argumentList>
        <argument>
          <name>Value</name>
          <direction>out</direction>
          <relatedStateVariable>Status2</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>Enabled</name>
      <argumentList>
        <argument>
          <name>Value</name>
          <direction>out</direction>
          <relatedStateVariable>Enabled</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
    <action>
      <name>Attributes</name>
      <argumentList>
        <argument>
          <name>Value</name>
          <direction>out</direction>
          <relatedStateVariable>Attributes</relatedStateVariable>
        </argument>
      </argumentList>
    </action>
  </actionList>
 
  <serviceStateTable>
    <stateVariable sendEvents="yes">
      <name>PresentationUrl</name>
      <dataType>string</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>Metadata</name>
      <dataType>string</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>Audio</name>
      <dataType>boolean</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>Status</name>
      <dataType>string</dataType>
      <allowedValueList>
        <allowedValue>Enabled</allowedValue>
        <allowedValue>Disabled</allowedValue>
        <allowedValue>Blocked</allowedValue>
      </allowedValueList>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>Status2</name>
      <dataType>string</dataType>
      <allowedValueList>
        <allowedValue>Sending</allowedValue>
        <allowedValue>Ready</allowedValue>
        <allowedValue>Blocked</allowedValue>
        <allowedValue>Inactive</allowedValue>
        <allowedValue>Disabled</allowedValue>
      </allowedValueList>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>Enabled</name>
      <dataType>boolean</dataType>
    </stateVariable>
    <stateVariable sendEvents="yes">
      <name>Attributes</name>
      <dataType>string</dataType>
    </stateVariable>
  </serviceStateTable>
</scpd>
Retrieved from "http://wiki.openhome.org/wiki/Av:Developer:SenderService"