Universal Plug-n-Play

From OSDev Wiki
Jump to: navigation, search

Universal Plug-n-Play (UPnP) is a standard set of network protocols defined to allow network devices to discover and retrieve metadata from other devices on the same network. It uses various network protocols, such as UDP, HTTP and SOAP messages to allow reliable cross-platform communication.

Contents

Device Discovery

UPnP devices can be discovered by listening for multicast UDP messages on port 1900.

These messages will contain HTTP-like requests and headers containing URLs that allow clients to further query the device for more information using HTTP GET requests, which return XML documents defining any services, actions or events supported by the device.

An example of a NOTIFY message sent by a device every few minutes may look like: 

NOTIFY * HTTP/1.1
HOST: 239.255.255.250:1900
LOCATION: http://100.100.100.100/Device.xml
NT: upnp:rootdevice
NTS: ssdp:alive

Device Information

Further information about the device can be retrieved by sending an HTTP GET request to the URL specified in the LOCATION header. The HTTP content that is returned will contain information about the device, and any services provided by the device. Each service has a unique Service Type that can be used to determine the exact functionality supported by the service, as well as a more generic Service ID that can be used as a fallback service classification for compatibility.

Each service listed in this document will have a link (SCPDURL) to a service definition XML file that provides even more metadata about that specific service, as well as a "control" URL that is used to send SOAP messages to control the service, and an "event subscription" URL that is used to subscribe to event notifications.

An example device definition document is shown below: 

<root xmlns="urn:schemas-upnp-org:device-1-0" xmlns:pnpx="http://schemas.microsoft.com/windows/pnpx/2005/11" xmlns:df="http://schemas.microsoft.com/windows/2008/09/devicefoundation">
	<specVersion>
		<major>1</major>
		<minor>0</minor>
	</specVersion>
	<device>
		<deviceType>urn:schemas-upnp-org:device:MediaServer:1</deviceType>
		<UDN>uuid:55076f6e-6b79-4d65-6401-00d0b811d10b</UDN>
		<friendlyName>MediaServer</friendlyName>
		<manufacturer>Manufacturer, Inc.</manufacturer>
		<manufacturerURL>http://www.manufacturer.com</manufacturerURL>
		<modelName>MediaServer 1.0</modelName>
		<modelURL>http://www.manufacturer.com/MediaServer</modelURL>
		<modelDescription>Media Server</modelDescription>
		<modelNumber>Media Server Home</modelNumber>
		<serialNumber>123345-50023</serialNumber>
		<UPC>1009234789893</UPC>
		<presentationURL>http://100.100.100.100/</presentationURL>
		<iconList>
			<icon>
				<mimetype>image/jpeg</mimetype>
				<height>48</height>
				<width>48</width>
				<depth>24</depth>
				<url>/images/icon-48x48.jpg</url>
			</icon>
			<icon>
				<mimetype>image/jpeg</mimetype>
				<height>120</height>
				<width>120</width>
				<depth>24</depth>
				<url>/images/icon-120x120.jpg</url>
			</icon>
		</iconList>
		<serviceList>
			<service>
				<serviceType>urn:schemas-upnp-org:service:ConnectionManager:1</serviceType>
				<serviceId>urn:upnp-org:serviceId:ConnectionManager</serviceId>
				<SCPDURL>/ConnectionManager.xml</SCPDURL>
				<eventSubURL>/ConnectionManager/Event</eventSubURL>
				<controlURL>/ConnectionManager/Control</controlURL>
			</service>
			<service>
				<serviceType>urn:schemas-upnp-org:service:ContentDirectory:1</serviceType>
				<serviceId>urn:upnp-org:serviceId:ContentDirectory</serviceId>
				<SCPDURL>/ContentDirectory.xml</SCPDURL>
				<eventSubURL>/ContentDirectory/Event</eventSubURL>
				<controlURL>/ContentDirectory/Control</controlURL>
			</service>
		</serviceList>
	</device>
</root>

Service Information

Further information concerning a service can be retrieved by sending an HTTP GET request to the URL specified in the SCPDURL field of the service listed in the device definition XML document. This URL may be a relative URL from the LOCATION field in the NOTIFY message sent by the device, or it may be a full URL if it starts with "http".

The Action List section lists all of the methods that can be invoked on the service, along with the IN and OUT parameters to each method. The type of each parameter is listed in the Serivce State Table section. 

<scpd xmlns="urn:schemas-upnp-org:service-1-0">
	<specVersion>
		<major>1</major>
		<minor>0</minor>
	</specVersion>
	<actionList>
		<action>
			<name>Browse</name>
			<argumentList>
				<argument>
					<name>ObjectID</name>
					<direction>in</direction>
					<relatedStateVariable>A_ARG_TYPE_ObjectID</relatedStateVariable>
				</argument>
				<argument>
					<name>BrowseFlag</name>
					<direction>in</direction>
					<relatedStateVariable>A_ARG_TYPE_BrowseFlag</relatedStateVariable>
				</argument>
				<argument>
					<name>Filter</name>
					<direction>in</direction>
					<relatedStateVariable>A_ARG_TYPE_Filter</relatedStateVariable>
				</argument>
				<argument>
					<name>StartingIndex</name>
					<direction>in</direction>
					<relatedStateVariable>A_ARG_TYPE_Index</relatedStateVariable>
				</argument>
				<argument>
					<name>RequestedCount</name>
					<direction>in</direction>
					<relatedStateVariable>A_ARG_TYPE_Count</relatedStateVariable>
				</argument>
				<argument>
					<name>SortCriteria</name>
					<direction>in</direction>
					<relatedStateVariable>A_ARG_TYPE_SortCriteria</relatedStateVariable>
				</argument>
				<argument>
					<name>Result</name>
					<direction>out</direction>
					<relatedStateVariable>A_ARG_TYPE_Result</relatedStateVariable>
				</argument>
				<argument>
					<name>NumberReturned</name>
					<direction>out</direction>
					<relatedStateVariable>A_ARG_TYPE_Count</relatedStateVariable>
				</argument>
				<argument>
					<name>TotalMatches</name>
					<direction>out</direction>
					<relatedStateVariable>A_ARG_TYPE_Count</relatedStateVariable>
				</argument>
				<argument>
					<name>UpdateID</name>
					<direction>out</direction>
					<relatedStateVariable>A_ARG_TYPE_UpdateID</relatedStateVariable>
				</argument>
			</argumentList>
		</action>
	</actionList>
	<serviceStateTable>
		<stateVariable sendEvents="no">
			<name>A_ARG_TYPE_SortCriteria</name>
			<dataType>string</dataType>
		</stateVariable>
		<stateVariable sendEvents="no">
			<name>A_ARG_TYPE_UpdateID</name>
			<dataType>ui4</dataType>
		</stateVariable>
		<stateVariable sendEvents="no">
			<name>A_ARG_TYPE_SearchCriteria</name>
			<dataType>string</dataType>
		</stateVariable>
		<stateVariable sendEvents="no">
			<name>A_ARG_TYPE_Filter</name>
			<dataType>string</dataType>
		</stateVariable>
		<stateVariable sendEvents="no">
			<name>A_ARG_TYPE_Result</name>
			<dataType>string</dataType>
		</stateVariable>
		<stateVariable sendEvents="no">
			<name>A_ARG_TYPE_Index</name>
			<dataType>ui4</dataType>
		</stateVariable>
		<stateVariable sendEvents="no">
			<name>A_ARG_TYPE_ObjectID</name>
			<dataType>string</dataType>
		</stateVariable>
		<stateVariable sendEvents="no">
			<name>A_ARG_TYPE_Count</name>
			<dataType>ui4</dataType>
		</stateVariable>
		<stateVariable sendEvents="no">
			<name>A_ARG_TYPE_BrowseFlag</name>
			<dataType>string</dataType>
			<allowedValueList>
				<allowedValue>BrowseMetadata</allowedValue>
				<allowedValue>BrowseDirectChildren</allowedValue>
			</allowedValueList>
		</stateVariable>
	</serviceStateTable>
</scpd>

Invoking Actions

Actions listed in the service definition XML document can be invoked by sending a HTTP POST request containing a SOAP envelope with the desired Action and any arguments defined in the service definition XML document. The device will perform the requested action and return a SOAP envelope containing any OUT parameter values defined in the service definition XML document.

An example SOAP request is shown below. The actual path, action and arguments will vary depending on the action being invoked. 

POST /Service/Control HTTP/1.0
HOST: 100.100.100.100:9000
CONTENT-LENGTH: 321
CONTENT-TYPE: text/xml; charset="utf-8"
USER-AGENT: OS/1.0 UPnP/2.0 product/1.0
SOAPACTION: "urn:schemas-upnp-org:service:ContentDirectory:1"
 
<?xml version="1.0"?>
 
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<s:Body>
		<u:Browse xmlns:u="urn:schemas-upnp-org:service:ContentDirectory:1">
			<ObjectID>0</ObjectID>
			<BrowseFlag>BrowseDirectChildren</BrowseFlag>
			<Filter>*</Filter>
			<StartingIndex>0</StartingIndex>
			<RequestedCount>0</RequestedCount>
			<SortCriteria></SortCriteria>
		</u:Browse>
	</s:Body>
</s:Envelope>


External Links

UPnP Specifications and Architecture Documentation

Retrieved from "https://wiki.osdev.org/index.php?title=Universal_Plug-n-Play&oldid=27957"
Personal tools
Namespaces
Variants
Actions
Navigation
About
Toolbox