You are on page 1of 136

UPnPDevice Architecture 1.

1
Document Revision Dat e: Oct ober 15, 2008

2008 Cont ribut ing Members of t he UPnP Forum. All right s reserved. See
ht t p:/ / www.upnp.org/ info/ cpyright .asp for more informat ion.

Authors*

Company

Alan Presser

AllegroSoft

Lee Farrell

Canon

Devon Kemp

Canon

William Lupt on

Conexant

Shinichi Tsuruyama

Epson

Shivaun Albright

HP

Andrew Donoho

IBM

John Rit chie

Int el

Bryan Roe

Int el

Mark Walker

Int el

Toby Nixon

Microsoft

Colleen Evans

Microsoft

Henry Rawas

Microsoft

Trevor Freeman

Microsoft

Joonyoung Park

Mot orola

Cat hy Chan

Nokia

Franklin Reynolds

Nokia

Jose Cost a-Requena

Nokia

Yinghua Ye

Nokia

Tom McGee

Philips

Geert Knapen

Philips

Maart en Bodlaender

Philips

Jarno Guidi

Philips

Lex Heerink

Philips

John Gildred

Pioneer

Alan Messer

Samsung

YoonSoo Kim

Samsung

Markus Wischy

Siemens

Andrew Fiddian-Green

Siemens

Bruce Fairman

Sony

Jonat han Tourzan

Sony

John Fuller

Sony

*Note: The UPnP Forum in no way guarantees the accuracy or completeness of this author list and in no way implies any
rights for or support from those members listed. This list is not the specifications contributor list that is kept on the UPnP
Forums website.

Table of Contents
List of Tables................................................................................................... v
List of Figures................................................................................................. vi
i
Introduction ............................................................................................... 1
i.1 What is UPnPTechnology? ........................................................................ 1
i.2 UPnPForum ......................................................................................... 1
i.3 In t his document ..................................................................................... 2
i.4 Audience ............................................................................................... 5
i.5 Conformance t erminology .......................................................................... 5
i.6 Acronyms .............................................................................................. 6
i.7 Glossary ................................................................................................ 6
i.8 References and resources........................................................................... 7
0 Addressing ................................................................................................. 8
0.1 Det ermining whet her t o use Aut o-IP .............................................................. 8
0.2 Choosing an address ................................................................................. 8
0.3 Test ing t he address .................................................................................. 9
0.4 Forwarding rules.................................................................................... 10
0.5 Periodic checking for dynamic address availabilit y ........................................... 10
0.6 Device naming and DNS int eract ion ............................................................. 10
0.7 Name t o IP address resolut ion ................................................................... 11
0.8 References .......................................................................................... 11
1 Discovery................................................................................................. 12
1.1 SSDP message format .............................................................................. 15
1.1.1 SSDP St art -line ................................................................................. 16
1.1.2 SSDP message header fields ................................................................. 16
1.1.3 SSDP header field ext ensions................................................................ 16
1.1.4 UUID format and RECOMMENDED generat ion algorit hms................................ 17
1.1.5 SSDP processing rules ......................................................................... 17
1.2 Advert isement ...................................................................................... 17
1.2.1 Advert isement prot ocols and st andards ................................................... 18
1.2.2 Device available - NOTIFY wit h ssdp:alive ................................................ 19
1.2.3 Device unavailable -- NOTIFY wit h ssdp:byebye.......................................... 25
1.2.4 Device Updat e NOTIFY wit h ssdp:updat e ................................................ 27
1.3 Search ................................................................................................ 29
1.3.1 Search prot ocols and st andards ............................................................. 29
1.3.2 Search request wit h M-SEARCH ............................................................. 30
1.3.3 Search response ............................................................................... 33
1.4 References .......................................................................................... 36
2 Description .............................................................................................. 37
2.1 Generic requirement s on HTTP usage........................................................... 40
2.2 Generic requirement s on XML usage ............................................................ 43
2.3 Device descript ion ................................................................................. 43

ii

2.4 UPnP Device Templat e ............................................................................ 48


2.5 Service descript ion ................................................................................. 48
2.5.1 Defining and processing ext ended dat a t ypes ............................................ 55
2.5.2 St ring equivalent s of ext ended dat a t ypes ................................................ 57
2.5.3 Generic requirement s ........................................................................ 58
2.5.4 Ordering of Element s ......................................................................... 58
2.5.5 Versioning ...................................................................................... 59
2.6 UPnP Service Templat e............................................................................ 59
2.7 Non-st andard vendor ext ensions and limit at ions.............................................. 60
2.7.1 Placement of Addit ional Element s and At t ribut es ....................................... 61
2.8 UPnP Device Schema............................................................................... 61
2.9 UPnP Service Schema .............................................................................. 62
2.10 UPnP Dat at ype Schema............................................................................ 62
2.11 Ret rieving a descript ion using HTTP ............................................................ 62
2.12 References .......................................................................................... 65
3 Control ................................................................................................... 67
3.1 Cont rol prot ocols................................................................................... 69
3.1.1 SOAP Profile .................................................................................... 69
3.2 Act ions ............................................................................................... 73
3.2.1 Act ion invocat ion .............................................................................. 73
3.2.2 Act ion Response ............................................................................... 76
3.2.3 UPnP Act ion Schema .......................................................................... 79
3.2.4 Recommendat ions and addit ional requirement s ......................................... 79
3.2.5 Act ion error response ......................................................................... 79
3.2.6 UPnP Error Schema............................................................................ 82
3.3 Query for variable .................................................................................. 83
3.4 References .......................................................................................... 83
4 Eventing.................................................................................................. 84
4.1 Unicast event ing.................................................................................... 85
4.1.1 Subscript ion .................................................................................... 86
4.1.2 SUBSCRIBE wit h NT and CALLBACK ......................................................... 88
4.1.3 Renewing a subscript ion wit h SUBSCRIBE wit h SID....................................... 91
4.1.4 Canceling a subscript ion wit h UNSUBSCRIBE.............................................. 93
4.2 Mult icast Event ing.................................................................................. 95
4.3 Event messages ..................................................................................... 96
4.3.1 Error Cases ..................................................................................... 97
4.3.2 Unicast event ing: Event messages: NOTIFY ............................................... 97
4.3.3 Mult icast Event ing: Event messages: NOTIFY ............................................ 101
4.4 UPnP Event Schema ............................................................................... 104
4.5 Augment ing t he UPnP Device and Service Schemas ......................................... 104
4.6 References ......................................................................................... 105
5 Presentation........................................................................................... 106
5.1 References ......................................................................................... 107
Appendix A. IP Version 6 Support ................................................................... 109

iii

A.1 Int roduct ion ........................................................................................ 109


A.2 General Principles................................................................................. 109
A.2.1 Device operat ion ............................................................................. 110
A.2.2 Cont rol point operat ion ..................................................................... 110
A.3 Addressing .......................................................................................... 110
A.3.1 Summary of boot / st art up process ......................................................... 111
A.3.2 Short overview of prot ocol specified by RFC 2462 ...................................... 111
A.4 Discovery ........................................................................................... 112
A.4.1 Advert isement ................................................................................ 113
A.4.2 Advert isement : Device unavailable ....................................................... 114
A.4.3 Advert isement : Device updat e ............................................................. 114
A.4.4 Search .......................................................................................... 114
A.4.5 Search response .............................................................................. 115
A.5 Descript ion ......................................................................................... 115
A.6 Cont rol .............................................................................................. 115
A.7 Event ing ............................................................................................ 115
A.8 Present at ion ....................................................................................... 116
A.9 References ......................................................................................... 116
Appendix B. Schemas.................................................................................. 117
B.1 UPnP Device Schema.............................................................................. 117
B.2 UPnP Service Schema ............................................................................. 122
B.3 UPnP Cont rol Schema............................................................................. 126
B.4 UPnP Error Schema................................................................................ 127
B.5 UPnP Event Schema ............................................................................... 128
B.6 Schema references................................................................................ 129

iv

List of Tables
Table i-1:

Acronyms ......................................................................................... 6

Table 1-1:

Root device discovery messages ........................................................... 20

Table 1-2:

Embedded device discovery messages .................................................... 20

Table 1-3:

Service discovery messages................................................................. 20

Table 2-1:

Vendor ext ensions............................................................................ 60

Table 3-1:

SOAP 1.1 UPnP Profile ....................................................................... 70

Table 3-2:

mustUnderstand at t ribut e ............................................................... 71

Table 3-3:

UPnP Defined Act ion error codes .......................................................... 82

Table 4-4:

HTTP St at us Codes indicat ing a Subscript ion Error ..................................... 91

Table 4-5:

HTTP St at us Codes indicat ing a Resubscript ion Error .................................. 93

Table 4-6:

HTTP St at us Codes indicat ing a Cancel Subscript ion Error ............................ 94

Table 4-7:

HTTP St at us Codes indicat ing a Not ify Error ............................................ 101

Table 4-7:

Mult icast event levels ...................................................................... 103

List of Figures
Figure i-1:

Prot ocol st ack .................................................................................. 2

Figure 1-1:

Discovery archit ect ure...................................................................... 13

Figure 1-2:

Advert isement prot ocol st ack ............................................................. 19

Figure 1-3:

Init ial and repeat announcement s, no announcement spreading.................... 21

Figure 1-4:

Init ial and repeat announcement s, message spreading of repeat announcement s 21

Figure 1-5:

Search prot ocol st ack ....................................................................... 30

Figure 2-1:

Descript ion archit ect ure ................................................................... 37

Figure 2-2:

Descript ion ret rieval prot ocol st ack ...................................................... 63

Figure 3-1:

Cont rol archit ect ure ........................................................................ 67

Figure 3-2:

Cont rol prot ocol st ack ...................................................................... 69

Figure 4-1:

Unicast event ing archit ect ure ............................................................. 85

Figure 4-2:

Unicast event ing prot ocol st ack ........................................................... 86

Figure 4-3:

Mult icast event ing archit ect ure ........................................................... 95

Figure 4-4:

Mulit cast event ing prot ocol st ack......................................................... 95

Figure 5-1:

Present at ion archit ect ure ................................................................. 106

Figure 5-2:

Present at ion prot ocol st ack .............................................................. 107

vi

Introduction

[Informative]

i.1

What is UPnP 1 Technology?

UPnPt echnology defines an archit ect ure for pervasive peer-t o-peer net work connect ivit y of int elligent appliances, wireless
devices, and PCs of all form fact ors. It is designed t o bring easy-t o-use, flexible, st andards-based connect ivit y t o ad-hoc or
unmanaged net works whet her in t he home, in a small business, public spaces, or at t ached t o t he Int ernet . UPnP t echnology
provides a dist ribut ed, open net working archit ect ure t hat leverages TCP/ IP and Web t echnologies t o enable seamless proximit y
net working in addit ion t o cont rol and dat a t ransfer among net worked devices.

The UPnP Device Archit ect ure (UDA) is more t han j ust a simple ext ension of t he plug and play peripheral model. It is designed t o
support zero-configurat ion, "invisible" net working, and aut omat ic discovery for a breadt h of device cat egories from a wide range
of vendors. This means a device can dynamically j oin a net work, obt ain an IP address, convey it s capabilit ies, and learn about
t he presence and capabilit ies of ot her devices. Finally, a device can leave a net work smoot hly and aut omat ically wit hout leaving
any unwant ed st at e behind.

The t echnologies leveraged in t he UPnP archit ect ure include Int ernet prot ocols such as IP, TCP, UDP, HTTP, and XML. Like t he
Int ernet , cont ract s are based on wire prot ocols t hat are declarat ive, expressed in XML, and communicat ed via HTTP. Using
Int ernet prot ocols is a st rong choice for UDA because of it s proven abilit y t o span different physical media, t o enable real world
mult iple-vendor int eroperat ion, and t o achieve synergy wit h t he Int ernet and many home and office int ranet s. The UPnP
archit ect ure has been explicit ly designed t o accommodat e t hese environment s. Furt her, via bridging, UDA accommodat es media
running non-IP prot ocols when cost , t echnology, or legacy prevent s t he media or devices at t ached t o it from running IP.

What is "universal" about UPnP t echnology? No device drivers; common prot ocols are used inst ead. UPnP net working is media
independent . UPnP devices can be implement ed using any programming language, and on any operat ing syst em. The UPnP
archit ect ure does not specify or const rain t he design of an API for applicat ions; OS vendors may creat e APIs t hat suit t heir
cust omers needs.

i.2

UPnP Forum

The UPnP Forum is an indust ry init iat ive designed t o enable easy and robust connect ivit y among st and-alone devices and PCs
from many different vendors. The UPnP Forum seeks t o develop st andards for describing device prot ocols and XML-based device
schemas for t he purpose of enabling device-t o-device int eroperabilit y in a scalable, net worked environment .

The UPnP Implement ers Corporat ion (UIC) is comprised of UPnP Forum member companies across many indust ries t hat promot e
t he adopt ion of uniform t echnical device int erconnect ivit y st andards and t est ing and cert ifying of t hese devices. The UIC

UPnPis a cert ificat ion mark of t he UPnPImplement ers Corporat ion.

develops and administ ers t he t est ing and cert ificat ion process, administ ers t he UPnP logo program, and provides informat ion t o
UIC members and ot her int erest ed part ies regarding t he cert ificat ion of UPnP devices. The UPnP device cert ificat ion process is
open t o any vendor who is a member of t he UPnP Forum and UIC, has paid t he UIC dues, and has devices t hat support UPnP
funct ionalit y. For more informat ion, see ht t p:/ / www.upnp-ic.org.

The UPnP Forum has set up working commit t ees in specific areas of domain expert ise. These working commit t ees are charged
wit h creat ing proposed device st andards, building sample implement at ions, and building appropriat e t est suit es. This document
indicat es specific t echnical decisions t hat are t he purview of UPnP Forum working commit t ees.

UPnP vendors can build compliant devices wit h confidence of int eroperabilit y and benefit s of shared int ellect ual propert y and
t he logo program. Separat e from t he logo program, vendors may also build devices t hat adhere t o t he UPnP Device Archit ect ure
defined herein wit hout a formal st andards procedure. If vendors build non-st andard devices, t hey det ermine t echnical decisions
t hat would ot herwise be det ermined by a UPnP Forum working commit t ee.

i.3

In this document

The UPnP Device Archit ect ure (formerly known as t he DCP Framework) cont ained herein defines t he prot ocols for communicat ion
bet ween cont rollers, or cont rol point s, and devices. For discovery, descript ion, cont rol, event ing, and present at ion, t he UPnP
Device Archit ect ure uses t he following prot ocol st ack (t he indicat ed colors and t ype st yles are used t hroughout t his document t o
indicat e where each prot ocol element is defined):

Figure i-1:

Protocol stack
UPnP vendor [purple-it alic]
UPnP Forum [red-it al ic]
UPnP Device Architecture [green-bold]

SSDP [blue]

SOAP [blue]

GENA [navy-bold]

HTTP [black]

HTTP [black]

Multicast events [navy-bold]

UDP [black]

TCP [black]

IP [black]

At t he highest layer, messages logically cont ain only UPnP vendor-specific informat ion about t heir devices. Moving down t he
st ack, vendor cont ent is supplement ed by informat ion defined by UPnP Forum working commit t ees. Messages from t he layers
above are host ed in UPnP-specific prot ocols such as t he Simple Service Discovery Prot ocol (SSDP), t he General Event Not ificat ion
Archit ect ure (GENA) and t he mult icast event prot ocol defined in t his document , and ot hers t hat are referenced. SSDP is
delivered via eit her mult icast or unicast UDP. Mult icast event s are delivered via mult icast UDP. GENA is delivered via HTTP.
Ult imat ely, all messages above are delivered over IP. The remaining sect ions of t his document describe t he cont ent and format
for each of t hese prot ocol layers in det ail. For reference, colors in [square bracket s] above indicat e which prot ocol defines
specific message component s t hroughout t his document .

Two general classificat ions of devices are defined by t he UPnP archit ect ure: cont rolled devices (or simply devices ), and cont rol
point s. A cont rolled device funct ions in t he role of a server, responding t o request s from cont rol point s. Bot h cont rol point s and
cont rolled devices can be implement ed on a variet y of plat forms including personal comput ers and embedded syst ems. Mult iple
devices, cont rol point s, or bot h may be operat ional on t he same net work endpoint simult aneously.

Not e: This document is orient ed t oward an IPv4 environment . Considerat ions for an IPv6 environment are expressed in Appendix
A.

The foundat ion for UPnP net working is IP addressing. In an IPv4 environment , each device or cont rol point must have a Dynamic
Host Configurat ion Prot ocol (DHCP) client and search for a DHCP server when t he device or cont rol point is first connect ed t o t he
net work. If a DHCP server is available, i.e., t he net work is managed; t he device or cont rol point MUST use t he IP address
assigned t o it . If no DHCP server is available, i.e., t he net work is unmanaged; t he device or cont rol point MUST use Aut o IP t o get
an address. In brief, Aut o IP defines how a device or cont rol point int elligent ly chooses an IP address from a set of reserved
addresses and is able t o move easily bet ween managed and unmanaged net works. If during t he DHCP t ransact ion, t he device or
cont rol point obt ains a domain name, e.g., t hrough a DNS server or via DNS forwarding, t he device or cont rol point should use
t hat name in subsequent net work operat ions; ot herwise, t he device or cont rol point should use it s IP address.

Cert ain UPnP net works have more complex configurat ions such as mult iple physical net works and/ or mult iple logical net works t o
accommodat e mult iple non-overlapping addressing schemes. Devices and cont rol point s may also have t wo or more net work
int erfaces, and/ or t wo or more IP addresses assigned t o each int erface. In such configurat ions, a single device or cont rol point
may be assigned mult iple IP addresses from different logical net works in t he same UPnP net work, result ing in devices appearing
t o a cont rol point mult iple t imes in t he net work. Devices and cont rol point s t hat have mult iple IP addresses on t he same UPnP
net work are referred t o as mult i-homed. Throughout t his document , t he t erm "UPnP-enabled int erface" is used t o refer t o an
int erface which is assigned an IP address belonging t o t he UPnP net work. Addit ional behaviors specific t o mult i-homed devices
and cont rol point s will be covered in applicable sect ions t hroughout t he document . However, as a general principle, relat ed
int eract ions bet ween cont rol point s and devices (e.g. act ion cont rol request and response messages, event subscript ion and
event messages) MUST occur using t he same pair of out going and incoming UPnP-enabled int erfaces.

Given an IP address, St ep 1 in UPnP net working is discovery. When a device is added t o t he net work, t he UPnP discovery prot ocol
allows t hat device t o advert ise it s services t o cont rol point s on t he net work. Similarly, when a cont rol point is added t o t he
net work, t he UPnP discovery prot ocol allows t hat cont rol point t o search for devices of int erest on t he net work. The fundament al
exchange in bot h cases is a discovery message cont aining a few essent ial specifics about t he device or one of it s services, e.g.,
it s t ype, ident ifier, and a point er t o more det ailed informat ion. The sect ion on Discovery below explains how devices advert ise,
how cont rol point s search, and cont ains det ails about t he format of discovery messages.

St ep 2 in UPnP net working is descript ion. Aft er a cont rol point has discovered a device, t he cont rol point st ill knows very lit t le
about t he device. For t he cont rol point t o learn more about t he device and it s capabilit ies, or t o int eract wit h t he device, t he

cont rol point must ret rieve t he device's descript ion from t he URL provided by t he device in t he discovery message. Devices may
cont ain ot her logical devices, as well as funct ional unit s, or services. The UPnP descript ion for a device is expressed in XML and
includes vendor-specific manufact urer informat ion like t he model name and number, t he serial number, t he manufact urer name,
URLs t o vendor-specific Web sit es, et c. The descript ion also includes a list of any embedded devices or services, as well as URLs
for cont rol, event ing, and present at ion. For each service, t he descript ion includes a list of t he commands, or act ions, t o which
t he service responds, and paramet ers, or argument s for each act ion; t he descript ion for a service also includes a list of variables;
t hese variables model t he st at e of t he service at run t ime, and are described in t erms of t heir dat a t ype, range, and event
charact erist ics. The sect ion on Descript ion below explains how devices are described and how cont rol point s ret rieve t hose
descript ions.

St ep 3 in UPnP net working is cont rol . Aft er a cont rol point has ret rieved a descript ion of t he device, t he cont rol point can send
act ions t o a device's services. To do t his, a cont rol point sends a suit able cont rol message t o t he cont rol URL for t he service
(provided in t he device descript ion). Cont rol messages are also expressed in XML using t he Simple Obj ect Access Prot ocol (SOAP).
Like funct ion calls, in response t o t he cont rol message, t he service ret urns any act ion-specific values. The effect s of t he act ion,
if any, are modeled by changes in t he variables t hat describe t he run-t ime st at e of t he service. The sect ion on Cont rol below
explains t he descript ion of act ions, st at e variables, and t he format of cont rol messages.

St ep 4 in UPnP net working is event ing. A UPnP descript ion for a service includes a list of act ions t he service responds t o and a list
of variables t hat model t he st at e of t he service at run t ime. The service publishes updat es when t hese variables change, and a
cont rol point may subscribe t o receive t his informat ion. The service publishes updat es by sending event messages. Event
messages cont ain t he names of one or more st at e variables and t he current value of t hose variables. These messages are also
expressed in XML. A special init ial event message is sent when a cont rol point first subscribes; t his event message cont ains t he
names and values for all event ed variables and allows t he subscriber t o init ialize it s model of t he st at e of t he service. To support
scenarios wit h mult iple cont rol point s, event ing is designed t o keep all cont rol point s equally informed about t he effect s of any
act ion. Therefore, all subscribers are sent all event messages, subscribers receive event messages for all event ed variables t hat
have changed, and event messages are sent no mat t er why t he st at e variable changed (eit her in response t o a request ed act ion
or because t he st at e t he service is modeling changed). Mult icast event ing is a variant of St ep 4 in UPnP net working. Through
mult icast event ing, cont rol point s can list en t o st at e changes in services wit hout subscript ion. This form of event ing is useful first
when event s which are not relevant t o specific UPnP int eract ions should be delivered t o cont rol point s t o inform users, and
second when mult iple cont rolled devices want t o inform mult iple ot her cont rol point s. Mult icast event ing is inherent ly unreliable
since it is based on UDP. To increase t he probabilit y of successful t ransmission, t he opt ion t o ret ransmit mult icast event
not ificat ions is out lined. UPnP Working commit t ees should define whet her specific event s are mult icast event s. The sect ion on
Event ing below explains unicast event subscript ion and t he format of bot h unicast and mult icast event messages.

St ep 5 in UPnP net working is present at ion. If a device has a URL for present at ion, t hen t he cont rol point can ret rieve a page
from t his URL, load t he page int o a browser, and depending on t he capabilit ies of t he page, allow a user t o cont rol t he device

and/ or view device st at us. The degree t o which each of t hese can be accomplished depends on t he specific capabilit ies of t he
present at ion page and device. The sect ion on Present at ion below explains t he prot ocol for ret rieving a present at ion page.

i.4

Audience

The audience for t his document includes UPnP device and cont rol point vendors, members of UPnP Forum working commit t ees,
and anyone else who has a need t o underst anding t he t echnical det ails of UPnP prot ocols.

This document assumes t he reader is familiar wit h t he HTTP, TCP, UDP, IP family of prot ocols; t his document makes no at t empt
t o explain t hem. This document also assumes most readers will be new t o XML, and while it is not an XML t ut orial, XML-relat ed
issues are addressed in det ail given t he cent ralit y of XML t o t he UPnP Device Archit ect ure. This document makes no assumpt ions
about t he reader's underst anding of various programming or script ing languages.

i.5

Conformance terminology

In t his document , feat ures are described as REQUIRED, RECOMMENDED, OPTIONAL or DEPRECATED as follows:

REQUIRED (or MUST or MANDATORY).


These basic feat ures MUST be implement ed t o comply wit h UPnP Device Archit ect ure. The phrases MUST NOT , and
PROHIBITED indicat e behavior t hat is prohibit ed, i.e. t hat if performed means t he implement at ion is not in compliance.

RECOMMENDED (or SHOULD).


These feat ures add funct ionalit y support ed by UPnP Device Archit ect ure and SHOULD be implement ed. RECOMMENDED
feat ures t ake advant age of t he capabilit ies UPnP Device Archit ect ure, usually wit hout imposing maj or cost increases. Not ice
t hat for compliance t est ing, if a RECOMMENDED feat ure is implement ed, it MUST meet t he specified requirement s t o be in
compliance wit h t hese guidelines. Some RECOMMENDED feat ures could become requirement s in t he fut ure. The phrase
SHOULD NOT indicat es behavior t hat is permit t ed but NOT RECOMMENDED.

OPTIONAL (or MAY).


These feat ures are neit her REQUIRED nor RECOMMENDED by UPnP Device Archit ect ure, but if t he feat ure is implement ed, it
MUST meet t he specified requirement s t o be in compliance wit h t hese guidelines. These feat ures are not likely t o become
requirement s in t he fut ure.

DEPRECATED.
Alt hough t hese feat ures are st ill described in t his specificat ion, t hey should not be implement ed except for backward
compat ibilit y. The occurrence of a deprecat ed feat ure during operat ion of an implement at ion compliant wit h t he current
specificat ion has no effect on t he implement at ion s operat ion and does not produce any error condit ions. Backward
compat ibilit y may require t hat a feat ure is implement ed and funct ions as specified but it MUST never be used by
implement at ions compliant wit h t his specificat ion.

i.6

Acronyms

Table i-1:

Acronyms

Acronym

Meaning

Acronym

Meaning

ARP

Address Resolut ion Prot ocol

SOAP

Simple Obj ect Access Prot ocol

CP

Cont rol Point

SSDP

Simple Service Discovery Prot ocol

DCP

Device Cont rol Prot ocol

UDA

UPnP Device Archit ect ure

DDD

Device Descript ion Document

UPC

Universal Product Code

DHCP

Dynamic Host Configurat ion Prot ocol

URI

Uniform Resource Ident ifier

DNS

Domain Name Syst em

URL

Uniform Resource Locat or

GENA

General Event Not ificat ion Archit ect ure

URN

Uniform Resource Name

HTML

Hypert ext Markup Language

UUID

Universally Unique Ident ifier

HTTP

Hypert ext Trrdansfer Prot ocol

XML

Ext ensible Markup Language

SCPD

Service Cont rol Prot ocol Descript ion

i.7

Glossary

act ion
Command exposed by a service. Takes one or more input or out put argument s. May have a ret urn value. For more
informat ion, see sect ion 2, Descript ion and sect ion 3, Cont rol .
argument
Paramet er for act ion exposed by a service. May be in or out . For more informat ion, see sect ion 2, Descript ion and
sect ion 3, Cont rol .
cont rol point
Ret rieves device and service descript ions, sends act ions t o services, polls for service st at e variables, and receives event s
from services.
device
Logical device. A cont ainer. May embed ot her logical devices. Embeds one or more services. Advert ises it s presence on
net work(s). For more informat ion, see sect ion 1, Discovery and sect ion 2, Descript ion .
device descript ion
Formal definit ion of a logical device, expressed in t he UPnP Templat e Language. Writ t en in XML synt ax. Specified by a UPnP
vendor by filling in t he placeholders in a UPnP Device Templat e, including, e.g., manufact urer name, model name, model
number, serial number, and URLs for cont rol, event ing, and present at ion. For more informat ion, see sect ion 2,
Descript ion .
device t ype
St andard device t ypes are denot ed by urn:schemas-upnp-org:device: followed by a unique name assigned by a UPnP Forum
working commit t ee. One-t o-one relat ionship wit h UPnP Device Templat es. UPnP vendors may specify addit ional device
t ypes; t hese are denot ed by urn:domain-name:device: followed by a unique name assigned by t he vendor, where domainname is a Vendor Domain Name. For more informat ion, see sect ion 2, Descript ion .
event
Not ificat ion of one or more changes in st at e variables exposed by a service. For more informat ion, see sect ion 4, Event ing .
GENA
General Event Not ificat ion Archit ect ure. The event subscript ion and not ificat ion prot ocol defined in sect ion 4, Event ing .
publisher
Source of event messages. Typically a device's service. For more informat ion, see sect ion 4, Event ing .
root device
A logical device t hat is not embedded in any ot her logical device. For more informat ion, see sect ion 2, Descript ion .
service
Logical funct ional unit . Smallest unit s of cont rol. Exposes act ions and models t he st at e of a physical device wit h st at e
variables. For more informat ion, see sect ion 3, Cont rol .

service descript ion


Formal definit ion of a logical service, expressed in t he UPnP Templat e language. Writ t en in XML synt ax. Specified by a UPnP
vendor by filling in any placeholders in a UPnP Service Templat e. (Was SCPD.) For more informat ion, see sect ion 2,
Descript ion .
service t ype
St andard service t ypes are denot ed by urn:schemas-upnp-org:service: followed by a unique name assigned by a UPnP forum
working commit t ee, colon, and an int eger version number. One-t o-one relat ionship wit h UPnP Service Templat es. UPnP
vendors may specify addit ional services; t hese are denot ed by urn:domain-name:service: followed by a unique name
assigned by t he vendor, colon, and a version number, where domain-name is a Vendor Domain Name. For more informat ion,
see sect ion 2, Descript ion .
SOAP
Simple Obj ect Access Prot ocol. A remot e-procedure call mechanism based on XML t hat sends commands and receives values
over HTTP. For more informat ion, see sect ion 3, Cont rol .
SSDP
Simple Service Discovery Prot ocol. A mult icast discovery and search mechanism t hat uses a mult icast variant of HTTP over
UDP. Defined in sect ion 1, Discovery .
st at e variable
Single facet of a model of a physical service. Exposed by a service. Has a name, dat a t ype, opt ional default value, opt ional
const raint s values, and may t rigger event s when it s value changes. For more informat ion, see sect ion 2, Descript ion and
sect ion 3, Cont rol .
subscriber
Recipient of event messages. Typically a cont rol point . For more informat ion, see sect ion 4, Event ing .
UPnP Device Templat e
Templat e list ing device t ype, required embedded devices (if any), and required services. Writ t en in XML synt ax and derived
from t he UPnP Device Schema. Defined by a UPnP Forum working commit t ee. One-t o-one relat ionship wit h st andard device
t ypes. For more informat ion, see sect ion 2, Descript ion .
UPnP Service Templat e
Templat e list ing act ion names, paramet ers for t hose act ions, st at e variables, and propert ies of t hose st at e variables.
Writ t en in XML synt ax and derived from t he UPnP Service Schema. Defined by a UPnP Forum working commit t ee. One-t o-one
relat ionship wit h st andard service t ypes. For more informat ion, see sect ion 2, Descript ion .
UPnP Device Schema
Defines t he element s and at t ribut es used in UPnP Device and Service Templat es. Writ t en in XML synt ax and derived from
XML Schema (Part 1: St ruct ures, Part 2: Dat at ypes). Defined by t he UPnP Device Archit ect ure herein. For more informat ion,
see sect ion 2, Descript ion .
Vendor Domain Name
A domain name t hat is supplied by a vendor. It is owned by t he vendor, and MUST be regist ered wit h an ICANN accredit ed
Regist rar, such t hat it is unique. The vendor MUST keep t he domain name regist rat ion up t o dat e. A Vendor Domain Name
lengt h SHOULD be chosen t o be compat ible wit h t he use of t he domain name in t he UDA.

i.8

References and resources

RFC 2710
Mult icast List ener Discovery for IPv6. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2710.t xt .
RFC 2616
HTTP: Hypert ext Transfer Prot ocol 1.1. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2616.t xt .
RFC 2279
UTF-8, a t ransformat ion format of ISO 10646 (charact er encoding). Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2279.t xt .
XML
Ext ensible Markup Language. W3C recommendat ion. Available at : ht t p:/ / www.w3.org/ XML/ .
Each sect ion in t his document cont ains addit ional informat ion about resources for specific t opics.

0 Addressing
[Normative]
Addressing is St ep 0 of UPnPnet working. Through addressing, devices and cont rol point s get a net work address. Addressing
enables discovery (St ep 1) where cont rol point s f ind int erest ing device(s), descript ion (St ep 2) where cont rol point s learn about
device capabilit ies, cont rol (St ep 3) where a cont rol point sends commands t o device(s), event ing (St ep 4) where cont rol point s
list en t o st at e changes in device(s), and present at ion (St ep 5) where cont rol point s display a user int erf ace f or device(s).

The foundat ion for UPnP net working is IP addressing. A UPnP device or cont rol point MAY support IP version 4-only, or bot h IP
version 4 and IP version 6. This sect ion, and t he examples given t hroughout sect ions 1 t hrough 5 of t his document , assumes an
IPv4 implement at ion. Annex A of t his document describes IPv6 operat ion. Each UPnP device or cont rol point which does not it self
implement a DHCP server MUST have a Dynamic Host Configurat ion Prot ocol (DHCP) client and search for a DHCP server when t he
device or cont rol point is first connect ed t o t he net work (if t he device or cont rol point it self implement s a DHCP server, it MAY
allocat e it self an address from t he pool t hat it cont rols). If a DHCP server is available, i.e., t he net work is managed; t he device
or cont rol point MUST use t he IP address assigned t o it . If no DHCP server is available, i.e., t he net work is unmanaged; t he device
or cont rol point MUST use aut omat ic IP addressing (Aut o-IP) t o obt ain an address.

Aut o-IP (defined in RFC 3927) defines how a device or cont rol point : (a) det ermines if DHCP is unavailable, and (b) int elligent ly
chooses an IP address from a set of link-local IP addresses. This met hod of address assignment enables a device or cont rol point
t o easily move bet ween managed and unmanaged net works.

This sect ion provides an overview of t he basic operat ion of Aut o-IP. The operat ions described in t his sect ion are det ailed and
clarified in t he reference document s list ed below. Where conflict s bet ween t his document and t he reference document s exist ,
t he reference document always t akes precedence.

0.1 Determining whether to use Auto-IP


A device or cont rol point t hat support s Aut o-IP and is configured for dynamic address assignment begins by request ing an IP
address via DHCP by sending out a DHCPDISCOVER message. The amount of t ime t his DHCP Client list ens for DHCPOFFERs is
implement at ion dependent . If a DHCPOFFER is received during t his t ime, t he device or cont rol point MUST cont inue t he process
of dynamic address assignment . If no valid DHCPOFFERs are received, t he device or cont rol point MUST t hen aut o-configure an IP
address using Aut o-IP.

0.2 Choosing an address


To aut o-configure an IP address using Aut o-IP, t he device or cont rol point uses an implement at ion dependent algorit hm for
choosing an address in t he 169.254/ 16 range. The first and last 256 addresses in t his range are reserved and MUST NOT be used.

The select ed address MUST t hen be t est ed t o det ermine if t he address is already in use. If t he address is in use by anot her device
or cont rol point , anot her address MUST be chosen and t est ed, up t o an implement at ion dependent number of ret ries. The

address select ion MUST be randomized t o avoid collision when mult iple devices or cont rol point s are at t empt ing t o allocat e
addresses. The device or cont rol point chooses an address using a pseudo-random algorit hm (dist ribut ed over t he ent ire address
range from 169.254.1.0 t o 169.254.254.255) t o minimize t he likelihood t hat devices or cont rol point s t hat j oin t he net work at t he
same t ime will choose t he same address and subsequent ly choose alt ernat ive addresses in t he same sequence when collisions are
det ect ed. This pseudo-random algorit hm SHOULD be seeded using t he device s or cont rol point s Et hernet hardware MAC address.

0.3 Testing the address


To t est t he chosen address, t he device or cont rol point MUST use an Address Resolut ion Prot ocol (ARP) probe. An ARP probe is an
ARP request wit h t he device or cont rol point hardware address used as t he sender's hardware address and t he sender's IP address
set t o 0s. The device or cont rol point MUST t hen list en for responses t o t he ARP probe, or ot her ARP probes for t he same IP
address. If eit her of t hese ARP packet s is seen, t he device or cont rol point MUST consider t he address in use and t ry a different
address. The ARP probe MAY be repeat ed for great er cert aint y t hat t he address is not already in use; it is RECOMMENDED t hat t he
probe be sent four t imes at t wo-second int ervals.

Aft er successfully configuring a link-local address, t he device or cont rol point MUST send t wo grat uit ous ARPs, spaced t wo
seconds apart , t his t ime filling in t he sender IP address. The purpose of t hese grat uit ous ARPs is t o make sure t hat ot her host s on
t he net do not have st ale ARP cache ent ries left over from some ot her host t hat may previously have been using t he same
address.

Devices and cont rol point s t hat are equipped wit h persist ent st orage MAY record t he IP address t hey have select ed and on t he
next boot use t hat address as t heir first candidat e when probing, in order t o increase t he st abilit y of addresses and reduce t he
need t o resolve address conflict s.

Address collision det ect ion is not limit ed t o t he address t est ing phase, when t he device or cont rol point is sending ARP probes
and list ening for replies. Address collision det ect ion is an ongoing process t hat is in effect for as long as t he device or cont rol
point is using a link-local address. At any t ime, if a device or cont rol point receives an ARP packet wit h it s own IP address given
as t he sender IP address, but a sender hardware address t hat does not mat ch it s own hardware address, t hen t he device or
cont rol point MUST t reat t his as an address collision and MUST respond as described in eit her (a) or (b) below:

(a)

Immediat ely configure a new link-local IP address as described above; or,

(b) If t he device or cont rol point current ly has act ive TCP connect ions or ot her reasons t o prefer t o keep t he same IP
address, and has not seen any ot her conflict ing ARP packet s recent ly (e.g., wit hin t he last t en seconds) t hen it MAY
elect t o at t empt t o defend it s address once, by recording t he t ime t hat t he conflict ing ARP packet was received, and
t hen broadcast ing one single grat uit ous ARP, giving it s own IP and hardware addresses as t he source addresses of t he
ARP. However, if anot her conflict ing ARP packet is received wit hin a short t ime aft er t hat (e.g., wit hin t en seconds)
t hen t he device or cont rol point MUST immediat ely configure a new Aut o-IP address as described above.

The device or cont rol point MUST respond t o conflict ing ARP packet s as described in eit her (a) or (b) above; it MUST NOT ignore
conflict ing ARP packet s. If a new address is select ed, t he device or cont rol point MUST cancel previous advert isement s and readvert ise wit h t he new address.

Aft er successfully configuring an Aut o-IP address, all subsequent ARP packet s (replies as well as request s) cont aining an Aut o-IP
source address MUST be sent using link-level broadcast inst ead of link-level unicast , in order t o facilit at e t imely det ect ion of
duplicat e addresses.

0.4 Forwarding rules


IP packet s whose source or dest inat ion addresses are in t he 169.254/ 16 range MUST NOT be sent t o any rout er for forwarding.
Inst ead, t he senders MUST ARP for t he dest inat ion address and t hen send t he packet s direct ly t o t he dest inat ion on t he same link.
IP dat agrams wit h a mult icast dest inat ion address and an Aut o-IP source address MUST NOT be forwarded off t he local link.
Devices and cont rol point s MAY assume t hat all 169.254/ 16 dest inat ion addresses are on-link and direct ly reachable. The
169.254/ 16 address range MUST NOT be subnet t ed.

0.5 Periodic checking for dynamic address availability


A device or cont rol point t hat has aut o-configured an IP address MUST periodically check for t he exist ence of a DHCP server. This
is accomplished by sending DHCPDISCOVER messages. How oft en t his check is made is implement at ion dependent , but checking
every 5 minut es would maint ain a balance bet ween net work bandwidt h required and connect ivit y maint enance. If a DHCPOFFER
is received, t he device or cont rol point MUST proceed wit h dynamic address allocat ion. Once a DHCP assigned address is in place,
t he device or cont rol point MAY release t he aut o-configured address, but MAY also choose t o maint ain t his address for a period of
t ime (or indefinit ely) t o maint ain connect ivit y.

To swit ch over from one IP address t o a new one, t he device SHOULD, if possible, cancel any out st anding advert isement s made
on t he previous address and MUST issue new advert isement s on t he new address. The sect ion on Discovery explains
advert isement s and t heir cancellat ions. In addit ion, any event subscript ions are delet ed by t he device (see sect ion on Event ing).

For a mult i-homed device wit h mult iple IP addresses, t o swit ch one of t he IP addresses t o a new one, t he device SHOULD cancel
any out st anding advert isement s made on t he previous IP address, and MUST issue new advert isement s on t he new IP addresses.
Furt hermore, it MUST also issue appropriat e updat e advert isement s on all unaffect ed IP addresses. The sect ion on Discovery
explains advert isement s, t heir cancellat ions and updat es. The sect ion on Event ing explains t he effect on event subscript ions.

0.6 Device naming and DNS interaction


Once a device has a valid IP address for t he net work, it can be locat ed and referenced on t hat net work t hrough t hat address.
There may be sit uat ions where t he end user needs t o locat e and ident ify a device. In t hese sit uat ions, a friendly name for t he
device is much easier for a human t o use t han an IP address. If a device chooses t o provide a host name t o a DHCP server and
regist er wit h a DNS server, t he device SHOULD eit her ensure t he request ed host name is unique or provide a means for t he user

10

t o change t he request ed host name. Most of t en, devices do not provide a host name, but provide URLs using lit eral (numeric) IP
addresses.

Moreover, names are much more st at ic t han IP addresses. Client s referring a device by name don't require any modificat ion when
t he IP address of a device changes. Mapping of t he device's DNS name t o it s IP address could be ent ered int o t he DNS dat abase
manually or dynamically according t o RFC 2136. While devices support ing dynamic DNS updat es can regist er t heir DNS records
direct ly in t he DNS, it is also possible t o configure a DHCP server t o regist er DNS records on behalf of t hese DHCP client s.

0.7 Name to IP address resolution


A device t hat needs t o cont act anot her device ident ified by a DNS name needs t o discover it s IP address. The device submit s a
DNS query according t o RFC1034 and 1035 t o t he pre-configured DNS server(s) and receives a response from a DNS server
cont aining t he IP address of t he t arget device. A device can be st at ically pre-configured wit h t he list of DNS servers.
Alt ernat ively a device could be configured wit h t he list of DNS server t hrough DHCP, or aft er t he address assignment t hrough a
DHCPINFORM message.

0.8 References
RFC1034
Domain Names - Concept s and Facilit ies. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc1034.t xt .
RFC1035
Domain Names - Implement at ion and Specificat ion. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc1035.t xt .
RFC 2131
Dynamic Host Configurat ion Prot ocol. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2131.t xt .
RFC 2136
Dynamic Updat es in t he Domain Name Syst em. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2136.t xt .
RFC 3927
Dynamic Configurat ion of IPv4 Link-Local Addresses. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc3927.t xt .

11

1 Discovery
[Normative]
Discovery is St ep 1 in UPnPnet working. Discovery comes af t er addressing (St ep 0) where devices get a net work address.
Through discovery, cont rol point s f ind int erest ing device(s). Discovery enables descript ion (St ep 2) where cont rol point s learn
about device capabilit ies, cont rol (St ep 3) where a cont rol point sends commands t o device(s), event ing (St ep 4) where cont rol
point s list en t o st at e changes in device(s), and present at ion (St ep 5) where cont rol point s display a user int erf ace f or device(s).

Discovery is t he first st ep in UPnP net working. When a device is added t o t he net work, t he UPnP discovery prot ocol allows t hat
device t o advert ise it s services t o cont rol point s on t he net work. Similarly, when a cont rol point is added t o t he net work, t he
UPnP discovery prot ocol allows t hat cont rol point t o search for devices of int erest on t he net work. The fundament al exchange in
bot h cases is a discovery message cont aining a few, essent ial specifics about t he device or one of it s services, e.g., it s t ype,
universally unique ident ifier, a point er t o more det ailed informat ion and opt ionally paramet ers t hat ident ify t he current st at e of
t he device.

12

Figure 1-1:

Discovery architecture

When a device knows it is newly added t o t he net work, it MUST mult icast a number of discovery messages advert ising it self, it s
embedded devices, and it s services (init ial announce). Any int erest ed cont rol point can list en t o t he st andard mult icast address
for not ificat ions t hat new capabilit ies are available. A mult i-homed device MUST mult icast t he discovery messages on all UPnPenabled int erfaces. A mult i-homed cont rol point MAY list en t o t he st andard mult icast address on one, some or all of it s UPnPenabled int erfaces.

When a new cont rol point is added t o t he net work, it MAY mult icast a discovery message searching for int erest ing devices,
services, or bot h. All devices MUST list en t o t he st andard mult icast address for t hese messages and MUST respond if any of t heir
root devices, embedded devices or services mat ches t he search crit eria in t he discovery message. In addit ion, a cont rol point
MAY unicast a discovery message t o a specific IP address on port 1900 or on t he port specified by t he opt ional

13

SEARCHPORT.UPNP.ORG header field (which supersedes port 1900 for t his use), searching for a UPnP device or service at t hat
specific IP address. This act ion presumes t he cont rol point already knows t he device at t his IP address is a UPnP 1.1 device
(which list ens on t he appropriat e port ). The cont rol point can use unicast search for a number of applicat ions. A unicast search
can quickly confirm a specific device and provide t he corresponding discovery informat ion (e.g. UUID, URL) of t his device. All
devices MUST list en t o incoming unicast search messages on port 1900 or, if provided, t he port number specified in t he
SEARCHPORT.UPNP.ORG header field and MUST respond if any of t heir root devices, embedded devices or services mat ches t he
search crit eria in t he discovery message.

A mult i-homed cont rol point MAY mult icast discovery messages on one, some or all of it s UPnP-enabled int erfaces. Mult i-homed
devices MUST list en t o t he st andard mult icast address on all UPnP-enabled int erfaces for mult icast discovery messages. Mult ihomed devices MUST also list en t o incoming unicast search messages on port 1900 or, if provided, t he port number specified in
t he SEARCHPORT.UPNP.ORG header field. The devices MUST respond if any of t heir root devices, embedded devices or services
mat ches t he search crit eria in t he discovery message.

To reit erat e, a cont rol point MAY learn of a device of int erest because t hat device sent discovery messages advert ising it self or
because t he device responded t o a discovery message searching for devices. In eit her case, if a cont rol point is int erest ed in a
device and want s t o learn more about it , t he cont rol point uses t he informat ion in t he discovery message t o send a descript ion
query message. The sect ion on Descript ion explains descript ion messages in det ail.

When a device is removed from t he net work, it SHOULD, if possible, mult icast a number of discovery messages revoking it s
earlier announcement s, effect ively declaring t hat it s root devices, embedded devices and services will no longer be available.
When t he IP address of a device is changed, it SHOULD revoke any earlier announcement s and it MUST advert ise using t he new IP
address.

When a mult i-homed device becomes unavailable t o t he net work on any of it s UPnP-enabled int erfaces, it SHOULD, if possible,
mult icast a number of discovery messages revoking it s earlier announcement s on t he affect ed UPnP-enabled int erfaces,
effect ively declaring t hat it s root devices, embedded devices and services will no longer be available on t hose int erfaces. If it
remains available t o t he net work on any of it s ot her UPnP-enabled int erfaces, it MUST NOT mult icast such discovery messages on
t he unaffect ed UPnP-enabled int erfaces.

When a mult i-homed device becomes available t o t he net work on a new UPnP-enabled int erface (in addit ion t o any exist ing
UPnP-enabled int erfaces), it MUST increase it s BOOTID.UPNP.ORG field value (see sect ion 1.2 Advert isement ), and mult icast a
number of updat e messages on t he exist ing UPnP-enabled int erf aces t o announce t he new BOOTID.UPNP.ORG field value. Aft er
all t he updat e messages have been sent , it MUST mult icast a number of discovery messages on all (exist ing and new) UPnPenabled int erfaces wit h t he new BOOTID.UPNP.ORG field value.

Similarly, when one of t he IP addresses of a mult i-homed device is changed, it SHOULD revoke any earlier announcement s on t he
previous IP address. It MUST increase it s BOOTID.UPNP.ORG field value (see sect ion 1.2 Advert isement ), and mult icast a

14

number of updat e messages on t he exist ing UPnP-enabled int erf aces t o announce t he new BOOTID.UPNP.ORG field value. Aft er
all t he updat e messages have been sent , it MUST mult icast a number of discovery messages on all (exist ing and new) UPnPenabled int erfaces wit h t he new BOOTID.UPNP.ORG field value.

Finally, if a mult i-homed device loses connect ivit y on one of it s UPnP-enabled int erfaces and t hen regains connect ivit y, it MUST
increase it s BOOTID.UPNP.ORG field value (see sect ion 1.2 Advert isement ), and mult icast a number of updat e messages on t he
unaffect ed UPnP-enabled int erfaces t o announce t he new BOOTID.UPNP.ORG field value. Aft er all t he updat e messages have
been sent , it MUST mult icast a number of discovery messages on all (affect ed and unaffect ed) UPnP-enabled int erfaces wit h t he
new BOOTID.UPNP.ORG field value.

To limit net work congest ion, t he t ime-t o-live (TTL) of each IP packet for each mult icast message SHOULD default t o 2 and
SHOULD be configurable. When t he TTL is great er t han 1, it is possible for mult icast messages t o t raverse mult iple rout ers;
t herefore cont rol point s and devices using non-Aut oIP addresses MUST send an IGMP Join message so t hat rout ers will forward
mult icast messages t o t hem (t his is not necessary when using an Aut o-IP address, since packet s wit h Aut o-IP addresses will not be
forwarded by rout ers).

Versioning: Discovery plays an import ant role in t he int eroperabilit y of devices and cont rol point s using different versions of
UPnP net working. The UPnP Device Archit ect ure (defined herein) is versioned wit h bot h a maj or and a minor version, usually
writ t en as maj or.minor, where bot h maj or and minor are int egers (for example, version 2.10 [t wo dot t en] is newer t han version
2.2 [t wo dot t wo]). Advances in minor versions MUST be a compat ible superset of earlier minor versions of t he same maj or
version. Advances in maj or version are not required t o be superset s of earlier versions and are not guarant eed t o be backward
compat ible. Version informat ion is communicat ed in discovery and descript ion messages. Discovery messages include t he version
of UPnP net working t hat t he devices and cont rol point s support (in t he SERVER and USER-AGENT header fields); t he version of
device and service t ypes support ed is also included in relevant discovery messages. Addit ionally, descript ion document s also
include t he same informat ion. SERVER and USER-AGENT header fields are also used in cont rol and event ing t o communicat e
which version of UPnP net working t he devices and cont rol point s support . This sect ion explains t he format of version informat ion
in discovery messages and specific requirement s on discovery messages t o maint ain compat ibilit y wit h advances in minor versions.

The remainder of t his sect ion explains t he UPnP discovery prot ocol known as SSDP (Simple Service Discovery Prot ocol) in det ail,
enumerat ing how devices advert ise and revoke t heir advert isement s as well as how cont rol point s search and devices respond.

1.1 SSDP message format


SSDP uses part of t he header field format of HTTP 1.1 as defined in RFC 2616. However, it is NOT based on full HTTP 1.1 as it
uses UDP inst ead of TCP, and it has it s own processing rules. This sect ion defines t he generic format of a SSDP message.

15

All SSDP messages MUST be format t ed according t o RFC 2616 sect ion 4.1 generic message . SSDP messages MUST have a st art line and a list of message header fields. SSDP messages SHOULD NOT have a message body. If a SSDP message is received wit h a
message body, t he message body MAY be ignored.

1.1.1 SSDP Start-line


Each SSDP message MUST have exact ly one st art -line. See sect ion 1.2, Advert isement and sect ion 1.3, Search below for t he
definit ion of all possible SSDP messages. The st art -line MUST be format t ed eit her as defined in RFC 2616 sect ion 5.1 or sect ion
6.1. Furt hermore, t he st art -line MUST be one of t he following t hree:
NOTIFY * HTTP/ 1.1\r\n
M-SEARCH * HTTP/ 1.1\r\n
HTTP/ 1.1 200 OK\r\n

As a clarificat ion, while t he st art -line MUST include HTTP/ 1.1 , t his does not signal t hat SSDP is fully based on HTTP 1.1; t his
st art -line element is included for backward compat ibilit y reasons only.

1.1.2 SSDP message header fields


The message header fields in a SSDP message MUST be format t ed according t o RFC 2616 sect ion 4.2. This specifies t hat each
message header field consist of a case-insensit ive field name followed by a colon (":"), followed by t he case-sensit ive field value.
SSDP rest rict s allowed field values.

Example SSDP header:


HOST: 239.255.255.250:1900

1.1.3 SSDP header field extensions


UPnP working commit t ees and UPnP vendors are allowed t o ext end SSDP messages wit h addit ional SSDP header fields. Addit ional
message header fields can also be defined by t he UPnP Forum Technical commit t ee (e.g. sect ion 1.2, Advert isement defines
BOOTID.UPNP.ORG, CONFIGID.UPNP.ORG, NEXTBOOTID.UPNP.ORG, and SEARCHPORT.UPNP.ORG header fields). To prevent
name-clashes of header field definit ions (t wo part ies accident ally define t he same header field name wit h different semant ics),
vendor-defined header field names MUST have t he following format :
field-name = t oken . domain-name

where t he domain-name MUST be Vendor Domain Name, and in addit ion MUST sat isfy t he t oken format as defined in RFC 2616,
sect ion 2.2.

Example vendor-defined SSDP header fields:


myheader.philips.com: some value
myheader.sony.com: ot her value

16

1.1.4 UUID format and RECOMMENDED generation algorithms


UPnP 1.1 devices MUST format UUIDs according t o t he format specified below. However, UPnP 1.1 cont rol point s MUST also be
able t o accept UUIDs t hat have not been format t ed according t o t he rules specified below, as format t ing rules are not specified
in UPnP 1.0 ot her t han t he requirement t hat a UUID is a st ring.

UUIDs are 128 bit numbers t hat MUST be format t ed as specified by t he following grammar (t aken from [1]):
UUID = 4 * <hexOct et > - 2 * <hexOct et > - 2 * <hexOct et > - 2 * <hexOct et > - 6 * <hexOct et
hexOct et = <hexDigit > <hexDigit >
hexDigit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | a | b | c | d | e | f | A | B | C | D | E | F

The following is an example of t he st ring represent at ion of a UUID:


2fac1234-31f8-11b4-a222-08002b34c003

UUIDs MAY be generat ed using any suit able generat ion algorit hm 2 t hat sat isfies t he following requirement s:
1.

It is very unlikely t o duplicat e a UUID generat ed from some ot her resource.

2.

It maps down t o a 128-bit number.

3.

UUIDs MUST remain fixed over t ime.

The following UUID generat ion algorit hm is RECOMMENDED:


Time & MAC-based algorit hm as specified in [1], where t he UUID is generat ed once and st ored in non-volat ile memory if
available.

1.1.5 SSDP processing rules


When an SSDP message is received t hat is not format t ed according t o sect ion 1.1, SSDP message format (t he sect ions above),
receivers SHOULD silent ly discard t he message. Receivers MAY t ry t o parse such SSDP messages t o t ry t o int eroperat e.

When parsing SSDP header fields, receivers MUST parse all REQUIRED SSDP-defined header fields (see sect ion 1.2,
Advert isement and sect ion 1.3, Search below) and MAY skip all ot her header fields. Receivers MUST be able t o skip header
fields t hey do not underst and.

1.2 Advertisement
When a device is added t o t he net work, t he device advert ises it s services t o cont rol point s. It does t his by mult icast ing discovery
messages t o a st andard address and port (239.255.255.250:1900). Cont rol point s list en t o t his port t o det ect when new
capabilit ies are available on t he net work. To advert ise t he full ext ent of it s capabilit ies, a device MUST mult icast a number of
discovery messages corresponding t o each of it s root devices, embedded devices and services. Each message cont ains informat ion
specific t o t he embedded device (or service) as well as informat ion about it s enclosing device. Messages MUST include durat ion
2
The UUID generat ion algorit hm specified in [1] is RECOMMENDED, but is not MANDATORY, ot her UUID generat ion algorit hms may
be used inst ead, as long as t hey sat isfy t he t hree requirement s.

17

unt il t he advert isement s expire; if t he device remains available, t he advert isement s MUST be re-sent (wit h new durat ion). If t he
device becomes unavailable, t he device SHOULD explicit ly cancel it s advert isement s, but if t he device is unable t o do t his, t he
advert isement s will expire on t heir own. If a mult i-homed device becomes unavailable on some, but not all, of it s UPnP-enabled
int erfaces, t he device SHOULD explicit ly cancel it s advert isement s on t he affect ed UPnP-enabled int erfaces (but NOT on t he
unaffect ed UPnP-enabled int erfaces), but if t he device is unable t o do t his, t he advert isement s on t hose int erfaces or IP
addresses will expire on t heir own. In addit ion, messages include t he following header fields defined in t his document :
BOOTID.UPNP.ORG, NEXTBOOTID.UPNP.ORG, CONFIGID.UPNP.ORG, SEARCHPORT.UPNP.ORG. The field value of t he
BOOTID.UPNP.ORG header field MUST be increased each t ime a device (re)j oins t he net work and sends an init ial announce (a
reboot in UPnP t erms), or adds a UPnP-enabled int erface. Unless t he device explicit ly announces a change in t he
BOOTID.UPNP.ORG field value using an SSDP message, as long as t he device remains cont inuously available in t he net work, t he
same BOOTID.UPNP.ORG field value MUST be used in all repeat announcement s, search responses, updat e messages and
event ually bye-bye messages. Cont rol point s can parse t his header field t o det ect whet her t he device has pot ent ially lost it s
st at e (event subscript ions will have been lost , DCP specific st at e may have been changed) due t o a reboot . Since a device
cannot change IP addresses wit hout changing t he BOOTID.UPNP.ORG field value, t he BOOTID.UPNP.ORG field value can also be
used t o dist inguish mult i-homed devices (in t his case, a cont rol point will see SSDP messages from different IP addresses wit h t he
same UUID, BOOTID.UPNP.ORG field value) from devices t hat changed IP addresses (in t his case, t he BOOTID.UPNP.ORG field
value will be different ). The field value of t he NEXTBOOTID.UPNP.ORG header field indicat es t he field value of t he
BOOTID.UPNP.ORG header field t hat a mult i-homed device int ends t o use in fut ure announcement s aft er adding a new UPnPenabled int erface. The field value of t he CONFIGID.UPNP.ORG header field ident ifies t he current set of device and service
descript ions; cont rol point s can parse t his header field t o det ect whet her t hey need t o send new descript ion query messages.
The field value of t he SEARCHPORT.UPNP.ORG header field ident ifies t he port at which t he device list ens t o unicast M-SEARCH
messages; cont rol point s can parse t his header field t o know t o which port unicast M-SEARCH messages MUST be sent . These
header fields are explained in det ail below.

1.2.1 Advertisement protocols and standards


To send (and receive) advert isement s, devices (and cont rol point s) use t he following subset of t he overall UPnP prot ocol st ack.
(The overall UPnP prot ocol st ack is list ed at t he beginning of t his document .)

18

Figure 1-2:

Advertisement protocol stack


UPnP vendor [purple-it alic]
UPnP Forum [red-it al ic]
UPnP Device Architecture [green-bold]
SSDP [blue]
UDP [black]
IP [black]

At t he highest layer, discovery messages cont ain vendor-specific informat ion, e.g., URL for t he device descript ion and device
ident ifier. Moving down t he st ack, vendor cont ent is supplement ed by informat ion from a UPnP Forum working commit t ee, e.g.,
device t ype. Messages from t he layers above are host ed in UPnP-specific prot ocols, defined in t his document . In t urn, t he SSDP
messages are delivered via UDP over IP. For reference, colors in [square bracket s] above indicat e which prot ocol defines specific
header fields and field values in discovery messages list ed below.

1.2.2 Device available - NOTIFY with ssdp:alive


When a device is added t o t he net work, it MUST mult icast discovery messages t o advert ise it s root device, any embedded devices,
and any services. Each discovery message MUST cont ain four maj or component s:
1.

A not ificat ion t ype (e.g., device t ype), sent in an NT (Not ificat ion Type) header field.

2.

A composit e ident ifier for t he advert isement , sent in a USN (Unique Service Name) header field.

3.

A URL for more informat ion about t he device (or enclosing device in t he case of a service), sent in a LOCATION header
field.

4.

A durat ion for which t he advert isement is valid, sent in a CACHE-CONTROL header field.

To advert ise it s capabilit ies, a device mult icast s a number of discovery messages. Specifically, a root device MUST mult icast :

19

Three discovery messages for t he root device.

Table 1-1:

Root device discovery messages


USN *

NT
1

upnp:rootdevice

uuid:device-UUID::upnp:rootdevice
**

uuid:device-UUID

urn:schemas-upnp-org:device:deviceType:ver
or
urn:domain-name:device:deviceType:ver

uuid:device-UUID (for root device UUID)


uuid:device-UUID::urn:schemas-upnp-org:device:deviceType:ver (of
root device)
or
uuid:device-UUID::urn:domain-name:device:deviceType:ver

Two discovery messages for each embedded device.

Table 1-2:

Embedded device discovery messages

NT

USN *

uuid:device-UUID **

uuid:device-UUID

urn:schemas-upnp-org:device:deviceType:ver
or
urn:domain-name:device:deviceType:ver

uuid:device-UUID::urn:schemas-upnp-org:device:deviceType:ver
or
uuid:device-UUID::urn:domain-name:device:deviceType:ver

Once for each service t ype in each device.

Table 1-3:

Service discovery messages

NT

USN *

urn:schemas-upnp-org:service:serviceType:ver
or
urn:domain-name:service:serviceType:ver

uuid:device-UUID::urn:schemas-upnp-org:service:serviceType:ver
or
uuid:device-UUID::urn:domain-name:service:serviceType:ver

Not e t hat t he prefix of t he USN header field (before t he double colon) MUST mat ch t he value of t he UDN element in t he device

descript ion. (Sect ion 2, Descript ion explains t he UDN element .)


**

Not e t hat t he field value of t his NT header field MUST mat ch t he value of t he UDN element in t he device descript ion.

If a root device has d embedded devices and s embedded services but only k dist inct service t ypes, t his works out t o 3+2d+k
request s. If a part icular device or embedded device cont ains mult iple inst ances of a part icular service t ype, it is only necessary
t o advert ise t he service t ype once (rat her t han once for each inst ance). Not e t hat if t wo embedded devices cont ain a service of
t he same service t ype, t hese services MUST st ill be separat ely announced. This advert ises t he full ext ent of t he device's
capabilit ies t o int erest ed cont rol point s. These messages MUST be sent out as a series wit h roughly comparable expirat ion t imes;
order is unimport ant , but refreshing or canceling individual messages is PROHIBITED.

Updat ed UPnP device and service t ypes are REQUIRED t o be fully backward compat ible wit h previous versions of t he same t ype.
Devices MUST advert ise t he highest support ed version of each support ed t ype. For example, if a device support s version 2 of t he
Audio service, it would advert ise only version 2, even t hough it also support s version 1. It MUST NOT advert ise addit ional
support ed versions. Cont rol point s t hat support a given version of a device or service are able t o also int eract wit h higher

20

versions because of t his backward compat ibilit y requirement , but only using t he funct ionalit y t hat was defined in t he lower
version. For example, if a cont rol point support s only version 1 of t he Audio service, and a device advert ises t hat it support s
version 2 of t he Audio service, t he cont rol point MUST recognize t he device and be able t o use it .

Choosing an appropriat e durat ion for advert isement s is a balance bet ween minimizing net work t raffic and maximizing freshness
of device st at us. Relat ively short durat ions close t o t he minimum of 1800 seconds will ensure t hat cont rol point s have current
device st at us at t he expense of addit ional net work t raffic; longer durat ions, say on t he order of a day, compromise freshness of
device st at us but can significant ly reduce net work t raffic. Generally, device vendors should choose a value t hat corresponds t o
expect ed device usage: short durat ions for devices t hat are expect ed t o be part of t he net work for short periods of t ime, and
significant ly longer durat ions for devices expect ed t o be long-t erm members of t he net work. Devices t hat frequent ly connect t o
and leave t he net work (such as mobile wireless devices) SHOULD use a short er durat ion so t hat cont rol point s have a more
accurat e view of t heir availabilit y. Advert isement s in a set (bot h init ial and subsequent ) SHOULD have comparable durat ions.
Advert isement s in t he init ial set SHOULD be sent as quickly as possible. Subsequent refreshment s of t he advert isement s MAY be
spread over t ime rat her t han being sent as a group.

Spreading refreshment s of advert isement s over t ime rat her t han being sent as a group improves reliabilit y in case t here are
net work glit ches: wit hout increasing t he t ot al net work load it increases t he frequency of sending announcement s from devices t o
cont rol point s. The t wo figures below show t he announcement behavior wit hout spreading and wit h spreading t he messages over
t he ent ire int erval. The figures show a t imeline from t he moment a device j oins t he net work, sends it s init ial announcement s
(represent ed by vert ical lines), and subsequent ly periodically sends repeat announcement s. In t he second figure, t hese repeat
announcement s are spread over t he ent ire period rat her t han sent as a bunch.

Figure 1-3:

Initial and repeat announcements, no announcement spreading

Figure 1-4:

Initial and repeat announcements, message spreading of repeat announcements

Devices SHOULD wait a random int erval (e.g. bet ween 0 and 100milliseconds) before sending an init ial set of advert isement s in
order t o reduce t he likelihood of net work st orms; t his random int erval SHOULD also be applied on occasions where t he device
obt ains a new IP address or a new UPnP-enabled int erface is inst alled.

Due t o t he unreliable nat ure of UDP, devices SHOULD send t he ent ire set of discovery messages more t han once wit h some delay
bet ween set s e.g. a few hundred milliseconds. To avoid net work congest ion discovery messages SHOULD NOT be sent more t han
t hree t imes. In addit ion, t he device MUST re-send it s advert isement s periodically prior t o expirat ion of t he durat ion specified in

21

t he CACHE-CONTROL header field; it is RECOMMENDED t hat such refreshing of advert isement s be done at a randomly-dist ribut ed
int erval of less t han one-half of t he advert isement expirat ion t ime, so as t o provide t he opport unit y for recovery from lost
advert isement s before t he advert isement expires, and t o dist ribut e over t ime t he advert isement refreshment of mult iple devices
on t he net work in order t o avoid spikes in net work t raffic. Not e t hat UDP packet s are also bounded in lengt h (perhaps as small as
512 Byt es in some implement at ions); each discovery message MUST fit ent irely in a single UDP packet . There is no guarant ee t hat
t he above 3+2d+k messages will arrive in a part icular order.

A mult i-homed device MUST perform t he above announcement procedures on each of it s UPnP-enabled int erfaces.
Advert isement s sent on mult iple UPnP-enabled int erfaces MUST cont ain t he same field values except for t he HOST, CACHECONTROL and LOCATION header fields. The HOST field value of an advert isement MUST be t he st andard mult icast address
specified for t he prot ocol (IPv4 or IPv6) used on t he int erface. The URL specified by t he LOCATION header field MUST be
reachable on t he int erface on which t he advert isement is sent . Finally, advert isement s sent on different int erfaces MAY have
different CACHE-CONTROL field values and MAY be sent wit h different frequencies.

When a device is added t o t he net work, it MUST send a mult icast message wit h met hod NOTIFY and ssdp:alive in t he NTS header
field in t he following format . Values in it alics are placeholders for act ual values.

NOTIFY * HTTP/1.1
HOST: 239.255.255.250:1900
CACHE-CONTROL: max-age = seconds until advertisement expires
LOCATION: URL for UPnP description for root device
NT: notification type
NTS: ssdp:alive
SERVER: OS/version UPnP/1.1 product/version
USN: composite identifier for the advertisement
BOOTID.UPNP.ORG: number increased each time device sends an initial announce or an update
message
CONFIGID.UPNP.ORG: number used for caching description information
SEARCHPORT.UPNP.ORG: number identifies port on which device responds to unicast M-SEARCH

Not e: No body is sent for messages wit h met hod NOTIFY, but not e t hat t he message MUST have a blank line following t he last
header field.

The TTL for t he IP packet SHOULD default t o 2 and SHOULD be configurable.

List ed below are det ails for t he request line and header fields appearing in t he list ing above. Field names are not case sensit ive.
All field values are case sensit ive except where not ed.
Request line
Must be NOTIFY * HTTP/ 1.1
NOTIFY
Met hod for sending not ificat ions and event s.
*
Message applies generally and not t o a specific resource. MUST be *.
HTTP/ 1.1
HTTP version.

22

Header fields
HOST
REQUIRED. Field value cont ains mult icast address and port reserved for SSDP by Int ernet Assigned Numbers Aut horit y (IANA).
MUST be 239.255.255.250:1900. If t he port number ( :1900 ) is omit t ed, t he receiver MUST assume t he default SSDP port
number of 1900.
CACHE-CONTROL
REQUIRED. Field value MUST have t he max-age direct ive ( max-age= ) followed by an int eger t hat specifies t he number of
seconds t he advert isement is valid. Aft er t his durat ion, cont rol point s SHOULD assume t he device (or service) is no longer
available; as long as a cont rol point has received at least one advert isement t hat is st ill valid from a root device, any of it s
embedded devices or any of it s services, t hen t he cont rol point can assume t hat all are available. The number of seconds
SHOULD be great er t han or equal t o 1800 seconds (30 minut es), alt hough except ions are defined in t he t ext above. Specified
by UPnP vendor. Ot her direct ives MUST NOT be sent and MUST be ignored when received.
LOCATION
REQUIRED. Field value cont ains a URL t o t he UPnP descript ion of t he root device. Normally t he host port ion cont ains a
lit eral IP address rat her t han a domain name in unmanaged net works. Specified by UPnP vendor. Single absolut e URL (see
RFC 3986).
NT
REQUIRED. Field value cont ains Not ificat ion Type. MUST be one of t he following. (See Table 1-1, Root device discovery
messages , Table 1-2, Embedded device discovery messages , and Table 1-3, Service discovery messages above.) Single
URI.
upnp:rootdevice
Sent once for root device.
uuid:device-UUID
Sent once for each device, root or embedded, where device-UUID is specified by t he UPnP vendor. See
sect ion 1.1.4, UUID format and RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format .
urn:schemas-upnp-org:device:deviceType:ver
Sent once for each device, root or embedded, where deviceType and ver are defined by UPnP Forum working
commit t ee, and ver specifies t he version of t he device t ype.
urn:schemas-upnp-org:service:serviceType:ver
Sent once for each service where serviceType and ver are defined by UPnP Forum working commit t ee and ver
specifies t he version of t he service t ype.
urn:domain-name:device:deviceType:ver
Sent once for each device, root or embedded, where domain-name is a Vendor Domain Name, deviceType and ver
are defined by t he UPnP vendor, and ver specifies t he version of t he device t ype. Period charact ers in t he Vendor
Domain Name MUST be replaced wit h hyphens in accordance wit h RFC 2141.
urn:domain-name:service:serviceType:ver
Sent once for each service where domain-name is a Vendor Domain Name, serviceType and ver are defined by
UPnP vendor, and ver specifies t he version of t he service t ype. Period charact ers in t he Vendor Domain Name
MUST be replaced wit h hyphens in accordance wit h RFC 2141.
NTS
REQUIRED. Field value cont ains Not ificat ion Sub Type. MUST be ssdp:alive. Single URI.
SERVER
REQUIRED. Specified by UPnP vendor. St ring. Field value MUST begin wit h t he following product t okens (defined by
HTTP/ 1.1). The first product t oken ident ifes t he operat ing syst em in t he form OS name/ OS version, t he second t oken
represent s t he UPnP version and MUST be UPnP/ 1.1, and t he t hird t oken ident ifes t he product using t he form
product name/ product version. For example, SERVER: unix/ 5.1 UPnP/ 1.1 MyProduct / 1.0 . Cont rol point s MUST be
prepared t o accept a higher minor version number of t he UPnP version t han t he cont rol point it self implement s. For
example, cont rol point s implement ing UDA version 1.0 will be able t o int eroperat e wit h devices implement ing
UDA version 1.1.
USN
REQUIRED. Field value cont ains Unique Service Name. Ident ifies a unique inst ance of a device or service. MUST be one of
t he following. (See Table 1-1, Root device discovery messages , Table 1-2, Embedded device discovery messages ,
and Table 1-3, Service discovery messages above.) The prefix (before t he double colon) MUST mat ch t he value of t he UDN
element in t he device descript ion. (Sect ion 2, Descript ion explains t he UDN element .) Single URI.
uuid:device-UUID::upnp:rootdevice
Sent once for root device where device-UUID is specified by UPnP vendor. See sect ion 1.1.4, UUID format and
RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format .

23

uuid:device-UUID
Sent once for every device, root or embedded, where device-UUID is specified by t he UPnP vendor. See
sect ion 1.1.4, UUID format and RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format .
uuid:device-UUID::urn:schemas-upnp-org:device:deviceType:ver
Sent once for every device, root or embedded, where device-UUID is specified by t he UPnP vendor, deviceType
and ver are defined by UPnP Forum working commit t ee and ver specifies version of t he device t ype. See
sect ion 1.1.4, UUID format and RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format .
uuid:device-UUID::urn:schemas-upnp-org:service:serviceType:ver
Sent once for every service where device-UUID is specified by t he UPnP vendor, serviceType and ver are defined
by UPnP Forum working commit t ee and ver specifies version of t he device t ype. See sect ion 1.1.4, UUID format
and RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format .
uuid:device-UUID::urn:domain-name:device:deviceType:ver
Sent once for every device, root or embedded, where device-UUID, domain-name (a Vendor Domain Name),
deviceType and ver are defined by t he UPnP vendor and ver specifies t he version of t he device t ype. See
sect ion 1.1.4, UUID format and RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format . Period
charact ers in t he Vendor Domain Name MUST be replaced by hyphens in accordance wit h RFC 2141.
uuid:device-UUID::urn:domain-name:service:serviceType:ver
Sent once for every service where device-UUID, domain-name (a Vendor Domain Name), serviceType and ver are
defined by t he UPnP vendor and ver specifies t he version of t he service t ype. See sect ion 1.1.4, UUID format and
RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format . Period charact ers in t he Vendor Domain
Name MUST be replaced by hyphens in accordance wit h RFC 2141.
BOOTID.UPNP.ORG
REQUIRED. The BOOTID.UPNP.ORG header field represent s t he boot inst ance of t he device expressed according t o a
monot onically increasing value. It s field value MUST be a non-negat ive 31-bit int eger; ASCII encoded, decimal, wit hout
leading zeros (leading zeroes, if present , MUST be ignored by t he recipient ) t hat MUST be increased on each init ial announce
of t he UPnP device or MUST be t he same as t he field value of t he NEXTBOOTID.UPNP.ORG header field in t he last sent SSDP
updat e message. It s field value MUST remain t he same on all periodically repeat ed announcement s. A convenient
mechanism is t o set t his field value t o t he t ime t hat t he device sends it s init ial announcement , expressed as seconds
elapsed since midnight January 1, 1970; for devices t hat have a not ion of t ime, t his will not require any addit ional st at e t o
remember or be flashed . However, it is perfect ly accept able t o use a simple boot count er t hat is increment ed on every
init ial announcement as a field value of t his header field. As such, cont rol point s MUST NOT view t his header field as a
t imest amp. The BOOTID.UPNP.ORG header field MUST be included in al l announcement s of a root device, it s embedded
devices and it s services. Unless t he device explicit ly updat es it s value by sending an SSDP updat e message, as long as t he
device remains available in t he net work, t he same BOOTID.UPNP.ORG field value MUST be used in all announcement s,
search responses, updat e messages and event ually bye-bye messages.
Cont rol point s can use t his header field t o det ect t he case when a device leaves and rej oins t he net work ( reboot s in UPnP
t erms). It can be used by cont rol point s for a number of purposes such as re-est ablishing desired event subscript ions,
checking for changes t o t he device st at e t hat were not event ed since t he device was off-line.
CONFIGID.UPNP.ORG
REQUIRED. The CONFIGID.UPNP.ORG field value MUST be a non-negat ive, 31-bit int eger, ASCII encoded, decimal, wit hout
leading zeros (leading zeroes, if present , MUST be ignored by t he recipient ) t hat MUST represent t he configurat ion number
of a root device. UPnP 1.1 devices MAY freely assign configid numbers from 0 t o 16777215 (2^24-1). Higher numbers are
reserved for fut ure use, and can be assigned by t he Technical Commit t ee. The configuration of a root device consist s of t he
following informat ion: t he DDD of t he root device and all it s embedded devices, and t he SCPDs of all t he cont ained services.
If any part of t he configurat ion changes, t he CONFIGID.UPNP.ORG field value MUST be changed. The CONFIGID.UPNP.ORG
header field MUST be included in all announcement s of a root device, it s embedded devices and it s services. The
configurat ion number t hat is present in a CONFIGID.UPNP.ORG field value MUST sat isfy t he following rule:
-

if a device sends out t wo messages wit h a CONFIGID.UPNP.ORG header field wit h t he same field value K, t he
configuration MUST be t he same at t he moment s t hat t hese messages were sent .

Whenever a cont rol point receives a CONFIGID.UPNP.ORG header field wit h a field value K, and subsequent ly downloads t he
configurat ion informat ion, t his configurat ion informat ion is associat ed wit h K. As an addit ional safeguard, t he device MUST
include a configId at t ribut e wit h value K in t he ret urned descript ion (see sect ion 2, Descript ion ). The following caching
rules for cont rol point s supersede t he caching rules t hat are defined in UPnP 1.0:
-

Cont rol point s MAY ignore t he CONFIGID.UPNP.ORG header field and use t he caching rules t hat are based on
advert isement expirat ions as defined in Chapt er 2, Descript ion: as long as at least one of t he discovery advert isement s
from a root device, it s embedded devices and it s services have not expired, a cont rol point MAY assume t hat t he root
device and all it s embedded devices and all it s services are available. The device and service descript ions MAY be
ret rieved at any point since t he device and service descript ions are st at ic as long as t he device and it s services are
available.

24

If no configurat ion number is included in a received SSDP message, cont rol point s SHOULD cache based on
advert isement expirat ions as defined in Chapt er 2 Descript ion.

If a CONFIGID.UPNP.ORG header field wit h field value K is included in a received SSDP message, and a cont rol point has
already cached informat ion associat ed wit h field value K, t he cont rol point MAY use t his cached informat ion as t he
current configurat ion of t he device. Ot herwise, a cont rol point SHOULD assume it has not cached t he current
configurat ion of t he device and needs t o send new descript ion query messages.

The CONFIGID.UPNP.ORG header field reduces peak loads on UPnP devices during st art up and during net work hiccups. Only
if a cont rol point receives an announcement of an unknown configurat ion is downloading required.
SEARCHPORT.UPNP.ORG
OPTIONAL. If a device does not send t he SEARCHPORT.UPNP.ORG header field, it MUST respond t o unicast M-SEARCH
messages on port 1900. Only if port 1900 is unavailable MAY a device select a different port t o respond t o unicast M-SEARCH
messages. If a device sends t he SEARCHPORT.UPNP.ORG header field, it s field value MUST be an ASCII encoded int eger,
decimal, wit hout leading zeros (leading zeroes, if present , MUST be ignored by t he recipient ), in t he range 49152-65535
(RFC 4340). The device MUST respond t o unicast M-SEARCH messages t hat are sent t o t he advert ised port .
Not e: No responses are sent for messages wit h met hod NOTIFY.

1.2.3 Device unavailable -- NOTIFY with ssdp:byebye


When a device and it s services are going t o be removed from t he net work, t he device SHOULD mult icast an ssdp:byebye message
corresponding t o each of t he ssdp:alive messages it mult icast ed t hat have not already expired. If t he device is removed abrupt ly
from t he net work, it might not be possible t o mult icast a message. As a fallback, discovery messages MUST include an expirat ion
value in a CACHE-CONTROL field value (as explained above); if not re-advert ised, t he discovery message event ually expires on it s
own.

(Not e: when a cont rol point is about t o be removed from t he net work, no discovery-relat ed act ion is required.)

When a device is about t o be removed from t he net work, it SHOULD explicit ly revoke it s discovery messages by sending one
mult icast message for each ssdp:alive message it sent . Each mult icast message MUST have met hod NOTIFY and ssdp:byebye in
t he NTS header field in t he following format . Values in it alics are placeholders for act ual values.

When a mult i-homed device is about t o be removed from t he net work on one or more of it s UPnP-enabled int erfaces, it SHOULD
explicit ly revoke it s discovery messages by sending one mult icast message for each ssdp:alive message it has previously sent on
t hose int erfaces and IP addresses. It MUST NOT send such mult icast messages t o any of t he UPnP-enabled int erfaces t hat remain
available.

When ssdp:byebye messages are sent on mult iple UPnP-enabled int erfaces, t he messages MUST cont ain ident ical field values
except for t he HOST field value. The HOST field value of an advert isement MUST be t he st andard mult icast address specified for
t he prot ocol (IPv4 or IPv6) used on t he int erface.

NOTIFY * HTTP/1.1
HOST: 239.255.255.250:1900
NT: notification type
NTS: ssdp:byebye
USN: composite identifier for the advertisement
BOOTID.UPNP.ORG: number increased each time device sends an initial announce or an update
message
CONFIGID.UPNP.ORG: number used for caching description information

25

Not e: No body is present for messages wit h met hod NOTIFY, but not e t hat t he message MUST have a blank line following t he last
header field.

The TTL for t he IP packet SHOULD default t o 2 and SHOULD be configurable.

List ed below are det ails for t he request line and header fields appearing in t he list ing above. Field names are not case sensit ive.
All field values are case sensit ive except where not ed.
Request line
Must be NOTIFY * HTTP/ 1.1
NOTIFY
Met hod for sending not ificat ions and event s.
*
Message applies generally and not t o a specific resource. MUST be *.
HTTP/ 1.1
HTTP version.

Header fields
HOST
REQUIRED. Field value cont ains mult icast address and port reserved for SSDP by Int ernet Assigned Numbers Aut horit y (IANA).
MUST be 239.255.255.250:1900. If t he port number ( :1900 ) is omit t ed, t he receiver MUST assume t he default SSDP port
number of 1900.
NT
REQUIRED. Field value cont ains Not ificat ion Type. (See list of required field values for t he NT header field in NOTIFY wit h
ssdp:alive above.) Single URI.
NTS
REQUIRED. Field value cont ains Not ificat ion Sub Type. MUST be ssdp:byebye. Single URI.
USN
REQUIRED. Field value cont ains Unique Service Name. (See list of required field values for t he USN header field in NOTIFY
wit h ssdp:alive above.) Single URI.
BOOTID.UPNP.ORG
REQUIRED. As defined in sect ion 1.2, and 1.2.2.
CONFIGID.UPNP.ORG
REQUIRED. As defined in sect ion 1.2, and 1.2.2.
Not e: No responses are sent for messages wit h met hod NOTIFY.

If a cont rol point has received at least one ssdp:byebye message of a root device, any of it s embedded devices or any of it s
services t hen t he cont rol point can assume t hat all are no longer available. As a fallback, if a cont rol point fails t o receive
not ificat ion t hat a root device, it s embedded devices and it s services are unavailable, t he original discovery messages will
event ually expire yielding t he same effect . Only when all original advert isement s of a root device, it s embedded devices and it s
services have expired can a cont rol point assume t hat t hey are no longer available.

26

If a mult i-homed cont rol point has received at least one ssdp:byebye message of a root device, any of it s embedded devices or
any of it s services on one of it s UPnP-enabled int erfaces t hen t he cont rol point can assume t hat all are no longer available on
t hat UPnP-enabled int erface. However, t he cont rol point MUST NOT assume t hat t he device is also no longer available on all of
it s ot her UPnP-enabled int erfaces. As a fallback, if a cont rol point fails t o receive not ificat ion t hat a root device, it s embedded
devices and it s services are unavailable on a part icular UPnP-enabled int erface, t he original discovery messages will event ually
expire yielding t he same effect . Only when all original advert isement s of a root device, it s embedded devices and it s services
received on a UPnP-enabled int erface have expired can a cont rol point assume t hat t hey are no longer available on t hat int erface
or IP address.

1.2.4 Device Update NOTIFY with ssdp:update


When a new UPnP-enabled int erface is added t o a mult i-homed device, t he device MUST increase it s BOOTID.UPNP.ORG field
value, mult icast an ssdp:update message for each of t he root devices, embedded devices and embedded services t o all of t he
exist ing UPnP-enabled int erfaces t o announce a change in t he BOOTID.UPNP.ORG field value, and re-advert ise it self on all
(exist ing and new) UPnP-enabled int erfaces wit h t he new BOOTID.UPNP.ORG field value. Similarly, if a mult i-homed device loses
connect ivit y on a UPnP-enabled int erface and regains connect ivit y, or if t he IP address on one of t he UPnP-enabled int erfaces
changes, t he device MUST increase t he BOOTID.UPNP.ORG field value, mult icast an ssdp:update message for each of t he root
devices, embedded devices and embedded services t o all t he unaffect ed UPnP-enabled int erfaces t o announce a change in t he
BOOTID.UPNP.ORG field value, and re-advert ise it self on all (affect ed and unaffect ed) UPnP-enabled int erfaces wit h t he new
BOOTID.UPNP.ORG field value. In all cases ,t he ssdp:update message for t he root devices MUST be sent as soon as possible.
Ot her ssdp:update messages SHOULD be spread over t ime. However, all ssdp:update messages MUST be sent before any
announcement messages wit h t he new BOOTID.UPNP.ORG field value can be sent .

When ssdp:update messages are sent on mult iple UPnP-enabled int erfaces, t he messages MUST cont ain ident ical field values
except for t he HOST and LOCATION field values. The HOST field value of an advert isement MUST be t he st andard mult icast
address specified for t he prot ocol (IPv4 or IPv6) used on t he int erface. The URL specified in t he LOCATION field value MUST be
reachable on t he int erface on which t he advert isement is sent .

NOTIFY * HTTP/1.1
HOST: 239.255.255.250:1900
LOCATION: URL for UPnP description for root device
NT: notification type
NTS: ssdp:update
USN: composite identifier for the advertisement
BOOTID.UPNP.ORG: BOOTID value that the device has used in its previous announcements
CONFIGID.UPNP.ORG: number used for caching description information
NEXTBOOTID.UPNP.ORG: new BOOTID value that the device will use in subsequent announcements
SEARCHPORT.UPNP.ORG: number identifies port on which device responds to unicast M-SEARCH

Not e: No body is present for messages wit h met hod NOTIFY, but not e t hat t he message MUST have a blank line following t he last
header field.

27

The TTL for t he IP packet SHOULD default t o 2 and SHOULD be configurable.

List ed below are det ails for t he request line and header fields appearing in t he list ing above. Field names are not case sensit ive.
All field values are case sensit ive except where not ed.
Request line
Must be NOTIFY * HTTP/ 1.1
NOTIFY
Met hod for sending not ificat ions and event s.
*
Message applies generally and not t o a specific resource. MUST be *.
HTTP/ 1.1
HTTP version.

Header fields
HOST
REQUIRED. Field value cont ains mult icast address and port reserved for SSDP by Int ernet Assigned Numbers Aut horit y (IANA).
MUST be 239.255.255.250:1900. If t he port number ( :1900 ) is omit t ed, t he receiver MUST assume t he default SSDP port
number of 1900.
LOCATION
REQUIRED. Field value MUST be t he same as t he LOCATION field value t hat has been sent in previous SSDP messages. Single
absolut e URL (see RFC 3986).
NT
REQUIRED. Field value cont ains Not ificat ion Type. (See list of required field values for t he NT header field in NOTIFY wit h
ssdp:alive above.) Single URI.
NTS
REQUIRED. Field value cont ains Not ificat ion Sub Type. MUST be ssdp:updat e. Single URI.
USN
REQUIRED. Field value cont ains Unique Service Name. (See list of required field values for t he USN header field in NOTIFY
wit h ssdp:alive above.) Single URI.
BOOTID.UPNP.ORG
REQUIRED. As defined in sect ion 1.2, and 1.2.2, Field value MUST be t he same as t he BOOTID.UPNP.ORG field value t hat has
been sent in previous SSDP messages.
CONFIGID.UPNP.ORG
REQUIRED. As defined in sect ion 1.2, and 1.2.2.
NEXTBOOTID.UPNP.ORG
REQUIRED. Field value cont ains t he new BOOTID.UPNP.ORG field value t hat t he device int ends t o use in t he subsequent
device and service announcement messages. It s field value MUST be a non-negat ive 31-bit int eger; ASCII encoded, decimal,
wit hout leading zeros (leading zeroes, if present , MUST be ignored by t he recipient ) and MUST be great er t han t he field
value of t he BOOTID.UPNP.ORG header field.
SEARCHPORT.UPNP.ORG
OPTIONAL. As defined in sect ion 1.2, and 1.2.2.
Not e: No responses are sent for messages wit h met hod NOTIFY.

If a cont rol point wit h a single UPnP-enabled int erface receives an ssdp:update message, t he NEXTBOOTID.UPNP.ORG field value
replaces t he BOOTID.UPNP.ORG field value t hat t he cont rol point has previously recorded for t he device. It can expect fut ure
announcement s, search responses, updat e messages and event ually bye-bye messages from t he device t o cont ain t he new
BOOTID.UPNP.ORG field value (t hat is: t he field value of t he NEXTBOOTID.UPNP.ORG header field in t he received ssdp:update

28

message). The field value in t he NEXTBOOTID.UPNP.ORG header field MUST be recorded as t he current BOOTID.UPNP.ORG field
value of t he device which is t o be expect ed on all subsequent SSDP messages.

If a mult i-homed cont rol point receives an ssdp:update message on it s UPnP-enabled int erface(s), and t he message arrives on
t he int erface(s) t hat it uses for UPnP communicat ions wit h t he device (such as event subscript ions), it can assume t hat t he
device has remained cont inuously available (including all device st at e), and t hat t he NEXTBOOTID.UPNP.ORG field value replaces
t he BOOTID.UPNP.ORG field value t hat t he cont rol point has previously recorded for t he device. It can expect fut ure
announcement s, search responses, updat e messages and event ually bye-bye messages from t he device t o cont ain t he new
BOOTID.UPNP.ORG field value (t hat is: t he field value of t he NEXTBOOTID.UPNP.ORG header field in t he received ssdp:update
message). The field value in t he NEXTBOOTID.UPNP.ORG header field MUST be recorded as t he current BOOTID.UPNP.ORG field
value of t he device which is t o be expect ed on all subsequent SSDP messages.

If a cont rol point receives an SSDP message wit h a BOOTID.UPNP.ORG field value different (eit her higher or lower) from t he value
t hat t he cont rol point has previously recorded for t he device,it can assume t hat t he device has become t emporarily unavailable
on t hat int erface and has become available again, and any st ored st at e informat ion about t he device has become invalid. It MUST
t reat t he device as a newly discovered device.

1.3 Search
When a cont rol point is added t o t he net work, t he UPnP discovery prot ocol allows t hat cont rol point t o search for devices of
int erest on t he net work. It does t his by mult icast ing on t he reserved address and port (239.255.255.250:1900) a search message
wit h a pat t ern, or t arget , equal t o a t ype or ident ifier for a device or service. Responses from devices cont ain discovery messages
essent ially ident ical t o t hose advert ised by newly connect ed devices; t he former are unicast while t he lat t er are mult icast .
Cont rol point s can also send a unicast search message t o a known IP address and port 1900 or t he port indicat ed by
SEARCHPORT.UPNP.ORG, t o verify t he exist ence of UPnP device(s) and service(s) at t he IP address. For example, a unicast
search may be used t o quickly check whet her a known UPnP device or service is st ill available on t he net work. Mult i-homed
cont rol point s MAY choose t o send discovery messages on any, some or all of it s UPnP-enabled int erfaces.

1.3.1 Search protocols and standards


To search for devices (and be discovered by cont rol point s), cont rol point s (and devices) use t he following subset of t he overall
UPnP prot ocol st ack. (The overall UPnP prot ocol st ack is list ed at t he beginning of t his document .)

29

Figure 1-5:

Search protocol stack


UPnP vendor [purple-it alic]
UPnP Forum [red-it al ic]
UPnP Device Architecture [green-bold]
SSDP [blue]
UDP [black]
IP [black]

At t he highest layer, search messages cont ain vendor-specific informat ion, e.g., t he cont rol point , device, and service ident ifiers.
Moving down t he st ack, vendor cont ent is supplement ed by informat ion from a UPnP Forum working commit t ee, e.g., device or
service t ypes. Messages from t he layers above are host ed in UPnP-specific prot ocols, defined in t his document . In t urn, search
request s are delivered via mult icast and unicast SSDP messages defined in t his document . Search responses are delivered via a
unicast SSDP messages defined in t his document . Bot h kinds of messages are delivered via UDP over IP. For reference, colors in
[square bracket s] above indicat e which prot ocol defines specific header fields and field values in discovery messages list ed below.

1.3.2 Search request with M-SEARCH


When a cont rol point desires t o search t he net work for devices, it MUST send a mult icast request wit h met hod M-SEARCH in t he
following format . Cont rol point s t hat know t he address of a specific device MAY also use a similar format t o send unicast request s
wit h met hod M-SEARCH.

For mult icast M-SEARCH, t he message format is defined below. Values in it alics are placeholders for act ual values.

M-SEARCH * HTTP/1.1
HOST: 239.255.255.250:1900
MAN: "ssdp:discover"
MX: seconds to delay response
ST: search target
USER-AGENT: OS/version UPnP/1.1 product/version

Not e: No body is present in request s wit h met hod M-SEARCH, but not e t hat t he message MUST have a blank line following t he
last header field.

Not e: The TTL for t he IP packet SHOULD default t o 2 and SHOULD be configurable.

List ed below are det ails for t he request line and header fields appearing in t he list ing above. Field names are not case sensit ive.
All field values are case sensit ive except where not ed.
Request line
Must be M-SEARCH * HTTP/1.1
M-SEARCH
Met hod for search request s.

30

*
Request applies generally and not t o a specific resource. MUST be *.
HTTP/ 1.1
HTTP version.
Header fields
HOST
REQUIRED. Field value cont ains t he mult icast address and port reserved for SSDP by Int ernet Assigned Numbers Aut horit y
(IANA). MUST be 239.255.255.250:1900.
MAN
REQUIRED by HTTP Ext ension Framework. Unlike t he NTS and ST field values, t he field value of t he MAN header field is
enclosed in double quot es; it defines t he scope (namespace) of t he ext ension. MUST be "ssdp:discover".
MX
REQUIRED. Field value cont ains maximum wait t ime in seconds. MUST be great er t han or equal t o 1 and SHOULD be less t han
5 inclusive. Device responses SHOULD be delayed a random durat ion bet ween 0 and t his many seconds t o balance load for
t he cont rol point when it processes responses. This value MAY be increased if a large number of devices are expect ed t o
respond. The MX field value SHOULD NOT be increased t o accommodat e net work charact erist ics such as lat ency or
propagat ion delay (for more det ails, see t he explanat ion below). Specified by UPnP vendor. Int eger.
ST
REQUIRED. Field value cont ains Search Target . MUST be one of t he following. (See NT header field in NOTIFY wit h ssdp:alive
above.) Single URI.
ssdp:all
Search for all devices and services.
upnp:rootdevice
Search for root devices only.
uuid:device-UUID
Search for a part icular device. device-UUID specified by UPnP vendor. See sect ion 1.1.4, UUID format and
RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format .
urn:schemas-upnp-org:device:deviceType:ver
Search for any device of t his t ype where deviceType and ver are defined by t he UPnP Forum working commit t ee.
urn:schemas-upnp-org:service:serviceType:ver
Search for any service of t his t ype where serviceType and ver are defined by t he UPnP Forum working commit t ee.
urn:domain-name:device:deviceType:ver
Search for any device of t his t ypewhere domain-name (a Vendor Domain Name), deviceType and ver are defined
by t he UPnP vendor and ver specifies t he highest specifies t he highest support ed version of t he device t ype.
Period charact ers in t he Vendor Domain Name MUST be replaced wit h hyphens in accordance wit h RFC 2141.
urn:domain-name:service:serviceType:ver
Search for any service of t his t ype. Where domain-name (a Vendor Domain Name), serviceType and ver are
defined by t he UPnP vendor and ver specifies t he highest specifies t he highest support ed version of t he service
t ype. Period charact ers in t he Vendor Domain Name MUST be replaced wit h hyphens in accordance wit h RFC 2141.
USER-AGENT
OPTIONAL. Specified by UPnP vendor. St ring. Field value MUST begin wit h t he following product t okens (defined by
HTTP/ 1.1). The first product t oken ident ifes t he operat ing syst em in t he form OS name/ OS version, t he second t oken
represent s t he UPnP version and MUST be UPnP/ 1.1, and t he t hird t oken ident ifes t he product using t he form
product name/ product version. For example, USER-AGENT: unix/ 5.1 UPnP/ 1.1 MyProduct / 1.0 . Cont rol point s MUST be
prepared t o accept a higher minor version number of t he UPnP version t han t he cont rol point it self implement s. For
example, cont rol point s implement ing UDA version 1.0 will be able t o int eroperat e wit h devices implement ing
UDA version 1.1.
For unicast M-SEARCH, t he message format is defined below. Values in it alics are placeholders for act ual values.

M-SEARCH * HTTP/1.1
HOST: hostname:portNumber
MAN: "ssdp:discover"
ST: search target
USER-AGENT: OS/version UPnP/1.1 product/version

31

Not e: No body is present in request s wit h met hod M-SEARCH, but not e t hat t he message MUST have a blank line following t he
last header field.

List ed below are det ails for t he request line and header fields appearing in t he list ing above. Field names are not case sensit ive.
All field values are case sensit ive except where not ed.
Request line
Must be M-SEARCH * HTTP/ 1.1
M-SEARCH
Met hod for search request s.
*
Request applies generally and not t o a specific resource. MUST be *.
HTTP/ 1.1
HTTP version.
Header fields
HOST
REQUIRED. For unicast request s, t he field value MUST be t he domain name or IP address of t he t arget device and eit her port
1900 or t he SEARCHPORT provided by t he t arget device.
MAN
REQUIRED by HTTP Ext ension Framework. Unlike t he NTS and ST field values, t he field value of t he MAN header field is
enclosed in double quot es; it defines t he scope (namespace) of t he ext ension. MUST be "ssdp:discover".
ST
REQUIRED. Field value cont ains Search Target . MUST be one of t he following. (See NT header field in NOTIFY wit h ssdp:alive
above.) Single URI.
ssdp:all
Search for all devices and services.
upnp:rootdevice
Search for root devices only.
uuid:device-UUID
Search for a part icular device. device-UUID specified by UPnP vendor. See sect ion 1.1.4, UUID format and
RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format .
urn:schemas-upnp-org:device:deviceType:ver
Search for any device of t his t ype where deviceType and ver are defined by t he UPnP Forum working commit t ee.
urn:schemas-upnp-org:service:serviceType:ver
Search for any service of t his t ype where serviceType and ver are defined by t he UPnP Forum working commit t ee.
urn:domain-name:device:deviceType:ver
Search for any device of t his t ype where domain-name (a Vendor Domain Name), deviceType and ver are defined
by t he UPnP vendor and ver specifies t he highest support ed version of t he device t ype. Period charact ers in t he
Vendor Domain Name MUST be replaced wit h hyphens in accordance wit h RFC 2141.
urn:domain-name:service:serviceType:ver
Search for any service of t his t ype where domain-name (a Vendor Domain Name), serviceType and ver are defined
by t he UPnP vendor and ver specifies t he highest support ed version of t he service t ype. Period charact ers in t he
Vendor Domain Name MUST be replaced wit h hyphens in accordance wit h RFC 2141.
USER-AGENT
OPTIONAL. Specified by UPnP vendor. St ring. Field value MUST begin wit h t he following product t okens (defined by
HTTP/ 1.1). The first product t oken ident ifes t he operat ing syst em in t he form OS name/ OS version, t he second t oken
represent s t he UPnP version and MUST be UPnP/ 1.1, and t he t hird t oken ident ifes t he product using t he form
product name/ product version. For example, USER-AGENT: unix/ 5.1 UPnP/ 1.1 MyProduct / 1.0 . Cont rol point s MUST be
prepared t o accept a higher minor version number of t he UPnP version t han t he cont rol point it self implement s. For
example, cont rol point s implement ing UDA version 1.0 will be able t o int eroperat e wit h devices implement ing
UDA version 1.1.

32

Due t o t he unreliable nat ure of UDP, cont rol point s SHOULD send each M-SEARCH message more t han once. As a fallback, t o
guard against t he possibilit y t hat a device might not receive t he M-SEARCH message from a cont rol point , a device SHOULD resend it s advert isement s periodically (see CACHE-CONTROL header field in NOTIFY wit h ssdp:alive above).

For a mult icast request , t he cont rol point SHOULD wait at least t he amount of t ime specified in t he MX header field for responses
t o arrive from devices. The random dist ribut ion of responses over t he MX int erval means t hat a responder MAY send a response at
MX seconds aft er receiving t he M-SEARCH request . The MX field value MAY be adj ust ed by heurist ics at t he request er based on,
for example, observed number of responders. Net work charact erist ics affect ing t he propagat ion of t raffic cannot be addressed
by increasing t he MX field value because of t he reason cit ed above. A request er MAY adapt t o net work charact erist ics wit h
heurist ics based on observed net work behavior (t he exact heurist ics are out of scope). The net effect is t hat t he M-SEARCH
request persist s at t he request er for a period of t ime exceeding MX such t hat t he charact erist ics of t he net work are properly
accommodat ed t o minimize lost responses.

When a device receives a unicast M-SEARCH, it SHOULD respond wit hin 1 second and it MAY respond sooner. The sender of t he
unicast request SHOULD wait at least 1 second for t he response.

Updat ed versions of device and service t ypes are REQUIRED t o be fully backward compat ible wit h previous versions. Devices
MUST respond t o M-SEARCH request s for any support ed version. For example, if a device implement s urn:schemas-upnporg:service:xyz:2 , it MUST respond t o search request s for bot h t hat t ype and urn:schemas-upnp-org:service:xyz:1 . The
response MUST specify t he same version as was cont ained in t he search request . If a cont rol point searches for a device or service
of a part icular version and receives no responses (presumably because no device present on t he net work support s t he specified
version), but is willing t o operat e using a lower version, it MAY repeat t he search request specifying t he lower version.

1.3.3 Search response


To be found by a net work search, a device MUST send a unicast UDP response t o t he source IP address and port t hat sent t he
request t o t he mult icast address. Devices respond if t he ST header field of t he M-SEARCH request is ssdp:all ,
upnp:root device , uuid: followed by a UUID t hat exact ly mat ches t he one advert ised by t he device, or if t he M-SEARCH
request mat ches a device t ype or service t ype support ed by t he device. Mult i-homed devices MUST send t he search response
using t he same UPnP-enabled int erface on which t he search request was received. The URL specified in t he LOCATION field value
MUST specify an address t hat is reachable on t hat int erface.

Devices responding t o a mult icast M-SEARCH SHOULD wait a random period of t ime bet ween 0 seconds and t he number of
seconds specified in t he MX field value of t he search request before responding, in order t o avoid flooding t he request ing cont rol
point wit h search responses from mult iple devices. If t he search request result s in t he need for a mult iple part response from t he
device, t hose mult iple part responses SHOULD be spread at random int ervals t hrough t he t ime period from 0 t o t he number of
seconds specified in t he MX header field. Devices MAY assume an MX field value less t han t hat specified in t he MX header field. If

33

t he MX header field specifies a field value great er t han 5, t he device SHOULD assume t hat it cont ained t he value 5 or less.
Devices MUST NOT st op responding t o ot her request s while wait ing t he random delay before sending a response.

For mult icast M-SEARCH request s, if t he search request does not cont ain an MX header field, t he device MUST silent ly discard and
ignore t he search request . If t he MX header field specifies a field value great er t han 5, t he device SHOULD assume t hat it
cont ained t he value 5 or less.

Any device responding t o a unicast M-SEARCH SHOULD respond wit hin 1 second.

The URL specified in t he LOCATION header field of t he M-SEARCH response MUST be reachable by t he cont rol point t o which t he
response is direct ed.

Responses t o M-SEARCH request s are int ent ionally parallel t o advert isement s, and as such, follow t he same pat t ern as list ed for
NOTIFY wit h ssdp:alive (above) except t hat inst ead of t he NT header field t here is an ST header field here. The response MUST
be sent in t he following format . Values in it alics are placeholders for act ual values.

HTTP/1.1 200 OK
CACHE-CONTROL: max-age = seconds until advertisement expires
DATE: when response was generated
EXT:
LOCATION: URL for UPnP description for root device
SERVER: OS/version UPnP/1.1 product/version
ST: search target
USN: composite identifier for the advertisement
BOOTID.UPNP.ORG: number increased each time device sends an initial announce or an update
message
CONFIGID.UPNP.ORG: number used for caching description information
SEARCHPORT.UPNP.ORG: number identifies port on which device responds to unicast M-SEARCH

Not e: No body is present in a response t o a request wit h met hod M-SEARCH, but not e t hat t he message MUST have a blank line
following t he last header field.

(Not e: No need t o limit TTL for t he IP packet in response t o a search request .)

List ed below are det ails for t he header fields appearing in t he list ing above. Field names are not case sensit ive. All field values
are case sensit ive except where not ed.
Response line
Must be HTTP/ 1.1 200 OK
Header fields
CACHE-CONTROL
REQUIRED. Field value MUST have t he max-age direct ive ( max-age= ) followed by an int eger t hat specifies t he number of
seconds t he advert isement is valid. Aft er t his durat ion, cont rol point s SHOULD assume t he device (or service) is no longer
available; as long as a cont rol point has received at least one advert isement t hat is st ill valid from a root device, any of it s
embedded devices or any of it s services, t hen t he cont rol point can assume t hat all are available. The number of seconds
SHOULD be great er t han or equal t o 1800 seconds (30 minut es), alt hough except ions are defined in t he t ext above. Specified
by UPnP vendor. Ot her direct ives MUST NOT be sent and MUST be ignored when received.

34

DATE
RECOMMENDED. Field value cont ains dat e when response was generat ed. rfc1123-dat e as defined in RFC 2616.
EXT
REQUIRED for backwards compat ibilit y wit h UPnP 1.0. (Header field name only; no field value.)
LOCATION
REQUIRED. Field value cont ains a URL t o t he UPnP descript ion of t he root device. Normally t he host port ion cont ains a
lit eral IP address rat her t han a domain name in unmanaged net works. Specified by UPnP vendor. Single absolut e URL (see
RFC 3986).
SERVER
REQUIRED. Specified by UPnP vendor. St ring. Field value MUST begin wit h t he following product t okens (defined by
HTTP/ 1.1). The first product t oken ident ifes t he operat ing syst em in t he form OS name/ OS version, t he second t oken
represent s t he UPnP version and MUST be UPnP/ 1.1, and t he t hird t oken ident ifes t he product using t he form
product name/ product version. For example, SERVER: unix/ 5.1 UPnP/ 1.1 MyProduct / 1.0 . Cont rol point s MUST be
prepared t o accept a higher minor version number of t he UPnP version t han t he cont rol point it self implement s. For
example, cont rol point s implement ing UDA version 1.0 will be able t o int eroperat e wit h devices implement ing
UDA version 1.1.
ST
REQUIRED. Field value cont ains Search Target . Single URI. The response sent by t he device depends on t he field value of t he
ST header field t hat was sent in t he request . In some cases, t he device MUST send mult iple response messages as follows. If
t he received ST field value was:
ssdp:all
Respond 3+2d+k t imes for a root device wit h d embedded devices and s embedded services but only k dist inct
service t ypes (see sect ion 1.1.2, SSDP message header fields for a definit ion of each message t o be sent ).
Field value for ST header field MUST be t he same as for t he NT header field in NOTIFY messages wit h ssdp:alive.
(See above.)
upnp:rootdevice
Respond once for root device. Must be upnp:rootdevice.
uuid:device-UUID
Respond once for each mat ching device, root or embedded. Must be uuid:device-UUID where device-UUID is
specified by t he UPnP vendor. See sect ion 1.1.4, UUID format and RECOMMENDED generat ion algorit hms for t he
MANDATORY UUID format .
urn:schemas-upnp-org:device:deviceType:ver
Respond once for each mat ching device, root or embedded. MUST be
urn:schemas-upnp-org:device:deviceType:ver where deviceType and ver are defined by UPnP Forum working
commit t ee and ver MUST cont ain t he version of t he device t ype cont ained in t he M-SEARCH request .
urn:schemas-upnp-org:service:serviceType:ver
Respond once for each mat ching service t ype. MUST be urn: schemas-upnp-org:service:serviceType:ver where
serviceType and ver are defined by t he UPnP Forum working commit t ee and ver MUST cont ain t he version of t he
service t ype cont ained in t he M-SEARCH request .
urn:domain-name:device:deviceType:ver
Respond once for each mat ching device, root or embedded. MUST be urn:domain-name:device:deviceType:ver
where domain-name (a Vendor Domain Name), deviceType and ver are defined by t he UPnP vendor and ver MUST
cont ain t he version of t he device t ype from t he M-SEARCH request . Period charact ers in t he Vendor Domain Name
MUST be replaced wit h hyphens in accordance wit h RFC 2141.
urn:domain-name:service:serviceType:ver
Respond once for each mat ching service t ype. MUST be urn: domain-name:service:serviceType:ver where domainname (a Vendor Domain Name), serviceType and ver are defined by t he UPnP vendor and ver MUST cont ain t he
version of t he service t ype from t he M-SEARCH request . Period charact ers in t he Vendor Domain Name MUST be
replaced wit h hyphens in accordance wit h RFC 2141.
USN
REQUIRED. Field value cont ains Unique Service Name. (See list of required field values for t he USN header field in NOTIFY
wit h ssdp:alive above.) Single URI.
BOOTID.UPNP.ORG
REQUIRED. As defined in sect ion 1.2, and 1.2.2.
CONFIGID.UPNP.ORG
OPTIONAL. As defined in sect ion 1.2, and 1.2.2.
SEARCHPORT.UPNP.ORG
OPTIONAL. As defined in sect ion 1.2, and 1.2.2.

35

If t here is an error wit h t he search request (such as an invalid field value in t he MAN header field, a missing MX header field, or
ot her malformed cont ent ), t he device MUST silent ly discard and ignore t he search request ; sending of error responses is
PROHIBITED due t o t he possibilit y of packet st orms if many devices send an error response t o t he same request .

1.4 References
RFC 2141
URN Synt ax. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2141.t xt >.
RFC 2616
HTTP: Hypert ext Transfer Prot ocol 1.1. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2616.t xt .
RFC 2774
HTTP Ext ension Framework. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2774.t xt .
RFC 3986
Uniform Resource Ident ifiers (URI): Generic Synt ax. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc3986.t xt .
RFC 4340
Dat agram Congest ion Cont rol Prot ocol (DCCP). Available at : ht t p:/ / www.iet f.org/ rfc/ rfc4340.t xt .
[1]
DCE variant of Universal Unique Ident ifiers (UUIDs), The Open group, 1997, Available
at : ht t p:/ / www.opengroup.org/ onlinepubs/ 9629399/ apdxa.ht m.

36

2 Description
[Normative]
Descript ion is St ep 2 in UPnPnet working. Descript ion comes af t er addressing (St ep 0) where devices get a net work address,
and af t er discovery (St ep 1) where cont rol point s f ind int erest ing device(s). Descript ion enables cont rol (St ep 3) where cont rol
point s send commands t o device(s), event ing (St ep 4) where cont rol point s list en t o st at e changes in device(s), and present at ion
(St ep 5) where cont rol point s may display an ht ml user int erf ace f or device(s).

Aft er a cont rol point has discovered a device, t he cont rol point st ill knows very lit t le about t he device -- only t he informat ion
t hat was in t he discovery message, i.e., t he device's (or service's) UPnP t ype, t he device's universally-unique ident ifier, and a URL
t o t he device's UPnP descript ion. For t he cont rol point t o learn more about t he device and it s capabilit ies, or t o int eract wit h t he
device, t he cont rol point MUST ret rieve a descript ion of t he device and it s capabilit ies from t he URL provided by t he device in
t he discovery message.

Figure 2-1:

Description architecture
root device
control point

HTTP GET
service

description
-----service URL
-----------

HTTP RESP

device

HTTP GET
description
-----------

HTTP RESP

service
service

The UPnP descript ion for a device is part it ioned int o t wo logical part s: a device descript ion describing t he physical and logical
cont ainers, and service descript ions describing t he capabilit ies exposed by t he device. A UPnP device descript ion includes
vendor-specific manufact urer informat ion like t he model name and number, serial number, manufact urer name, URLs t o vendorspecific Web sit es, et c. (det ails below). For each service included in t he device, t he device descript ion list s t he service t ype,
service name, a URL for a service descript ion, a URL for cont rol, and a URL for event ing. A device descript ion also includes a
descript ion of all embedded devices and a URL for present at ion of t he aggregat e. This sect ion explains UPnP device descript ions,
and t he sect ions on Cont rol, Event ing, and Present at ion explain how URLs for cont rol, event ing, and present at ion are used
respect ively.

Not e t hat a single physical device MAY include mult iple logical devices. Mult iple logical devices can be modeled as a single root
device wit h embedded devices (and services) or as mult iple root devices (perhaps wit h no embedded devices). In t he former case,

37

t here is one UPnP device descript ion for t he root device, and t hat device descript ion cont ains a descript ion for all embedded
devices. In t he lat t er case, t here are mult iple UPnP device descript ions, one for each root device.

A UPnP device descript ion is writ t en by a UPnP vendor. The descript ion is in XML synt ax and is usually based on a st andard UPnP
Device Templat e. A UPnP Device Templat e is produced by a UPnP Forum working commit t ee; t hey derive t he t emplat e from t he
UPnP Device Schema, which was derived from st andard const ruct ions in XML. This sect ion explains t he format for a UPnP device
descript ion, UPnP Device Templat es, and t he part of t he UPnP Device Schema t hat covers devices.

A UPnP service descript ion includes a list of commands, or act ions, t o which t he service responds, and paramet ers, or argument s
for each act ion. A service descript ion also includes a list of variables. These variables model t he st at e of t he service at run t ime,
and are described in t erms of t heir dat a t ype, range, and event charact erist ics. This sect ion explains t he descript ion of act ions,
argument s, st at e variables, and t he propert ies of t hose variables. The sect ion on Event ing explains event charact erist ics.

Like a UPnP device descript ion, a UPnP service descript ion is writ t en by a UPnP vendor. The descript ion is in XML synt ax and is
usually based on a st andard UPnP Service Templat e. A UPnP Service Templat e is produced by a UPnP Forum working commit t ee;
t hey derived t he t emplat e from t he UPnP Service Schema, augment ing it wit h human language where necessary. The UPnP
Service Schema is derived using t he convent ions of XML Schema. This sect ion explains t he format for a UPnP service descript ion,
UPnP Service Templat es, t ypical augment at ions in human language, and t he part of t he UPnP Service Schema t hat covers services.

UPnP vendors can different iat e t heir devices by ext ending services (see sect ion 2.7, Non-st andard vendor ext ensions and
limit at ions ), including addit ional UPnP services, or embedding addit ional devices. When a cont rol point ret rieves a part icular
device's descript ion, t hese added feat ures are exposed t o t he cont rol point for cont rol and event ing. The device and service
descript ions aut horit at ively document t he implement at ion of t he device.

Ret rieving a UPnP device descript ion is simple: t he cont rol point issues an HTTP GET request on t he URL in t he discovery message,
and t he device ret urns t he device descript ion. Ret rieving a UPnP service descript ion is a similar process t hat uses a URL wit hin
t he device descript ion. The prot ocol st ack, met hod, header fields, and body for t he response and request are explained in det ail
below. Descript ion document s MUST be sent using t he same IP address on which t he HTTP GET request was received.

As long as at least one of t he discovery advert isement s from a root device, any of it s embedded devices or any of it s services
have not expired and none of t he advert isement s have been cancelled, a cont rol point MAY assume t hat t he root device and all
it s embedded devices and all it s services are available. The device and service descript ions MAY be ret rieved at any point since
t he device and service descript ions are st at ic as long as t he device and it s services are available. If a device cancels at least one
of it s advert isement s or if all t he advert isement s expire, a cont rol point SHOULD assume t he device and it s services are no longer
available. If a device needs t o change one of t hese descript ions, it MUST cancel it s out st anding advert isement s and re-advert ise.
Consequent ly, cont rol point s SHOULD NOT assume t hat device and service descript ions are unchanged if a device re-appears on
t he net work, but t hey can det ect whet her descript ions changed if a changed CONFIGID.UPNP.ORG field value is present in t he
announcement s.

38

Like discovery, descript ion plays an import ant role in t he int eroperabilit y of devices and cont rol point s using different versions of
UPnP net working. As explained in sect ion 1, Discovery , t he UPnP Device Archit ect ure is versioned wit h bot h a maj or and a
minor version. The maj or version and minor version are separat e int eger numbers; t hey are not t o be int erpret ed or compared as
t hough t hey were a single decimal number, even t hough t hey may appear as such in print . Advances in minor versions MUST be a
compat ible superset of earlier minor versions of t he same maj or version; t herefore device vendors are free t o implement
st andardized devices and services on versions of t he archit ect ure wit h a higher minor version number. Advances in maj or version
are NOT REQUIREDt o be superset s of earlier versions and are not guarant eed t o be backward compat ible. The archit ect ure
version of a root device, all it s embedded devices and all it s services MUST be t he same. Version informat ion is communicat ed in
descript ion messages as a backup t o t he informat ion communicat ed in discovery messages. This sect ion explains t he format of
version informat ion in descript ion messages.

Device and service t ypes st andardized by UPnP Forum working commit t ees or creat ed by vendors have an int eger version. Every
lat er version of a device or service MUST be a fully backwardly compat ible superset of t he previous version, i.e., compared t o
earlier versions of t he device, it MUST include all mandat ory embedded devices and services of t he same or lat er version. The
UPnP device or service t ype remains t he same across all versions of a device whereas t he device or service version MUST be
larger for lat er versions. Versions of device and service t emplat es MAY have non-int eger versions (such as 0.9 ) during
development in t he working commit t ee, but t his MUST become an int eger upon st andardizat ion. Devices and services MAY have a
version number great er t han t he maj or version number of t he archit ect ure t hey are designed for (e.g., Power:2 MAY be
designed t o work on UDA version 1.0); t here is no direct correlat ion bet ween t he version of a device or service t emplat e and t he
archit ect ure version wit h which it is designed t o work. If a non-backward-compat ible version of a device or service is defined, it
MUST have a different device or service name t o indicat e t hat it is not backwardly compat ible (and version numbers of t he new
t ype MUST rest art at 1).

UPnP device and service t ypes are building blocks t hat MAY be assembled in various combinat ions. Bot h st andard and vendordefined device t ypes MAY be embedded in st andard device t ypes. Bot h st andard and vendor-defined device t ypes MAY be
embedded in vendor-defined device t ypes. Likewise, bot h st andard and vendor-defined service t ypes MAY be embedded in bot h
st andard and vendor-defined device t ypes. A cont rol point t hat is capable of operat ing wit h a part icular device or service t ype
MUST at least recognize t hat device or service t ype even when it is embedded wit hin anot her device t ype (st andard or vendordefined) t hat it does not recognize. For example, if a st andard service t ype Print :1 is defined, and a st andard device t ype
Print er:1 is defined t hat cont ains t he Print :1 service, a cont rol point t hat wishes t o use t he Print :1 service must find and
use it whet her t he service is embedded wit hin a urn:schemas-upnp-org:device:Print er:1 device or embedded wit hin a vendordefined urn:acme-com:device:Print er:1 or urn:acme-com:device:AcmeMult if unct ionPrint er:1 device.

The remainder of t his sect ion first explains how devices are described, explaining det ails of vendor-specific informat ion,
embedded devices, and URLs for cont rol, event ing, and present at ion. Second, it explains UPnP Device Templat es. Third, it
explains how services are described, explaining det ails of act ions, argument s, st at e variables, and propert ies of t hose variables.

39

Then it explains UPnP Service Templat es, and t he UPnP Service Schema. Finally, t his sect ion explains in det ail how a cont rol
point ret rieves device and service descript ions from a device.

2.1 Generic requirements on HTTP usage


This sect ion defines generic requirement s on HTTP usage in UPnP Version 1.1. HTTP is t he underlying t ransport for:
Descript ion (see sect ion 2, Descript ion )
Cont rol (see sect ion 3, Cont rol )
Event ing (see sect ion 4, Event ing )
Present at ion (sect ion 5, Present at ion )
The baseline t ransport for all devices and cont rol point s is RECOMMENDED t o be HTTP/ 1.1 compliant (as defined in RFC 2616) but
at least MUST be HTTP/ 1.0 compliant (as defined in RFC 1945). Vendors are free t o implement and Working Commit t ees are free
t o require for new device classes implement at ions of more recent versions of HTTP t hat are backwards compat ible wit h HTTP
version 1.0, such as HTTP version 1.1 as defined in RFC 2616. However what ever version is implement ed, all REQUIRED
component s defined by t he specified HTTP version MUST be implement ed.

If a cont rol point uses an HTTP/ 1.0 binding on a SOAP request wit hout set t ing t he KeepAlive t oken, t he device MUST close t he
socket aft er responding. If a cont rol point uses an HTTP/ 1.1 binding on a SOAP request , and set s t he Connect ion:CLOSE t oken,
t he device MUST close t he socket aft er responding.
USER-AGENT header field
Cont rol point s can add t he USER-AGENT header field t o any UPnP-relat ed HTTP request t o signal t hat t hey support UPnP 1.1.
Working Commit t ees MAY require presence of t his header on descript ion ret rieval, act ion invocat ions and event subscript ions for
newly defined services.

USER-AGENT: OS/version UPnP/1.1 product/version


USER-AGENT
OPTIONAL.Specified by UPnP vendor. St ring. Field value MUST begin wit h t he following product t okens (defined by
HTTP/ 1.1). The first product t oken ident ifes t he operat ing syst em in t he form OS name/ OS version, t he second t oken
represent s t he UPnP version and MUST be UPnP/ 1.1, and t he t hird t oken ident ifes t he product using t he form
product name/ product version. For example, USER-AGENT: unix/ 5.1 UPnP/ 1.1 MyProduct / 1.0 . Cont rol point s MUST be
prepared t o accept a higher minor version number of t he UPnP version t han t he cont rol point it self implement s. For
example, cont rol point s implement ing UDA version 1.0 will be able t o int eroperat e wit h devices implement ing
UDA version 1.1.
Vendor-defined or working committee-defined HTTP Header fields
HTTP field names defined by vendors or working commit t ees MUST have t he following format :

field-name = t oken . domain-name

where t he domain-name MUST be a Vendor Domain Name or MUST be UPNP.ORG (for working commit t ee defined field names),
and in addit ion MUST sat isfy t he t oken format as defined in RFC 2616 sect ion 2.2. Field names are case-insensit ive.

40

HTTP/1.0 Persistent connections


Some implement at ions of HTTP/ 1.0 defined what is known as persist ent connect ions. There are many pract ical uses for t his
funct ionalit y, as it may reduce overhead for a given device by allowing resources t o be used more efficient ly. However, t his
funct ionalit y for HTTP/ 1.0 is not officially defined in t he specificat ion and classified as experiment al. Furt her, t he way it has
been experiment ally defined is flawed in such a way t hat it may cause sessions t o hang in cert ain scenarios. This funct ionalit y
MUST NOT be implement ed by any UPnP devices or cont rol point s t hat implement HTTP version 1.0.
HTTP/1.0 HEAD request
Some implement at ions ut ilize t he HEAD request t o t ry t o predet ermine t he amount of memory required t o process a GET request .
Some servers may not know t hat size of t he cont ent because it may be dynamic. In such cases, t he responses will not cont ain a
CONTENT-LENGTH header field. As such, cont rol point s MUST NOT rely on t he CONTENT-LENGTH header field being specified for
a HEAD response.
HTTP/1.1 General
When a device or cont rol point implement s HTTP/ 1.1, all requirement s of HTTP/ 1.0 MUST be maint ained, wit h t he except ion of
t he CONTENT-LENGTH header field, which MUST NOT be specified when doing chunked t ransfers.
HTTP status codes
Servers MUST ret urn appropriat e HTTP st at us codes for invalid request s. A device or cont rol point MUST use a 4xx HTTP st at us
code for responses t hat indicat e a problem wit h t he format of a request or response. For example, if an HTTP client makes a PUT
request t o a server t hat does not implement t he PUT met hod, t he server SHOULD ret urn a "405 Met hod not Allowed" HTTP st at us
code and MUST ret urn a 4xx series HTTP st at us code. Anot her example is if an HTTP client makes a request t o a server t hat is
malformed HTTP or not well formed XML, t he server SHOULD ret urn a "400 Bad Request " HTTP st at us code and MUST ret urn a 4xx
series HTTP st at us code. While client s are not REQUIRED t o underst and specific st at us codes, t hey MUST underst and classes of
st at us codes. For example, a 4xx series HTTP st at us code signifies an improper request , whereas a 5xx series HTTP st at us code
signifies a processing error for a valid request .
HTTP/1.1 and HTTP/1.0 compatibility
Devices and cont rol point s t hat implement HTTP/ 1.1 MUST be able t o int eroperat e wit h HTTP/ 1.0 cont rol point s and devices.
Care MUST be t aken when devices and cont rol point s process request s, such t hat t he response generat ed is compat ible wit h t he
HTTP version specified in t he request . For example, if an HTTP/ 1.0 request is made, t he device or cont rol point MUST NOT
ret urn an HTTP/ 1.1 chunked response.
HTTP/1.1 HOST header field and use of the HOST header field with HTTP/1.0
The HOST header field MUST be specified in all request s, because HTTP/ 1.1 allows support for virt ual domains, which rely on
t his header field t o det ermine t he t arget dest inat ion.

The HOST header field MUST also be included in HTTP/ 1.0 request s, for backwards compat ibilit y wit h UPnP 1.0, which REQUIRES
t he HOST header field t o be present wit hout explicit ly ment ioning a HTTP version.

41

HTTP/1.1 EXPECT: 100-Continue


Servers MAY send a 100-Cont inue HTTP st at us code t o let t he client know t hat t he header fields received have been processed.
If a client will rely on t his st at us response before sending t he body, it MUST send t he EXPECT: 100-Cont inue header field in t he
request . If a server received t his header field in t he request , it MUST NOT wait for t he request body before sending t he cont inue
response. However, a client MUST be prepared t o handle cases when t he EXPECT: 100-Cont inue header field is not sent , but a
100-Cont inue HTTP st at us code is st ill received from t he server.
HTTP/1.1 Chunked Encoding
Devices and cont rol point s t hat advert ise support for HTTP/ 1.1 MUST have support for decoding chunked encoded messages.
Chunked encoded messages MAY cont ain Chunk-Ext ensions, which are delineat ed wit h a ; . Ext ensions t hat are not recognized
MUST be ignored, which includes t he absence of an ext ension, but t he presence of t he delineat or.

Chunked encoding also allows responses and request s t o include t railer fields, which are header fields t hat follow t he body.
Devices and cont rol point s MUST only send t railer fields if t he request cont ained t he TE header field (indicat es t railer
processing is support ed), or if t he t railer fields in t he response only cont ain OPTIONAL met adat a t hat can be safely ignored.

Before a cont rol point uses chunked encoding t o make a request t o a device, it MUST check t o ensure t hat t he device is an
HTTP/ 1.1 device. Devices MAY use different HTTP engines (t hat support different versions) for descript ion, cont rol, event ing and
present at ion. Therefore, t o correct ly ident ify which HTTP version is used for processing cont rol request s, a HEAD request MAY be
issued t o t he corresponding cont rol URL.
HTTP/1.1 Persistent Connections
Persist ent connect ions is t he default behavior defined by HTTP/ 1.1. It is st rongly RECOMMENDED t hat t his behavior be
maint ained, as it may be beneficial in many scenarios, as it allows for resources t o be ut ilized more efficient ly. Support for
Pipelined request handling is also RECOMMENDED if persist ent connect ions are support ed.

If a server responds wit h a CONNECTION: close header line, it MUST close t he session aft er responding. Similarly if a client
specifies CONNECTION: close in t he request , t he server MUST also close t he session aft er responding.

When Request s are pipelined t o a server, t he server MUST answer t he request s in t he order t hat t hey are received. Client s MUST
also be prepared t o ret ry connect ions if pipelining fails, for example, if t he server does not support t hem.
HTTP/1.1 Redirect restrictions
HTTP/ 1.1 defines OPTIONAL support for redirect ing an HTTP request . UPnP 1.1 devices MAY redirect a request , alt hough t his is
NOT RECOMMENDED. If a UPnP 1.1 device redirect s a request , it MUST respond wit h a 307 Temporary Redirect HTTP st at us
code (see also RFC 2616). UPnP 1.1 devices MUST NOT ret urn any ot her HTTP/ 1.1 redirect opt ions. Cont rol point s MUST
implement HTTP/ 1.1 redirect and SHOULD redirect t he request upon receiving a 307 Temporary Redirect HTTP st at us code
(see also RFC 2616).

42

2.2 Generic requirements on XML usage


XML namespace prefixes do not have t o be t he specific st rings t hat are used in t he examples in t his specificat ion. They can be
any value t hat obeys t he rules of t he general XML namespace mechanism as out lined in t he Namespaces in XML specificat ion.
Devices MUST accept request s t hat use ot her legal XML namespace prefixes.

If an XML element has no value (i.e. it cont ains t he empt y st ring), it is valid t o combine t he opening and closing XML t ags (e. g.,
<actionname/> inst ead of <actionname></actionname> ).

2.3 Device description


The UPnP descript ion for a device cont ains several pieces of vendor-specific informat ion, definit ions of all embedded devices,
URL for present at ion of t he device, and list ings for all services, including URLs for cont rol and event ing. In addit ion t o defining
non-st andard devices (which MAY cont ain bot h vendor-defined and st andard embedded devices and services), UPnP vendors MAY
add embedded devices and services t o st andard devices. To illust rat e t hese, below is a list ing wit h placeholders (in it alics) for
act ual element s and values. Some of t hese placeholders would be specified by a UPnP Forum working commit t ee (colored red) or
by a UPnP vendor (colored purple). For a non-st andard device, all of t hese placeholders would be specified by a UPnP vendor.
Element s defined by t he UPnP Device Archit ect ure are colored green. Immediat ely following t he list ing is a det ailed explanat ion
of t he element s, at t ribut es, and values.

<?xml version="1.0"?>
<root xmlns="urn:schemas-upnp-org:device-1-0"
configId="configuration number">
<specVersion>
<major>1</major>
<minor>1</minor>
</specVersion>
<device>
<deviceType>urn:schemas-upnp-org:device:deviceType:v</deviceType>
<friendlyName>short user-friendly title</friendlyName>
<manufacturer>manufacturer name</manufacturer>
<manufacturerURL>URL to manufacturer site</manufacturerURL>
<modelDescription>long user-friendly title</modelDescription>
<modelName>model name</modelName>
<modelNumber>model number</modelNumber>
<modelURL>URL to model site</modelURL>
<serialNumber>manufacturer's serial number</serialNumber>
<UDN>uuid:UUID</UDN>
<UPC>Universal Product Code</UPC>
<iconList>
<icon>
<mimetype>image/format</mimetype>
<width>horizontal pixels</width>
<height>vertical pixels</height>
<depth>color depth</depth>
<url>URL to icon</url>
</icon>
<!-- XML to declare other icons, if any, go here -->
</iconList>
<serviceList>
<service>
<serviceType>urn:schemas-upnp-org:service:serviceType:v</serviceType>
<serviceId>urn:upnp-org:serviceId:serviceID</serviceId>
<SCPDURL>URL to service description</SCPDURL>
<controlURL>URL for control</controlURL>
<eventSubURL>URL for eventing</eventSubURL>

43

</service>
<!-- Declarations for other services defined by a UPnP Forum working committee
(if any) go here -->
<!-- Declarations for other services added by UPnP vendor (if any) go here -->
</serviceList>
<deviceList>
<!-- Description of embedded devices defined by a UPnP Forum working committee
(if any) go here -->
<!-- Description of embedded devices added by UPnP vendor (if any) go here -->
</deviceList>
<presentationURL>URL for presentation</presentationURL>
</device>
</root>

List ed below are det ails for each of t he element s, at t ribut es, and values appearing in t he list ing above. All element s and
at t ribut es are case sensit ive; HTTP specifies case sensit ivit y for URLs; ot her values are not case sensit ive except where not ed.
The order of element s is significant . Except where not ed: REQUIRED element s MUST occur exact ly once (no duplicat es), and
RECOMMENDED or OPTIONAL element s MAY occur at most once. Not e t hat some implement at ions MAY st rict ly enforce t he lengt h
limit s for various element s not ed below, and t herefore working commit t ees are advised t o heed all limit s specified.
<?xml>
REQUIRED for all XML document s. Case sensit ive.
<root>
REQUIRED. MUST have urn:schemas-upnp-org:device-1-0 as t he value for t he xmlns at t ribut e; t his references t he UPnP
Device Schema (described below). Case sensit ive. Has t he following at t ribut e:
configId
REQUIRED. Specifies t he configurat ion number t o which t he device descript ion belongs. See sect ion 1, Discovery
for furt her definit ion and usage of t he configurat ion number.
Cont ains all ot her element s describing t he root device, i.e., cont ains t he following child element s:
<specVersion>
REQUIRED. In device t emplat es, defines t he lowest version of t he archit ect ure on which t he device can be
implement ed. In act ual UPnP devices, defines t he archit ect ure on which t he device is implement ed. Cont ains t he
following sub element s:
<major>
REQUIRED. Maj or version of t he UPnP Device Archit ect ure. MUST be 1 for devices implement ed on a
UPnP 1.1 archit ect ure.
<minor>
REQUIRED. Minor version of t he UPnP Device Archit ect ure. MUST be 1 for devices implement ed on a
UPnP 1.1 archit ect ure. MUST accurat ely reflect t he version number of t he UPnP Device Archit ect ure
support ed by t he device. Cont rol point s MUST be prepared t o accept a higher version number t han t he
cont rol point it self implement s.
<URLBase>
Use of URLBase is deprecat ed in UPnP 1.1; UPnP 1.1 devices MUST NOT include URLBase in t heir descript ion
document s. For full definit ion of URLBase, see t he UPnP 1.0 specificat ion.
<device>
REQUIRED. Cont ains t he following sub element s:
<deviceType>
REQUIRED. UPnP device t ype. Single URI.
For st andard devices defined by a UPnP Forum working commit t ee, MUST begin wit h urn: schemasupnp-org:device: followed by t he st andardized device t ype suffix, a colon, and an int eger device
version i.e. urn:schemas-upnp-org:device:deviceType:ver. The highest support ed version of t he
device t ype MUST be specified.
For non-st andard devices specified by UPnP vendors, MUST begin wit h urn: , followed by a Vendor
Domain Name, followed by :device: , followed by a device t ype suffix, colon, and an int eger
version, i.e., urn:domain-name:device:deviceType:ver . Period charact ers in t he Vendor Domain

44

Name MUST be replaced wit h hyphens in accordance wit h RFC 2141. The highest support ed version
of t he device t ype MUST be specified.
The device t ype suffix defined by a UPnP Forum working commit t ee or specified by a UPnP vendor MUST
be <= 64 chars, not count ing t he version suffix and separat ing colon.
<friendlyName>
REQUIRED. Short descript ion for end user. MAY be localized (see ACCEPT-LANGUAGE and CONTENTLANGUAGE header fields). Specified by UPnP vendor. St ring. SHOULD be < 64 charact ers.
<manufacturer>
REQUIRED. Manufact urer's name. MAY be localized (see ACCEPT-LANGUAGE and CONTENT-LANGUAGE
header fields). Specified by UPnP vendor. St ring. SHOULD be < 64 charact ers.
<manufacturerURL>
OPTIONAL. Web sit e for Manufact urer. MAY have a different value depending on language request ed
(see ACCEPT-LANGUAGE and CONTENT-LANGUAGE header fields). Specified by UPnP vendor. Single URL.
<modelDescription>
RECOMMENDED. Long descript ion for end user. MAY be localized (see ACCEPT-LANGUAGE and CONTENTLANGUAGE header fields). Specified by UPnP vendor. St ring. SHOULD be < 128 charact ers.
<modelName>
REQUIRED. Model name. MAY be localized (see ACCEPT-LANGUAGE and CONTENT-LANGUAGE header
fields). Specified by UPnP vendor. St ring. SHOULD be < 32 charact ers.
<modelNumber>
RECOMMENDED. Model number. MAY be localized (see ACCEPT-LANGUAGE and CONTENT-LANGUAGE
header fields). Specified by UPnP vendor. St ring. SHOULD be < 32 charact ers.
<modelURL>
OPTIONAL. Web sit e for model. MAY have a different value depending on language request ed (see
ACCEPT-LANGUAGE and CONTENT-LANGUAGE header fields). Specified by UPnP vendor. Single URL.
<serialNumber>
RECOMMENDED. Serial number. MAY be localized (see ACCEPT-LANGUAGE and CONTENT-LANGUAGE
header fields). Specified by UPnP vendor. St ring. SHOULD be < 64 charact ers.
<UDN>
REQUIRED. Unique Device Name. Universally-unique ident ifier for t he device, whet her root or embedded.
MUST be t he same over t ime for a specific device inst ance (i.e., MUST survive reboot s). MUST mat ch t he
field value of t he NT header field in device discovery messages. MUST mat ch t he prefix of t he USN
header field in all discovery messages. (Sect ion 1, Discovery explains t he NT and USN header fields.)
MUST begin wit h uuid: followed by a UUID suffix specified by a UPnP vendor. See sect ion 1.1.4, UUID
format and RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format .
<UPC>
OPTIONAL. Universal Product Code. 12-digit , all-numeric code t hat ident ifies t he consumer package.
Managed by t he Uniform Code Council. Specified by UPnP vendor. Single UPC.
<iconList>
REQUIRED if and only if device has one or more icons. Specified by UPnP vendor. Cont ains t he following
sub element s:
<icon>
RECOMMENDED. Icon t o depict device in a cont rol point UI. MAY have a different value
depending on language request ed (see ACCEPT-LANGUAGE and CONTENT-LANGUAGE header
fields). Icon sizes t o support are vendor-specific. Cont ains t he following sub element s:
<mimetype>
REQUIRED. Icon's MIME t ype (see RFC 2045, 2046, and 2387). Single MIME image t ype. At least
one icon SHOULD be of t ype image/ png (Port able Net work Graphics, see IETF RFC 2083).
<width>
REQUIRED. Horizont al dimension of icon in pixels. Int eger.
<height>
REQUIRED. Vert ical dimension of icon in pixels. Int eger.
<depth>
REQUIRED. Number of color bit s per pixel. Int eger.
<url>
REQUIRED. Point er t o icon image. (XML does not support direct embedding of binary dat a. See
not e below.) Ret rieved via HTTP. MUST be relat ive t o t he URL at which t he device descript ion
is locat ed in accordance wit h sect ion 5 of RFC 3986. Specified by UPnP vendor. Single URL.

45

<serviceList>
OPTIONAL. Cont ains t he following sub element s:
<service>
OPTIONAL. Repeat ed once for each service defined by a UPnP Forum working commit t ee. If
UPnP vendor different iat es device by adding addit ional, st andard UPnP services, repeat ed
once for each addit ional service. Cont ains t he following sub element s:
<serviceType>
Required. UPnP service t ype. MUST NOT cont ain a hash charact er (#, 23 Hex in UTF8). Single URI.
For st andard service t ypes defined by a UPnP Forum working commit t ee, MUST
begin wit h urn:schemas-upnp-org:service: followed by t he st andardized
service t ype suffix, colon, and an int eger service version i.e. urn: schemasupnp-org:device:serviceType:ver. The highest support ed version of t he service
t ype MUST be specified.
For non-st andard service t ypes specified by UPnP vendors, MUST begin wit h
urn: , followed by a Vendor Domain Name, followed by :service: , followed
by a service t ype suffix, colon, and an int eger service version, i.e.,
urn:domain-name:service:serviceType:ver . Period charact ers in t he Vendor
Domain Name MUST be replaced wit h hyphens in accordance wit h RFC 2141.
The highest support ed version of t he service t ype MUST be specified.
The service t ype suffix defined by a UPnP Forum working commit t ee or specified by
a UPnP vendor MUST be <= 64 charact ers, not count ing t he version suffix and
separat ing colon.
<serviceId>
REQUIRED. Service ident ifier. MUST be unique wit hin t his device descript ion. Single
URI.
For st andard services defined by a UPnP Forum working commit t ee, MUST begin
wit h urn:upnp-org:serviceId: followed by a service ID suffix i.e. urn:upnporg:serviceId:serviceID. If t his inst ance of t he specified service t ype (i.e. t he
<serviceType> element above) corresponds t o one of t he services defined by
t he specified device t ype (i.e. t he <deviceType> element above), t hen t he
value of t he service ID suffix MUST be t he service ID defined by t he device
t ype for t his inst ance of t he service. Ot herwise, t he value of t he service ID
suffix is vendor defined. (Not e t hat upnp-org is used inst ead of schemas-upnporg in t his case because an XML schema is not defined for each service ID.)
For non-st andard services specified by UPnP vendors, MUST begin wit h urn: ,
followed by a Vendor Domain Name, followed by :serviceId: , followed by a
service ID suffix, i.e., urn:domain-name:serviceId:serviceID . If t his inst ance
of t he specified service t ype (i.e. t he <serviceType> element above)
corresponds t o one of t he services defined by t he specified device t ype (i.e.
t he <deviceType> element above), t hen t he value of t he service ID suffix
MUST be t he service ID defined by t he device t ype for t his inst ance of t he
service. Period charact ers in t he Vendor Domain Name MUST be replaced wit h
hyphens in accordance wit h RFC 2141.
The service ID suffix defined by a UPnP Forum working commit t ee or specified by a
UPnP vendor MUST be <= 64 charact ers.
<SCPDURL>
REQUIRED. URL for service descript ion. (See sect ion 2.5, Service descript ion
below.) MUST be relat ive t o t he URL at which t he device descript ion is locat ed in
accordance wit h sect ion 5 of RFC 3986. Specified by UPnP vendor. Single URL.
<controlURL>
REQUIRED. URL for cont rol (see sect ion 3, Cont rol ). MUST be relat ive t o t he URL
at which t he device descript ion is locat ed in accordance wit h sect ion 5 of RFC 3986.
Specified by UPnP vendor. Single URL.
<eventSubURL>
REQUIRED. URL for event ing (see sect ion 4, Event ing ). MUST be relat ive t o t he
URL at which t he device descript ion is locat ed in accordance wit h sect ion 5 of RFC
3986. MUST be unique wit hin t he device; any t wo services MUST NOT have t he same
URL for event ing. If t he service has no event ed variables, t his element MUST be

46

present but MUST be empt y (i.e., <eventSubURL></eventSubURL>.) Specified by


UPnP vendor. Single URL.
<deviceList>
REQUIRED if and only if root device has embedded devices. Cont ains t he following sub element s:
<device>
REQUIRED. Repeat once for each embedded device defined by a UPnP Forum working
commit t ee. If UPnP vendor different iat es device by embedding addit ional UPnP devices,
repeat once for each embedded device. Cont ains sub element s as defined above for root sub
element device.
<presentationURL>
RECOMMENDED. URL t o present at ion for device (see sect ion 5, Present at ion ). MUST be relat ive t o t he
URL at which t he device descript ion is locat ed in accordance wit h t he rules specified in sect ion 5 of RFC
3986. Specified by UPnP vendor. Single URL.
Cont rol point s SHOULD recognize and int eroperat e wit h services using serviceId values ot her t han t he value defined by t he device
t ype. If mult iple inst ances of a service exist , cont rol point s SHOULD by default (unless direct ed ot herwise by user act ion) use t he
service inst ance associat ed wit h t he serviceId value defined by t he device t ype. If none of t he inst ances of t he service have t he
serviceId value defined by t he device t ype, t he cont rol point may use any service inst ance. When only one inst ance of t he service
exist s, cont rol point s SHOULD use t hat inst ance even if t he serviceId value does not mat ch t hat defined by t he device t ype.

For fut ure ext ensibilit y and according t o t he requirement s in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8,
UPnP Device Schema , when processing XML like t he list ing above, devices and cont rol point s MUST ignore: (a) any unknown
element s and t heir sub element s or cont ent , and (b) any unknown at t ribut es and t heir values.

Subj ect t o t he const raint s defined in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8, UPnP Device Schema ,
cont rol point s and devices MUST ignore any XML comment s or XML processing inst ruct ions embedded in UPnP device and service
descript ions t hat t hey do not underst and. UPnP device descript ions MUST be encoded using UTF-8.

When t he value of any t ext element or at t ribut e cont ains one or more charact ers reserved as markup (such as ampersand ( & )
or less t han ( < )), t he t ext MUST be escaped in accordance wit h t he provisions of sect ion 2.4 of t he XML specificat ion and each
such charact er replaced wit h t he equivalent numeric represent at ion or st ring (such as &amp; or &lt ; ). Such charact ers
appearing in URLs MAY also be percent -encoded in accordance wit h t he URL percent -encoding rules specified in sect ions 2.1 and
2.4 of RFC 3986.

XML does not support direct ly embedding binary dat a, e.g., icons in UPnP device descript ions. Binary dat a MAY be convert ed int o
t ext (and t hereby embedded int o XML) using an XML dat a t ype of eit her bin.base64 (a MIME-st yle base 64 encoding for binary
dat a) or bin.hex (hexadecimal digit s represent oct et s). Alt ernat ively, t he dat a can be passed indirect ly, as it were, by embedding
a URL in t he XML and t ransferring t he dat a in response t o a separat e HTTP request ; t he icon(s) in UPnP device descript ions are
t ransferred in t his lat t er manner.

If any icons are included, at least one SHOULD be in t he Port able Net work Graphics (PNG) format defined in RFC 2083, indicat ed
by t he MIME t ype image/ png , and not use progressive encoding. NO specific icon sizes are RECOMMENDED due t o t he wide
variet y preferred by various cont rol point s; cont rol point vendors are encouraged t o publish implement at ion guidelines.

47

The use of URLBase element is deprecat ed by t his specificat ion. UPnP 1.1 devices MUST NOT include URLBase in t heir descript ion
document s. To ensure int eroperabilit y wit h UPnP 1.0 devices, cont rol point s MUST be able t o process URLBase if it is specified
and use it for resolving relat ive URLs t hat appear elsewhere in t he descript ion. If relat ive URLs are included in t he device
descript ion, cont rol point s MUST resolve t hem int o absolut e URLs in accordance wit h sect ion 5 of RFC 3986, using eit her URLBase
(if specified) or t he locat ion from which t he device descript ion was ret rieved as t he base URL, before using t hese URLs for t heir
respect ive purposes.

Not e t hat in version 1.0 of t he UPnP Device Archit ect ure, t he serviceList element was REQUIRED, and it was REQUIRED t o
cont ain at least one service element . These requirement s were subsequent ly rescinded t o accommodat e t he
Int ernet Gat ewayDevice:1 and Basic:1 device t ypes. If t he device has no services, t he serviceList element MAY be omit t ed
ent irely, or it MAY be present but cont ain no service element s.

2.4 UPnP Device Template


The list ing above also illust rat es t he relat ionship bet ween a UPnP device descript ion and a UPnP Device Templat e. As explained
above, t he UPnP device descript ion is writ t en by a UPnP vendor, in XML, following a UPnP Device Templat e. A UPnP Device
Templat e is produced by a UPnP Forum working commit t ee as a means t o st andardize devices.

By appropriat e specificat ion of placeholders, t he list ing above can be eit her a UPnP Device Templat e or a UPnP device
descript ion. Recall t hat some placeholders would be defined by a UPnP Forum working commit t ee (colored red), i.e., t he UPnP
device t ype ident ifier, REQUIRED UPnP services, and REQUIRED UPnP embedded devices (if any). If t hese were defined, t he
list ing would be a UPnP Device Templat e, codifying t he st andard for t his t ype of device. UPnP Device Templat es are one of t he
key deliverables from UPnP Forum working commit t ees.

Taking t his anot her st ep furt her, t he remaining placeholders in t he list ing above would be specified by a UPnP vendor (colored
purpl e), i.e., vendor-specific informat ion. If t hese placeholders were specified (as well as t he ot hers), t he list ing would be a
UPnP device descript ion, suit able t o be delivered t o a cont rol point t o enable cont rol, event ing, and present at ion.

Put anot her way, t he UPnP Device Templat e defines t he overall t ype of device, and each UPnP device descript ion inst ant iat es
t hat t emplat e wit h vendor-specific informat ion. The first is creat ed by a UPnP Forum working commit t ee; t he lat t er, by a UPnP
vendor.

2.5 Service description


The UPnP descript ion for a service defines act ions and t heir argument s, and st at e variables and t heir dat a t ype, range, and event
charact erist ics.

Each service MUST have zero or more act ions. Each act ion MUST have zero or more argument s. Each argument is designat ed as
eit her an input or an out put argument . Input argument s MUST be list ed first . If an act ion has one or more out put argument s, t he

48

first out put argument MAY be marked as a ret urn value. Each argument MUST correspond t o one of t he <st at eVariable> element s
in t he <serviceSt at eTable> in t he SCPD.

Each service MUST have one or more st at e variables.

In addit ion t o defining non-st andard services, UPnP vendors MAY add act ions and services t o st andard devices, and MAY embed
st andard services and devices in non-st andard devices.

To illust rat e t hese point s, below is a list ing wit h placeholders (in it alics) for act ual element s and values. For a st andard UPnP
service, some of t hese placeholders would be defined by a UPnP Forum working commit t ee (colored red) or specified by a UPnP
vendor (purple). For a non-st andard service, all of t hese placeholders would be specified by a UPnP vendor. Element s defined by
t he UPnP Device Archit ect ure are colored green. Immediat ely following t he list ing is a det ailed explanat ion of t he element s,
at t ribut es, and values.

<?xml version="1.0"?>
<scpd
xmlns="urn:schemas-upnp-org:service-1-0"
xmlns:dt1="urn:domain-name:more-datatypes"
<!-- Declarations for other namespaces added by UPnP Forum working committee (if any) go
here -->
<!-- The value of the attribute must remain as defined by the UPnP Forum working committee.
-->
xmlns:dt2="urn:domain-name:vendor-datatypes"
<!-- Declarations for other namespaces added by UPnP vendor (if any) go here -->
<!-- Vendors must change the URNs domain-name to a Vendor Domain Name -->
<!-- Vendors must change vendor-datatypes to reference a vendor-defined namespace -->
configId="configuration number">
<specVersion>
<major>1</major>
<minor>1</minor>
</specVersion>
<actionList>
<action>
<name>actionName</name>
<argumentList>
<argument>
<name>argumentNameIn1</name>
<direction>in</direction>
<relatedStateVariable>stateVariableName</relatedStateVariable>
</argument>
<!-- Declarations for other IN arguments defined by UPnP Forum working
Committee (if any) go here -->
<argument>
<name>argumentNameOut1</name>
<direction>out</direction>
<retval/>
<relatedStateVariable>stateVariableName</relatedStateVariable>
</argument>
<argument>
<name>argumentNameOut2</name>
<direction>out</direction>
<relatedStateVariable>stateVariableName</relatedStateVariable>
</argument>
<!-- Declarations for other OUT arguments defined by UPnP Forum working
committee (if any) go here -->
</argumentList>
</action>
<!-- Declarations for other actions defined by UPnP Forum working committee
(if any)go here -->

49

<!-- Declarations for other actions added by UPnP vendor (if any) go here -->
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes"|"no" multicast="yes"|"no">
<name>variableName</name>
<dataType>basic data type</dataType>
<defaultValue>default value</defaultValue>
<allowedValueRange>
<minimum>minimum value</minimum>
<maximum>maximum value</maximum>
<step>increment value</step>
</allowedValueRange>
</stateVariable>
<stateVariable sendEvents="yes"|"no" multicast="yes"|"no">
<name>variableName</name>
<dataType type="dt1:variable data type">string</dataType>
<defaultValue>default value</defaultValue>
<allowedValueList>
<allowedValue>enumerated value</allowedValue>
<!-- Other allowed values defined by UPnP Forum working committee
(if any) go here -->
<!-- Other allowed values defined by vendor (if any) go here -->
</allowedValueList>
</stateVariable>
<stateVariable sendEvents="yes"|"no" multicast="yes"|"no">
<name>variableName</name>
<dataType type="dt2:vendor data type">string</dataType>
<defaultValue>default value</defaultValue>
</stateVariable>
<!-- Declarations for other state variables defined by UPnP Forum working committee
(if any) go here -->
<!-- Declarations for other state variables added by UPnP vendor (if any) go here -->
</serviceStateTable>
</scpd>

List ed below are det ails for each of t he element s, at t ribut es, and values appearing in t he list ing above. All element s and
at t ribut es (including act ion, argument , and st at e variable names) are case sensit ive; values are not case sensit ive except where
not ed. Except where not ed, REQUIRED element s MUST occur exact ly once (no duplicat es), and RECOMMENDED or OPTIONAL
element s MAY occur at most once.
<?xml>
REQUIRED for all XML document s. Case sensit ive.
<scpd>
REQUIRED. MUST have urn:schemas-upnp-org:service-1-0 as t he value for t he xmlns at t ribut e; t his references t he UPnP
Service Schema (explained below). Case sensit ive. Has t he following at t ribut e:
configId
REQUIRED. Specifies t he configurat ion number t o which t he service descript ion belongs. See sect ion 1,
Discovery for furt her definit ion and usage of t he configurat ion number.
Cont ains all ot her element s describing t he service, i.e., cont ains t he following sub element s:
<specVersion>
REQUIRED. In service t emplat es, defines t he lowest version of t he archit ect ure on which t he service can be
implement ed. In act ual UPnP services, defines t he archit ect ure on which t he service is implement ed. Cont ains t he
following sub element s:
<major>
REQUIRED. Maj or version of t he UPnP Device Archit ect ure. MUST be 1 for services implement ed on a
UPnP 1.1 archit ect ure.
<minor>
REQUIRED. Minor version of t he UPnP Device Archit ect ure. MUST be 1 for services implement ed on a
UPnP 1.1 archit ect ure. MUST accurat ely reflect t he version number of t he UPnP Device Archit ect ure
support ed by t he device. Cont rol point s MUST be prepared t o accept a higher version number t han t he
cont rol point it self implement s.

50

<actionList>
REQUIRED if and only if t he service has act ions. (Each service MAY have >= 0 act ions.) Cont ains t he following sub
element (s):
<action>
REQUIRED. Repeat once for each act ion defined by a UPnP Forum working commit t ee. If UPnP vendor
different iat es service by adding addit ional act ions, repeat once for each addit ional act ion. Cont ains t he
following sub element s:
<name>
REQUIRED. Name of act ion. MUST NOT cont ain a hyphen charact er ( - , 2D Hex in UTF-8) nor
a hash charact er ( # , 23 Hex in UTF-8). Case sensit ive. First charact er MUST be a USASCII
let t er ( A - Z , a - z ), USASCII digit ( 0 - 9 ), an underscore ( _ ), or a non-experiment al
Unicode let t er or digit great er t han U+007F. Succeeding charact ers MUST be a USASCII let t er
( A - Z , a - z ), USASCII digit ( 0 - 9 ), an underscore ( _ ), a period ( . ), a Unicode
combiningchar, an ext ender, or a non-experiment al Unicode let t er or digit great er t han
U+007F. The first t hree let t ers MUST NOT be XML in any combinat ion of case.
For st andard act ions defined by a UPnP Forum working commit t ee, MUST NOT begin wit h
X_ nor A_ .
For non-st andard act ions specified by a UPnP vendor and added t o a st andard service,
MUST begin wit h X_ , followed by a Vendor Domain Name, followed by t he underscore
charact er ( _ ), followed by t he vendor-assigned act ion name. The vendor-assigned
act ion name must comply wit h t he synt ax rules defined above.
St ring. SHOULD be < 32 charact ers.
<argumentList>
REQUIRED if and only if paramet ers are defined for act ion. (Each act ion MAY have >= 0
paramet ers.) Cont ains t he following sub element (s):
<argument>
REQUIRED. Repeat once for each paramet er. UPnP vendors MUST NOT add vendordefined argument s t o act ions defined by a UPnP Forum working commit t ees.
Cont ains t he following sub element s:
<name>
REQUIRED. Name of formal paramet er. The name SHOULD be chosen t o
reflect t he semant ic use of t he argument . MUST NOT cont ain a hyphen
charact er ( - , 2D Hex in UTF-8). First charact er MUST be a USASCII let t er
( A - Z , a - z ), USASCII digit ( 0 - 9 ), an underscore ( _ ), or a nonexperiment al Unicode let t er or digit great er t han U+007F. Succeeding
charact ers MUST be a USASCII let t er ( A - Z , a - z ), USASCII digit
( 0 - 9 ), an underscore ( _ ), a period ( . ), a Unicode combiningchar,
an ext ender, or a non-experiment al Unicode let t er or digit great er t han
U+007F. The first t hree let t ers MUST NOT be XML in any combinat ion of
case. St ring. Case sensit ive. SHOULD be < 32 charact ers.
<direction>
REQUIRED. Defines whet her argument is an input or out put paramet er.
MUST be eit her in or out and not bot h. All input argument s MUST be
list ed before any out put argument s.
<retval>
OPTIONAL. Ident ifies at most one out put argument as t he ret urn value. If
included, MUST be included as a subelement of t he first out put argument .
(Element only; no value.)
<relatedStateVariable>
REQUIRED. MUST be t he name of a st at e variable. Case Sensit ive. Defines
t he t ype of t he argument ; see furt her explanat ion below in t his sect ion.
<serviceStateTable>
REQUIRED. (Each service MUST have => 1 st at e variables.) Cont ains t he following sub element (s):
<stateVariable>
REQUIRED. Repeat once for each st at e variable defined by a UPnP Forum working commit t ee. If UPnP
vendor different iat es service by adding addit ional st at e variables, repeat once for each addit ional st at e
variable. Has t he following at t ribut es:

51

sendEvents
OPTIONAL. Defines whet her event messages will be generat ed when t he value of t his st at e
variable changes. Default value is yes . Non-event ed st at e variables MUST set t his at t ribut e
t o no .
For st andard st at e variables defined by a UPnP Forum working commit t ee, t he working
commit t ee decides whet her t he variable is event ed and t he value of t he sendEvents
at t ribut e MUST NOT be alt ered by a vendor.
For non-st andard st at e variables specified by a UPnP vendor and added t o a st andard
service, t he vendor MAY decide whet her t he non-st andard st at e variable will be event ed
or not .
multicast
OPTIONAL. Defines whet her event messages will be delivered using mult icast event ing.
Default value is no . If t he mult icast is set t o yes , t hen all event s sent for t his st at e
variable MUST be unicast AND mult icast .
For st andard st at e variables defined by a UPnP Forum working commit t ee, t he working
commit t ee decides whet her t he st at e variable is mult icast and t he value of t he
multicast at t ribut e MUST NOT be alt ered by a vendor.
For non-st andard variables specified by a UPnP vendor and added t o a st andard service,
t he vendor may decide whet her t he non-st andard variable will be delivered using
mult icast event ing.
The <stateVariable> element cont ains t he following sub element s:
<name>
REQUIRED. Name of st at e variable. MUST NOT cont ain a hyphen charact er ( - , 2D Hex in UTF8). First charact er MUST be a USASCII let t er ( A - Z , a - z ), USASCII digit ( 0 - 9 ), an
underscore ( _ ), or a non-experiment al Unicode let t er or digit great er t han U+007F.
Succeeding charact ers MUST be a USASCII let t er ( A - Z , a - z ), USASCII digit ( 0 - 9 ),
an underscore ( _ ), a period ( . ), a Unicode combiningchar, an ext ender, or a nonexperiment al Unicode let t er or digit great er t han U+007F. The first t hree let t ers MUST NOT be
XML in any combinat ion of case. Case sensit ive.
For st andard st at e variables defined by a UPnP Forum working commit t ee, MUST NOT
begin wit h X_ nor A_ .
For non-st andard st at e variables specified by a UPnP vendor and added t o a st andard
service, MUST begin wit h X_ , followed by a Vendor Domain Name, followed by t he
underscore charact er ( _ ), followed by t he vendor-assigned st at e variable name. The
vendor-assigned st at e variable name must comply wit h t he synt ax rules defined above.
St ring. SHOULD be < 32 charact ers.
<dataType>
REQUIRED. Same as dat a t ypes defined by XML Schema, Part 2: Dat at ypes. Defined by a UPnP
Forum working commit t ee for st andard st at e variables; specified by UPnP vendor for
ext ensions. Has an OPTIONAL type at t ribut e:
type
OPTIONAL. If t he type at t ribut e is present , t he value of t he <dataType> element
MUST be st ring . The value of t he type at t ribut e overrides t he st ring value; it
defines t he dat a t ype using a fully qualified dat a t ype name according t o t he
convent ions of XML schema and can refer t o XML Schema simple t ypes, service-local
complex t ypes and service-local ext ended simple t ypes. Service-local dat a t ypes are
defined in a corresponding UPnP Service Templat e or t hey MAY be vendor-specific.
See also sect ion 2.5.1, Defining and processing ext ended dat a t ypes and
sect ion 2.5.2, St ring equivalent s of ext ended dat a t ypes .
For example: <dataType type="xsd:byte">string</dataType>
For a st at e variable using an ext ended dat a t ype via t he type at t ribut e and
cont aining complex dat a, t he <defaultValue>, <allowedValueList> and
<allowedValueRange> element s MUST NOT be present . In such case t he
rest rict ions for t he dat a t ype MUST be described in t he dat a t ype schema provided
in t he service t emplat e document .

52

The <dataType> element MUST have one of t he following values:


ui1
Unsigned 1 Byt e int . Same format as int wit hout leading sign.
ui2
Unsigned 2 Byt e int . Same format as int wit hout leading sign.
ui4
Unsigned 4 Byt e int . Same format as int wit hout leading sign.
i1
1 Byt e int . Same format as int .
i2
2 Byt e int . Same format as int .
i4
4 Byt e int . Same format as int . MUST be bet ween -2147483648 and 2147483647.
int
Fixed point , int eger number. MAY have leading sign. MAY have leading zeros, which
SHOULD be ignored by t he recipient . (No currency symbol.) (No grouping of digit s t o
t he left of t he decimal, e.g., no commas.)
r4
4 Byt e float . Same format as float . MUST be bet ween 3.40282347E+38 t o
1.17549435E-38.
r8
8 Byt e float . Same format as float . MUST be bet ween -1.79769313486232E308 and 4.94065645841247E-324 for negat ive values, and bet ween 4.94065645841247E-324
and 1.79769313486232E308 for posit ive values, i.e., IEEE 64-bit (8-Byt e) double.
number
Same as r8.
fixed.14.4
Same as r8 but no more t han 14 digit s t o t he left of t he decimal point and no more
t han 4 t o t he right .
float
Float ing point number. Mant issa (left of t he decimal) and/ or exponent MAY have a
leading sign. Mant issa and/ or exponent MAY have leading zeros, which SHOULD be
ignored by t he recipient . Decimal charact er in mant issa is a period, i.e., whole
digit s in mant issa separat ed from fract ional digit s by period ( . ). Mant issa
separat ed from exponent by E . (No currency symbol.) (No grouping of digit s in t he
mant issa, e.g., no commas.)
char
Unicode st ring. One charact er long.
st ring
Unicode st ring. No limit on lengt h.
dat e
Dat e in a subset of ISO 8601 format wit hout t ime dat a.
dat eTime
Dat e in ISO 8601 format wit h OPTIONAL t ime but no t ime zone.
dat eTime.t z
Dat e in ISO 8601 format wit h OPTIONAL t ime and OPTIONAL t ime zone.
t ime
Time in a subset of ISO 8601 format wit h no dat e and no t ime zone.
t ime.t z
Time in a subset of ISO 8601 format wit h OPTIONAL t ime zone but no dat e.
boolean
0 for false or 1 for t rue. The values t rue , yes , false , or no are
deprecat ed and MUST NOT be sent but MUST be accept ed when received. When
received, t he values t rue and yes MUST be int erpret ed as t rue and t he values
false and no MUST be int erpret ed as false.

53

bin.base64
MIME-st yle Base64 encoded binary BLOB. Takes 3 Byt es, split s t hem int o 4 part s, and
maps each 6 bit piece t o an oct et . (3 oct et s are encoded as 4.) No limit on size.
bin.hex
Hexadecimal digit s represent ing oct et s. Treat s each nibble as a hex digit and
encodes as a separat e Byt e. (1 oct et is encoded as 2.) No limit on size.
uri
Universal Resource Ident ifier.
uuid
Universally Unique ID. See sect ion 1.1.4, UUID format and RECOMMENDED
generat ion algorit hms for t he MANDATORY UUID format .
<defaultValue>
RECOMMENDED. Expect ed, init ial value. Defined by a UPnP Forum working commit t ee or
delegat ed t o UPnP vendor. MUST mat ch dat a t ype. MUST sat isfy <allowedValueList> or
<allowedValueRange> const raint s. For a st at e variable using an ext ended dat a t ype via t he
type at t ribut e and cont aining complex dat a, t he <defaultValue> element MUST NOT be
present .
<allowedValueList>
RECOMMENDED. Enumerat es legal st ring values. PROHIBITED for dat a t ypes ot her t han st ring.
At most one of t he <allowedValueRange> or <allowedValueList> element s MAY be
specified. Sub element s are ordered. For a st at e variable using an ext ended dat a t ype via t he
type at t ribut e and cont aining complex dat a, t he <allowedValueList> element MUST NOT
be present . Cont ains t he following sub element s:
<allowedValue>
REQUIRED. A legal value for a st ring variable. Defined by a UPnP Forum working
commit t ee for st andard st at e variables; if t he UPnP Forum working commit t ee
permit s it , UPnP vendors MAY add vendor-specific allowed values t o st andard st at e
variables. Specified by UPnP vendor for ext ensions. St ring. MUST be < 32 charact ers.
<allowedValueRange>
RECOMMENDED. Defines bounds for legal numeric values; defines resolut ion for numeric values.
Defined only for numeric dat a t ypes (i.e. int egers and float s). At most one of t he
<allowedValueRange> or <allowedValueList> element s MAY be specified. For a st at e
variable using an ext ended dat a t ype via t he type at t ribut e and cont aining complex dat a, t he
<allowedValueRange> element MUST NOT be present . Cont ains t he following sub element s
which MUST have t he same t ype as t he st at e variable:
<minimum>
REQUIRED. Inclusive lower bound. Defined by a UPnP Forum working commit t ee or
delegat ed t o UPnP vendor. Single numeric value. The value of t he <minimum>
element MUST be less t han t he value of t he <maximum> element . If a working
commit t ee has assigned an explicit value for t his element , t hen vendors MUST use
t hat value. Ot herwise, vendors MUST choose t heir own value, but always wit hin t he
allowed range for t he dat a t ype of t his st at e variable. If t he working commit t ee
defines an allowed range for t his st at e variable, t hen t he value MUST be wit hin t hat
allowed range as defined by t he <st ep> value (See below).
<maximum>
REQUIRED. Inclusive upper bound. Defined by a UPnP Forum working commit t ee or
delegat ed t o UPnP vendor. Single numeric value. The value of t he <maximum>
element MUST be great er t han t he value of t he <minimum> element . If a working
commit t ee has assigned an explicit value for t his element , t hen vendors MUST use
t hat value. Ot herwise, vendors MUST choose t heir own value, but always wit hin t he
allowed range for t he dat a t ype of t his st at e variable. If t he working commit t ee
defines an allowed range for t his st at e variable, t hen t he value MUST be wit hin t hat
allowed range as defined by t he <st ep> value (See below).
<step>
RECOMMENDED. Defines t he set of allowed values permit t ed for t he st at e variable
bet ween t he <minimum> and <maximum>. The value of t he <step> element divides
t he inclusive range from <minimum> value t o <maximum> value int o an int egral
number of equal part s. Addit ionally, <maximum> value = <minimum> value + n *
<step> value, where n is a posit ive int eger. Defined by a UPnP Forum working
commit t ee or delegat ed t o UPnP vendor. If a working commit t ee has assigned an
explicit value for t his element , t hen vendors MUST use t hat value. Ot herwise,
vendors MAY choose t heir own value. When t he <step> element is omit t ed and t he

54

dat a t ype of t he st at e variable is an int eger, t he default value of st ep is 1;


ot herwise, when st ep is omit t ed, t he st at e variable MAY be set t o any value wit hin
t he inclusive range of <minimum> value t o <maximum> value. Single numeric value.
Not e: care must be t aken when dealing wit h float ing point values so t hat
conversions and/ or rounding errors do not cause inaccurat e comparison operat ions.
The <relatedStateVariable> element of an <argument> element definit ion MUST be t he name of a st at e variable defined
in t he same service descript ion. The <relatedStateVariable> element defines t he dat a t ype of t he argument ; t here is not
necessarily any semant ic relat ionship bet ween an argument and t he relat ed st at e variable used t o define it s t ype. The
<relatedStateVariable> element MUST specify t he name of a st at e variable in t he service st at e t able which has t he same
dat a t ype, allowed value list , or allowed value range as t he argument . If no st at e variable exist s wit h an appropriat e definit ion,
t he working commit t ee (or vendor) MUST define an addit ional st at e variable for t hat purpose; st at e variables which are defined
solely for t he purpose of describing t he t ype of an argument MUST have a name t hat includes t he prefix A_ARG_TYPE_ .

The <allowedValueList> and <allowedValueRange> element s MAY be used t o indicat e opt ional device capabilit ies.
Working commit t ees MAY REQUIRE all values in t he list or range t o be support ed by all vendors (no opt ions), REQUIRE a minimum
subset wit h addit ional values being OPTIONAL, or allow vendors t o ent irely decide which port ions of t he list or range t o support .
Vendors MAY add addit ional, vendor-specific values t o t he allowed value list by using t he X_ prefix on t he vendor-defined
allowed values, if permit t ed by working commit t ees. However, it should be not ed t hat great er flexibilit y in OPTIONAL
capabilit ies reduces t he number of values t hat cont rol point s can depend on t o be present , wit h corresponding impact s on
int eroperabilit y. If device capabilit ies are expect ed t o change during device operat ion, working commit t ees SHOULD define
event ed st at e variables or separat e act ions t o det ect device capabilit ies rat her t han embedding capabilit ies informat ion in t he
service descript ion, because t he lat t er requires cancellat ion of advert isement s and readvert isement each t ime t he service
descript ion document is changed. If t he service descript ion is used t o convey capabilit ies informat ion, t he device MUST omit from
t he service descript ion any OPTIONAL element s (act ions, allowed values, et c.) t hat are not implement ed.

For a st at e variable using an ext ended dat a t ype via t he type at t ribut e and cont aining complex dat a, t he <defaultValue>,
<allowedValueList> and <allowedValueRange> element s MUST NOT be present . In such case t he rest rict ions for t he dat a
t ype MUST be described in t he dat a t ype schema t ypically provided in t he service t emplat e document .

2.5.1 Defining and processing extended data types


The opt ional type at t ribut e of t he <dataType> element as defined in sect ion 2.5, Service descript ion above allows a service
descript ion document (SCPD) t o include ext ended dat a t ypes (defined by t he UPnP t echnical commit t ee, a UPnP working
commit t ee or vendor-specific dat a t ypes) t hat have more st ruct ure and expression t han t he exist ing XSD dat a t ypes. As
ment ioned above, t his type at t ribut e can only be applied when t he base dat a t ype is of t ype string. The value at t ached t o t he
type at t ribut e refers t o a dat a t ype from a separat e schema defined out side t his document .

As a first RECOMMENDATION on t he use of ext ended dat a t ypes, if UPnP act ions only have simple argument s, t hese SHOULD be
declared using UPnP defined dat a t ypes, inst ead of XML schema simple t ypes. This enables use of such UPnP act ions by UPnP 1.0
st acks t hat are not XML-schema enabled.

55

As a furt her RECOMMENDATION on ext ended dat a t ypes t hat MAY be defined, arrays SHOULD be declared by using a sequence
wit h an element t ype of which t he number of occurrences is rest rict ed. For example, if an array-t ype myArrayType of 50 long
int egers needs t o be declared, t his could be t he corresponding schema fragment :

<xsd:complexType name="myArrayType">
<xsd:sequence>
<xsd:element name="x" type="xsd:long" minOccurs="50" maxOccurs="50"/>
</xsd:sequence>
</xsd:complexType>

References t o t his t ype (as wit h any XML namespace) can be made in one of t wo ways. The first opt ion is a fully qualified
namespace reference in t he type at t ribut e alone. In t his case t he namespace reference in t he type at t ribut e MUST not only
refer t o t he schema, but also t o t he t ype wit hin t hat schema.

<scpd xmlns="urn:schemas-upnp-org:service-1-0"
configId="configuration number">
...
<dataType type="urn:domain-name:schema-name:datatype-name">
string
</dataType>
...
</scpd>

The second opt ion is t o define t he namespace at t he beginning of t he SCPD document and t hen make a reference in t he t ype
definit ion. In t his case, t he type at t ribut e cont ains a prefix t hat ident ifies t he namespace, followed by t he dat a t ype-named.

<scpd xmlns="urn:schemas-upnp-org:service-1-0"
xmlns:dt="urn:domain-name:schema-name"
configId="configuration number">
...
<dataType type="dt:datatype-name">
string
</dataType>
...
</scpd>

Implement at ions MUST support bot h format s. The first format is pot ent ially easier t o parse, while t he second format may result
in short er descript ion files (i.e. when t he same namespace is used mult iple t imes in t he same document ).

These dat a t ypes writ t en in XSD Schema need not be processed at run-t ime. Inst ead, an implement er MAY use t he referred
schema as a st andard descript ion of t he t ype t o parse for t hat part icular type at t ribut e. To allow run-t ime schema processing of
ext ended dat a t ypes, an opt ional locat ion of t he ext ended dat a t ype schema MAY be expressed in t he SCPD using t he st andard
XSD xsi:schemaLocation and xsi:noNamespaceSchemaLocation at t ribut es as defined in sect ion 4.3.2 of XML Schema Part
1. These at t ribut es can be used in t he root SCPD element (essent ially an inst ance document ) where t he ext ended dat a t ype is
defined, as illust rat ed below:

56

<scpd xmlns="urn:schemas-upnp-org:service-1-0"
xmlns:dt="urn:domain-name:schema-name"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:domain-name:schema-name
http://some.company.com/dir/file.xsd"
configId="configuration number">
...
<dataType type="dt:datatype-name">
string
</dataType>
...
</scpd>

Alt ernat ively, t hese at t ribut es MAY be declared on use in t he <dataType> element where t he exist ing fully qualified namespace
and t ype name for t he ext ended dat a t ype are defined. An example for reference is given below:

<scpd xmlns="urn:schemas-upnp-org:service-1-0"
configId="configuration number">
...
<dataType type="urn:domain-name:schema-name:datatype-name"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://some.company.com/dir/file.xsd">
string
</dataType>
...
</scpd>

2.5.2 String equivalents of extended data types


A number of working commit t ees have creat ed services based on UPnP 1.0 (which does not support ext ended dat a t ypes) t hat
define t heir own encoding of informat ion inside specific st ring-t ype st at e variables. To provide t hese working commit t ees wit h an
upgrade pat h t o ext ended dat at ypes writ t en in nat ive XML3 , a mechanism is defined t hat gives working commit t ees t he opt ion t o
define t he st ring equivalent of an ext ended dat a t ype (working commit t ees can decide not t o). If a st ring equivalent of an
ext ended dat a t ype is defined, t here are t wo valid ways t o represent t he value of t he dat a t ype: eit her as an ext ended dat a t ype,
writ t en in nat ive XML, or as a st ring, t hat encodes t he dat at ype as specified by t he working commit t ee.

The mechanism uses t he USER-AGENT header field in act ion invocat ions and event subscript ions (see also sect ion 2.1, Generic
requirement s on HTTP usage ). If a cont rol point invokes an act ion wit hout a USER-AGENT header field, or if t he USER-AGENT
header field does not specify UPnP version 1.1 or great er, t he values of in-argument s and out -argument s MUST be encoded using
t he st ring equivalent .

If a cont rol point invokes an act ion wit h a USER-AGENT header field t hat specifies UPnP version 1.1 or great er, t he values of inargument s and out -argument s MUST be encoded using t he ext ended dat a t ype writ t en in nat ive XML.

In t his t ext nat ive XML refers t o dat at ypes format t ed according t o XML-schema using t he normal XML format , while st ringequivalent of an ext ended dat at ype refers t o encoding a complex dat a t ype inside a UPnP st ring, examples of which (escaped
XML, comma-separat ed list s) can be found in t he Cont ent Direct ory:1 specificat ion.

57

If a cont rol point has subscribed t o event s wit hout a USER-AGENT header field, or if t he USER-AGENT header field specifies a
UPnP version less t han 1.1, all values of complex-t ype event ed st at e variables t hat are sent t o t he cont rol point MUST be
encoded using t he st ring equivalent . If no st ring equivalent is defined for an event ed st at e variable, subscript ion wit hout t he
correct USER-AGENT header field MUST be refused.

If a cont rol point has subscribed t o event s wit h a USER-AGENT header field t hat specifies UPnP version 1.1 or great er, all values
of complex-t ype event ed st at e variables t hat are sent t o t he cont rol point MUST be encoded using t he ext ended dat a t ype
writ t en in nat ive XML.

2.5.3 Generic requirements


For fut ure ext ensibilit y and according t o t he requirement s in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8,
UPnP Device Schema , when processing XML like t he list ing above, devices and cont rol point s MUST ignore: (a) any unknown
element s and t heir sub element s or cont ent , and (b) any unknown at t ribut es and t heir values.

Subj ect t o t he const raint s defined in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8, UPnP Device Schema ,
cont rol point s and devices MUST ignore any XML comment s or XML processing inst ruct ions embedded in UPnP device and service
descript ions t hat t hey do not underst and. UPnP service descript ions MUST be encoded using UTF-8.

When t he value of any t ext element or at t ribut e cont ains one or more charact ers reserved as markup (such as ampersand ( & )
or less t han ( < )), t he t ext MUST be escaped in accordance wit h t he provisions of sect ion 2.4 of t he XML specificat ion and each
such charact er replaced wit h t he equivalent numeric represent at ion or st ring (such as &amp; or &lt ; ). Such charact ers
appearing in URLs MAY also be percent -encoded in accordance wit h t he URL percent -encoding rules specified in sect ions 2.1 and
2.4 of RFC 3986. Not e t hat it is logically possible for a service t o have no act ions but have st at e variables and event ing; t hough
unlikely, such a service would be an aut onomous informat ion source. However, a service wit h no st at e variables is PROHIBITED.

Unlike device descript ions, service descript ions and associat ed values MUST NOT use locale-specific values; t his includes service
descript ions, values of act ion argument s, and values of st at e variables. Inst ead, most act ion argument s and st at e variables MUST
use values t hat are expressed in a locale-independent manner; cont rol point s MAY convert and/ or format t he informat ion from a
st andard form int o t he correct language and/ or format for t he locale. For example, dat es are represent ed in a localeindependent format (ISO 8601), and int egers are represent ed wit hout locale-specific format t ing (e.g., no currency symbol, no
grouping of digit s). St ring values MUST be represent ed in a locale-independent manner. Variables wit h an allowedValueList MUST
use t oken values in t he language of UPnP st andards and not reflect st rings int ended t o be displayed in a localized user int erface.

2.5.4 Ordering of Elements


The order of XML element s in device and service descript ion document s MUST adhere t o t he order as defined in t he
corresponding specificat ion as defined by t he working commit t ee for t hat device or service t ype. Furt hermore, t he order of

58

element s (e.g. argument s) in cont rol messages and in t heir responses MUST adhere t o t he order defined in t he device s service
descript ion document .

Not e: UPnP 1.0 does NOT REQUIRE t hat t he order of XML element s in device and service descript ion document s adheres t o t he
order as defined in t he corresponding schema (as defined by t he working commit t ee) for t hat device or service t ype. However, it
does REQUIRE t hat cont rol messages and responses are ordered according t o t he corresponding device s service descript ion, a
REQUIREMENT t hat is somet imes overlooked. Therefore, when receiving messages from UPnP 1.0 services, cont rol point s SHOULD
be able t o process out -of-order element s; and when t ransmit t ing messages t o UPnP 1.0 services, cont rol point s MUST send
element s in t he order defined by t hat part icular device s service descript ion.

2.5.5 Versioning
Services st andardized by UPnP Forum working commit t ees have an int eger version. Every lat er version of a service MUST be a
superset of t he previous version, i.e., it MUST include all act ions and st at e variables exact ly as t hey are defined by earlier
versions of t he service. The UPnP service t ype remains t he same across all versions of a service whereas t he service version MUST
be larger for lat er versions. Versions of device and service t emplat es MAY have non-int eger versions (such as 0.9 ) during
development in t he working commit t ee, but t his MUST become an int eger upon st andardizat ion. Devices and services MAY have a
version number great er t han t he maj or version number of t he archit ect ure t hey are designed for (e.g., Power:2 may be
designed t o work on UDA version 1.0).

2.6 UPnP Service Template


The list ing above also illust rat es t he relat ionship bet ween a UPnP service descript ion and a UPnP Service Templat e. As explained
above, t he UPnP descript ion for a service is writ t en by a UPnP vendor, in XML, following a UPnP Service Templat e. A UPnP
Service Templat e is produced by a UPnP Forum working commit t ee as a means t o st andardize devices.

By appropriat e specificat ion of placeholders, t he list ing above can be eit her a UPnP Service Templat e or a UPnP service
descript ion. Recall t hat some placeholders would be defined by a UPnP Forum working commit t ee (colored red), i.e., act ions and
t heir paramet ers, and st at es and t heir dat a t ype, range, and event charact erist ics. If t hese were specified, t he list ing above
would be a UPnP Service Templat e, codifying t he st andard for t his t ype of service. Along wit h UPnP Device Templat es (see
sect ion 2, Descript ion ), UPnP Service Templat es are one of t he key deliverables from UPnP Forum working commit t ees.

Taking t his anot her st ep furt her, t he remaining placeholders in t he list ing above would be specified by a UPnP vendor (colored
purpl e), i.e., addit ional, vendor-specified act ions and st at e variables. If t hese placeholders were specified (as well as t he ot hers),
t he list ing would be a UPnP service descript ion, suit able for effect ive cont rol of t he service wit hin a device.

Put anot her way, t he UPnP Service Templat e defines t he overall t ype of service, and each UPnP service descript ion inst ant iat es
t hat t emplat e wit h vendor-specific addit ions. The first is creat ed by a UPnP Forum working commit t ee; t he lat t er by a UPnP
vendor.

59

2.7 Non-standard vendor extensions and limitations


As explained above, UPnP vendors MAY different iat e t heir devices and ext end a st andard device by including addit ional services
and embedded devices. Similarly, UPnP vendors MAY ext end a st andard service by including addit ional act ions, st at e variables or
allowed values. Naming convent ions and condit ions for each of t hese are list ed in t he t able below and explained in det ail above.

Table 2-1:

Vendor extensions

Type of extension

Standard

Non-Standard

device t ype

urn:schemas-upnp-org:device:deviceType:v

urn:domain-name:device:deviceType:v

service t ype

urn:schemas-upnp-org:service:serviceType:v

urn:domain-name:service:serviceType:v

service ID

urn:upnp-org:serviceId:serviceID

urn:domain-name:serviceId:serviceID

act ion name

MUST comply wit h t he synt ax rules of t he


st andardized act ion name as defined in
sect ion 2.5, Service descript ion .

MUST comply wit h t he synt ax rules of t he


non-st andardized act ion name as defined in
sect ion 2.5, Service descript ion .

st at eVariable name

MUST comply wit h t he synt ax rules of t he


st andardized st at eVariable name as defined in
sect ion 2.5, Service descript ion .

MUST comply wit h t he synt ax rules of t he


non-st andardized st at eVariable name as
defined in sect ion 2.5, Service descript ion .

allowedValue value

MUST be a legal value for a st ring variable. Only


values explicit ly defined by a working
commit t ee are allowed.

Permit t ed only if allowed by t he working


commit t ee. MUST begin wit h a Vendor Domain
Name, followed by t he underscore charact er
( _ ), followed by a legal value for a st ring
variable.

XML element s and t heir


at t ribut es in device or
service descript ion

Defined by t he UPnP Device and Service


Schemas.

Arbit rary XML, scoped by one or more XML


namespaces owned by t he vendor. MUST be
enclosed in an element t hat begins wit h X_ .

XML at t ribut es of
st andard element s in
device or service
descript ion

Defined by t he UPnP Device and Service


Schemas.

Arbit rary at t ribut es, scoped by one or more


XML namespaces, owned by t he vendor. MUST
begin wit h X_ .

As t he last t wo rows of t he t able above indicat e, UPnP vendors MAY also add non-st andard XML t o a device or service descript ion.
Each addit ion MUST be scoped by a vendor-owned XML namespace. Arbit rary XML MUST be enclosed in an element t hat begins
wit h X_, and t his element MUST be a sub element of a st andard complex t ype. Non-st andard at t ribut es MAY be added t o
st andard element s provided t hese at t ribut es are scoped by a vendor-owned XML namespace and begin wit h X_ .

To illust rat e t his, below are list ings wit h placeholders (in it alics) for act ual element s and values. Some of t hese placeholders
would be specified by a UPnP vendor (purple) and some are defined by t he UPnP Device Archit ect ure (green).

<RootStandardElement
xmlns="urn:schemas-upnp-org:device-1-0"
xmlns:n="domain-name:schema-name">
<!-- other XML -->
<AnyStandardElement n:X_VendorAttribute="arbitrary string value">
<!-- other XML -->
</AnyStandardElement>
<!-- other XML -->
</RootStandardElement>

60

<RootStandardElement>
A st andard root element . xmlns at t ribut e defines namespaces, in t his case, a st andard UPnP namespace and a non-st andard
namespace wit h t he prefix n. (Not e: n is j ust a placeholder. A vendor can specify any prefix t o ident ify t he namespace t hat
is valid according t o t he Namespaces in XML specificat ion.)
For device descript ions, MUST be <root>.
For service descript ions, MUST be <scpd>.
<AnyStandardElement>
Any st andard element , root or ot herwise, cont ent of t ext or element only. MUST already be included as part of t he
st andard device or service descript ion. X_VendorAt t ribut e MUST begin wit h X_ . (Prefix A_ is reserved.) MAY have
an arbit rary st ring value.

<StandardComplexType n:X_VendorAttribute="vendor value">


<n:X_VendorElement xmlns:n="domain-name:schema-name">
<!-- arbitrary XML -->
</n:X_VendorElement>
</StandardComplexType>
<StandardComplexType>
Element of complex t ype. MUST already be included as part of t he st andard device or service descript ion.
For device descript ions, MUST be one of: <root>, <specVersion>, <device>, <iconList>, <icon>,
<serviceList>, <service>, or <deviceList>.
For service descript ions, MUST be one of: <scpd>, <actionList>, <action>, <argumentList>, <argument>,
<serviceStateTable>, <stateVariable>, <allowedValueList>, or <allowedValueRange>.
<X_VendorElement>
MUST begin wit h X_ . (Prefix A_ is reserved.) MUST have a value for t he xmlns at t ribut e. MAY cont ain arbit rary
XML.

2.7.1 Placement of Additional Elements and Attributes


Inst ances of any UPnP schema, including device and service descript ions, cont rol act ions, errors and event not ificat ions, MAY
include addit ional XML element s (ot her t han t hose defined by t he UPnP Forum) onl y at t he end of an ordered sequence of
element s corresponding t o a given complex t ype. Addit ionally, inst ances of any UPnP schema MAY include addit ional at t ribut es
wit h any element .

Exception for UPnP 1.0 devices:

UPnP 1.0 allows t he inclusion of addit ional element s anywhere wit hin device and service descript ions, cont rol act ions, errors and
event not ificat ions, provided t hat t he XML is well-formed. Therefore, when receiving messages from UPnP 1.0 devices, cont rol
point s MUST handle unknown element s and at t ribut es found anywhere wit hin t he message.

2.8 UPnP Device Schema


The paragraphs above explain UPnP device descript ions and illust rat e how one would be inst ant iat ed from a UPnP Device
Templat e. As explained, UPnP Device Templat es are produced by UPnP Forum working commit t ees, and t hese t emplat es are
based upon t he UPnP Device Schema. This schema defines t he st ruct ures and dat a t ypes used t o creat e UPnP Device Templat es.
Appendix B.1, UPnP Device Schema cont ains t he schema; below is an explanat ion of t his schema.

61

The UPnP Device Schema is writ t en in XML and according t o t he convent ions of XML Schema (Part 1: St ruct ures, Part 2:
Dat at ypes). XML Schema provides a met hod of describing t he st ruct ure of an XML document . The XML Schema descript ion
language it self is based upon XML. The language is very robust ; it specifies which element s are REQUIRED vs. OPTIONAL, element
nest ing, dat a t ypes for values (as well as ot her propert ies not of int erest here) and much more. The UPnP Device Schema uses
t hese XML Schema const ruct ions t o define element s like <specVersion>, <URLBase>, <deviceType>, et al list ed in det ail
above. Because t he UPnP Device Schema is const ruct ed using a precise descript ion language, it is unambiguous. As t he UPnP
Device Schema, UPnP Device Templat es, and UPnP device descript ions are all machine-readable, soft ware t ools MAY be devised
t o validat e t he lat t er t wo, checking t hat t hey cont ain all t he REQUIRED element s, are correct ly nest ed, and have values of t he
correct dat a t ypes.

2.9 UPnP Service Schema


The paragraphs above explain UPnP service descript ions and illust rat e how one would be inst ant iat ed from a UPnP Service
Templat e. Like UPnP Device Templat es, UPnP Service Templat es are produced by UPnP Forum working commit t ees, and t hese
t emplat es are based upon t he UPnP Service Schema. This schema defines t he st ruct ure and dat a t ypes used t o creat e UPnP
Service Templat es. As explained above, t he UPnP Service Schema is writ t en in XML according t o t he convent ions of XML Schema
(Part 1: St ruct ures, Part 2: Dat at ypes). Appendix B.2, UPnP Service Schema cont ains a list ing of t his schema

2.10 UPnP Datatype Schema


The UPnP basic dat a t ypes for st at e variables are defined in sect ion 2.5, Service descript ion . For any ext ended dat a t ypes for
st at e variables used by a service t emplat e, t he service t emplat e MUST include eit her a reference t o all relevant schemas for t he
ext ended dat a t ypes or include a new service specific dat at ype schema wit h a corresponding unique t arget namespace. If any
ext ended dat a t ypes are used for st at e variables wit hin an SCPD, t he corresponding namespace for each ext ended dat a t ype
MUST be referenced wit hin t he SCPD according t o t he Namespaces in XML specificat ion. Sect ion 2.5, Service descript ion
cont ains an example SCPD wit h namespace declarat ions.

2.11 Retrieving a description using HTTP


As explained above, aft er a cont rol point has discovered a device, it st ill knows very lit t le about t he device. To learn more about
t he device and it s capabilit ies, t he cont rol point MUST ret rieve t he UPnP descript ion for t he device using t he URL provided by t he
device in t he discovery message. Then, t he cont rol point MUST ret rieve one or more service descript ions using t he URL(s)
provided in t he device descript ion. This is a simple HTTP-based process and uses t he following subset of t he overall UPnP
prot ocol st ack. (The overall UPnP prot ocol st ack is list ed at t he beginning of t his document .)

A mult i-homed device MUST send descript ion document s using t he UPnP-enabled int erface on which t he HTTP GET request was
received. To ret rieve t he UPnP descript ion using a part icular int erface, a mult i-homed cont rol point MUST use t he URL provided
in t he discovery message which arrived on t hat int erface.

62

Figure 2-2:

Description retrieval protocol stack


UPnP vendor [purple-it alic]
UPnP Forum [red-it alic]
UPnP Device Architecture [green-bold]
HTTP [black]
TCP [black]
IP [black]

At t he highest layer, descript ion messages cont ain vendor-specific informat ion, e.g., device t ype, service t ype, and required
services. Moving down t he st ack, vendor cont ent is supplement ed by informat ion from a UPnP Forum working commit t ee, e.g.,
model name, model number, and specific URLs. Messages from t he layers above are host ed in UPnP-specific prot ocols, defined in
t his document . In t urn, t he above messages are delivered via HTTP over TCP over IP. For reference, colors in [square bracket s]
above indicat e which prot ocol defines specific header fields and body element s in t he descript ion messages list ed below.

When a cont rol point discovers a device on t he net work, it MAY wish t o ret rieve t he Device Descript ion document and Service
Descript ion Document s. Ret rieving t he UPnP device descript ion is simple: t he cont rol point issues an HTTP GET request t o t he
URL in t he discovery message, and t he device ret urns it s descript ion in t he body of an HTTP response. Similarly, t o ret rieve a
UPnP service descript ion, t he cont rol point issues an HTTP GET request t o t he corresponding URL in t he device descript ion, and
t he device ret urns t he descript ion in t he body of an HTTP response. The header fields and body for t he response and request are
explained in det ail below.

First , a cont rol point MUST send a request wit h met hod GET in t he following format . Values in it alics are placeholders for act ual
values.

GET /descriptionPath HTTP/1.1


HOST: hostname:portNumber
ACCEPT-LANGUAGE: language preferred by control point

(No body for request t o ret rieve a descript ion, but not e t hat t he message MUST have a blank line following t he last HTTP header
field.)
List ed below are det ails for t he request line and header fields appearing in t he list ing above. Field names are not case sensit ive.
All field values are case sensit ive except where not ed. See RFC 2616 and RFC 1945 for furt her requirement s on encoding of
values of t hese fields.
Request line
GET
Met hod defined by HTTP. Can be GET or HEAD.
descript ionPat h
Pat h component of device descript ion URL (LOCATION header field in discovery message) or of t he fully qualified service
descript ion URL. (If t he SCPDURL sub element of t he service element in t he device descript ion is an absolut e URL, t he fully
qualified service descript ion URL is t he SCPDURL sub element . Ot herwise (t he SCPDURL sub element is a relat ive URL), t he
fully qualified service descript ion URL is t he URL resolved from t he SCPDURL sub element in accordance wit h sect ion 5 of

63

RFC 3986, using eit her t he URLBase element , if specified, or t he URL from which t he device descript ion was ret rieved as t he
base URL.) Single, absolut e pat h (see also RFC 2616).
HTTP/ 1.1
The version supported by the control point. (Note: the control point MUST implement all MANDATORY components of the
version specified). MAY be any HTTP version that is backwards compatible to HTTP/ 1.0 (like HTTP/ 1.1).
Header fields
HOST
REQUIRED. Field value cont ains domain name or IP address and opt ional port component s of device descript ion URL
(LOCATION header field in discovery message) or of t he fully qualified service descript ion URL. (If t he SCPDURL sub element
of t he service element in t he device descript ion is an absolut e URL, t he fully qualified service descript ion URL is t he
SCPDURL sub element . Ot herwise (t he SCPDURL sub element is a relat ive URL), t he fully qualif ied service descript ion URL is
t he URL resolved from t he SCPDURL sub element in accordance wit h sect ion 5 of RFC 3986, using eit her t he URLBase
element , if specified, or t he URL from which t he device descript ion was ret rieved as t he base URL.) If t he port is empt y or
not given, port 80 is assumed.
ACCEPT-LANGUAGE
OPTIONAL. RECOMMENDED for ret rieving device descript ions. Field value cont ains preferred language(s) for descript ion. If
no descript ion is available in t his language, device MAY ret urn a descript ion in a default language. See RFC 1766 language
t ag(s).
Aft er a cont rol point sends a request , t he device t akes t he second st ep and responds wit h a copy of it s descript ion. Including
expect ed t ransmission t ime, a device MUST respond wit hin 30 seconds. If it fails t o respond wit hin t his t ime, t he cont rol point
SHOULD re-send t he request . A device MUST send a response in t he following format and in accordance wit h sect ion 2.1,
Generic requirement s on HTTP usage . Two example responses are provided below: one t hat uses t he CONTENT-LENGTH header
field, and one t hat uses chunked encoding (wit h 2 chunks). Values in it alics are placeholders for act ual values.

Not e: XML namespace prefixes do not have t o be t he specific examples shown below (e.g., s or u ); t hey can be any value
t hat obeys t he rules of t he general XML namespace mechanism; a device MUST accept act ion invocat ions t hat use ot her legal XML
namespace prefixes.
Response using CONTENT-LENGTH header field Valid with HTTP/1.0 or HTTP/1.1
HTTP/1.1 200 OK
CONTENT-LANGUAGE: language used in description
CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when responded
Body

Response using chunked encoding Valid with HTTP/1.1 only


HTTP/1.1 200 OK
TRANSFER-ENCODING: chunked
CONTENT-TYPE: text/xml; charset="utf-8"
CONTENT-LANGUAGE: language used in description
DATE: when responded
Length of
Chunk
Length of
Chunk
0

chunk 1 in hexadecimal notation


1
chunk 2 in hexadecimal notation
2

64

The body of t his response is a UPnP device or service descript ion as explained in det ail above. List ed below are det ails for t he
header fields appearing in t he list ing above. Field names are not case sensit ive. All field values are case sensit ive except where
not ed.
Status Line
HTTP/ 1.1
The highest version support ed by t he origin server t hat is compat ible wit h t he cont rol point t hat issued t he request . For
example, if t he cont rol point specified support for HTTP/ 1.0 in t he request , t he response MUST cont ain HTTP/ 1.0.
200 OK
HTTP defined st at us code indicat ing t hat no HTTP errors have occurred.
Header fields
CONTENT-LANGUAGE
REQUIRED if and only if request included an ACCEPT-LANGUAGE header field. Field value cont ains language of descript ion.
RFC 1766 language t ag(s).
CONTENT-LENGTH
REQUIRED if Origin Server does not close t he session aft er sending t he response AND Origin Server does not send t he
response using chunked encoding.
PROHIBITED if Origin Server sends t he response using chunked encoding. OPTIONAL ot herwise.
Field value specifies t he lengt h of t he body in byt es. Int eger.
TRANSFER-ENCODING
OPTIONAL for HTTP/ 1.1 and above. Field value specifies whet her t he response is chunked encoded by having field value
chunked . MUST NOT be specified if CONTENT-LENGTH header field is present .
CONTENT-TYPE
REQUIRED. Field value MUST be t ext / xml; charset ="ut f-8" for descript ion document s.
DATE
RECOMMENDED according t o RFC 2616, sect ion 14.18. Field value cont ains dat e when response was generat ed. rfc1123dat e as defined in RFC 2616.
SERVER
(No SERVER header field is required for descript ion messages.)
Not e t hat because HTTP 1.1 allows use of chunked encoding, some devices MAY send t he descript ion using chunked encoding if
t he GET request specifies HTTP 1.1. Therefore all implement at ions t hat include HTTP 1.1 client support MUST support receiving
chunked encoding.

2.12 References
ISO 8601
ISO (Int ernat ional Organizat ion for St andardizat ion). Represent at ions of dat es and t imes, 1988-06-15. Available
at : ht t p:/ / www.w3.org/ TR/ 1998/ NOTE-dat et ime-19980827.
RFC 822
St andard for t he format of ARPA Int ernet t ext messages. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc822.t xt .
RFC 1123
Includes format for dat es, for, e.g., HTTP DATE header field. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc1123.t xt .
RFC 1766
Format for language t ag for, e.g., HTTP ACCEPT-LANGUAGE header field. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc1766.t xt .
See also ht t p:/ / www.loc.gov/ st andards/ iso639-2 for language codes.
RFC 2045
Mult ipurpose Int ernet Mail Ext ensions (MIME) Part One: Format of Int ernet Message Bodies. Available
at : ht t p:/ / www.iet f.org/ rfc/ rfc2045.t xt .
RFC 2046
Mult ipurpose Int ernet Mail Ext ensions (MIME) Part Two: Media Types. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2046.t xt .

65

RFC 2083
PNG (Port able Net work Graphics) Specificat ion Version 1.0. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2083.t xt . See
also ht t p:/ / www.w3.org/ TR/ REC-png.ht ml.
RFC 2387
Format for represent ing cont ent t ype, e.g., mimet ype element for an icon. Available
at : ht t p:/ / www.iet f.org/ rfc/ rfc2387.t xt .
RFC 2616
HTTP: Hypert ext Transfer Prot ocol 1.1. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2616.t xt .
RFC 3986
Uniform Resource Ident ifiers (URI): Generic Synt ax. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc3986.t xt .
UPC
Universal Product Code. 12-digit , all-numeric code t hat ident ifies t he consumer package. Managed by t he Uniform Code
Council. Available at : ht t p:/ / www.uc-council.org/ main/ ID_Numbers_and_Bar_Codes.ht ml.
XML
Ext ensible Markup Language. Available at : ht t p:/ / www.w3.org/ TR/ 2000/ REC-xml-20001006.
XML Schema (Part 1: St ruct ures, Part 2: Dat at ypes). Available at :
ht t p:/ / www.w3.org/ TR/ xmlschema-1, ht t p:/ / www.w3.org/ TR/ xmlschema-2.
Namespaces in XML
Available at : ht t p:/ / www.w3.org/ TR/ REC-xml-names/ .

66

3 Control
[Normative]
Cont rol is St ep 3 in UPnPnet working. Cont rol comes af t er addressing (St ep 0) where devices get a net work address, af t er
discovery (St ep 1) where cont rol point s f ind int erest ing device(s), and af t er descript ion (St ep 2) where cont rol point s learn
about device capabilit ies. Cont rol is independent of event ing (St ep 4) where cont rol point s l ist en t o st at e changes in device(s).
Through cont rol, cont rol point s invoke act ions on devices and poll f or values. Cont rol and event ing are compl ement ary t o
present at ion (St ep 5) where cont rol point s display a user int erf ace provided by device(s).

Given knowledge of a device and it s services, a cont rol point can ask t hose services t o invoke act ions and receive responses
indicat ing t he result of t he act ion. Invoking act ions is a kind of remot e procedure call; a cont rol point sends t he act ion t o t he
device's service, and when t he act ion has complet ed (or failed), t he service ret urns any result s or errors.

Figure 3-1:

Control architecture
root device
control point

SOAP action
service
SOAP resp

device
service
service

To cont rol a device, a cont rol point invokes an act ion on t he device's service. To do t his, a cont rol point sends a suit able cont rol
message t o t he fully qualified cont rol URL for t he service obt ained from t he cont rolURL sub element of t he service element of
t he device descript ion. If t he cont rolURL sub element is an absolut e URL, t he fully qualified cont rol URL for t he service is t he
cont rolURL sub element . Ot herwise (t he cont rolURL sub element is a relat ive URL), t he fully qualified cont rol URL for t he service
is t he URL resolved from t he cont rolURL sub element in accordance wit h sect ion 5 of RFC 3986, using eit her t he URLBase element
of t he device descript ion, if specified, or t he URL from which t he device descript ion was ret rieved as t he base URL. A mult ihomed cont rol point t hat sends t he cont rol message on a part icular int erface MUST use t he fully qualified cont rol URL from t he
descript ion document received on t hat int erface. In response, t he service ret urns any result s or errors from t he act ion. The
effect s of t he act ion, if any, MAY also be modeled by changes in t he variables t hat describe t he run-t ime st at e of t he service.
When t hese st at e variables change, event s are published t o all int erest ed cont rol point s. This sect ion explains t he prot ocol st ack
for, and format of, cont rol messages. Sect ion 4, Event ing explains event publicat ion.

67

Working commit t ees and vendors MAY define act ions t o allow cont rol point s t o det ermine t he current value of one or more st at e
variables. Similar t o invoking an act ion, a cont rol point sends t he defined query message t o t he cont rol URL for t he service. In
response, t he service provides t he value of t he variable or variables; each service is responsible for keeping it s st at e t able
consist ent so cont rol point s can poll and receive meaningful values for t hose st at e variables for which query act ions are defined.
Sect ion 4, Event ing explains aut omat ic not ificat ion of variable values.

As long as one of t he discovery advert isement s from a device have not expired, a cont rol point MAY assume t hat t he device and
it s services are available. If a device cancels at least one of it s advert isement s, a cont rol point MUST assume t he device and it s
services are no longer available.

Cont rol point s and devices MUST use UTF-8 for all UPnP cont rol messages and responses.

While UDA does define a means t o invoke act ions and poll for values, UDA does not specify or const rain t he design of an API for
applicat ions running on cont rol point s; OS vendors MAY creat e APIs t hat suit t heir cust omers needs.

If a large amount of dat a must be sent in associat ion wit h an act ion (part icularly if t he amount of dat a is not known in advance),
it is NOT RECOMMENDED t o send t he dat a as part of a SOAP argument or as a MIME at t achment t o t he SOAP message. Inst ead, it is
RECOMMENDED t hat out -of-band t ransfer be used. For example, a URL could be sent as an argument value, and an HTTP GET,
PUT, or POST be used t o t ransfer t he dat a. HTTP chunked encoding can be used when t he amount of dat a is not known in
advance.

Responses t o SOAP messages during t he Cont rol phase MUST be sent t o t he same IP address from which t he request was received.
Any fully-qualified URLs cont ained in an act ion or response t hat refer t o a resource on t he device it self MUST have t he HOST
port ion of t he URL set appropriat ely so t hat t he resource will be reachable by t he cont rol point t hat request ed t he act ion. This
might be accomplished by using t he field value specified in t he HTTP HOST header field of t he cont rol request .

Services t hat use complex dat at ype argument s MUST follow t he requirement s in sect ion 2.5, Service descript ion

The remainder of t his sect ion explains in det ail how cont rol messages are format t ed and sent t o devices.

68

3.1 Control protocols


To invoke act ions and poll for values, cont rol point s (and devices) use t he following subset of t he overall UPnP prot ocol st ack.
(The overall UPnP prot ocol st ack is list ed at t he beginning of t his document .)

Figure 3-2:

Control protocol stack


UPnP vendor [purple-it alic]
UPnP Forum [red-it al ic]
UPnP Device Architecture [green-bold]
SOAP [blue]
HTTP [black]
TCP [black]
IP [black]

At t he highest layer, cont rol messages cont ain vendor-specific informat ion, e.g., argument values. Moving down t he st ack,
vendor cont ent is supplement ed by informat ion from a UPnP Forum working commit t ee, e.g., act ion names, argument names,
variable names. Messages from t he layers above are host ed in UPnP-specific prot ocols, defined in t his document . In t urn, t he
above messages are format t ed using a Simple Obj ect Access Prot ocol (SOAP) header and body element s, and t he messages are
delivered via HTTP over TCP over IP. For reference, colors in [square bracket s] above indicat e which prot ocol defines specific
header field element s in t he subscript ion messages list ed below.

The generic requirement s on HTTP usage in UPnP 1.1 (as defined in sect ion 2.1, Generic requirement s on HTTP usage of t his
document ) MUST be followed by devices and cont rol point s t hat implement Cont rol.

3.1.1 SOAP Profile


UPnP profiles SOAP 1.1, NOT REQUIRING t hat all devices support all OPTIONAL feat ures of SOAP 1.1, but devices and cont rol
point s MUST support all MANDATORY feat ures of SOAP 1.1. The following t able summarizes t he UPnP profiling of SOAP.

69

Table 3-1:

SOAP 1.1 UPnP Profile


Mandatory
Optional

UPnP Control Request


<Envelope> element

Prohibited

Comment

encodingStyle at t ribut e of <Envelope>

<Header> element (child element of <Envelope>)

If present , must be
"ht t p:/ / schemas.xmlsoap.org/ soap/ encoding/ "

actor at t ribut e of <Header>

mustUnderstand at t ribut e of <Header>

Only allowed if defined by t he service t o which it is


direct ed

encodingStyle at t ribut e of <Header>

If present , must be
"ht t p:/ / schemas.xmlsoap.org/ soap/ encoding/ "

<Body> element (child element of <Envelope>)

Exact ly one <Body> child element allowed

encodingStyle at t ribut e of <Body> element

root At t ribut e of <Body> child element

SHOULD NOT be used

UPnP Control Response


<Envelope> element

encodingStyle at t ribut e of <Envelope>

<Header> element (child element of <Envelope>)

If present , must be
"ht t p:/ / schemas.xmlsoap.org/ soap/ encoding/ "

actor at t ribut e of <Header>

mustUnderstand at t ribut e of <Header>

Only allowed if defined by t he service t o which it is


direct ed

encodingStyle At t ribut e of <Header>

If present , must be
"ht t p:/ / schemas.xmlsoap.org/ soap/ encoding/ "

<Body> element (child element of <Envelope>)

Exact ly one <Body> child element allowed

encodingStyle at t ribut e of <Body> element

root at t ribut e of <Body> child element

SHOULD NOT be used

UPnP Control Error Response


<Envelope> element

encodingStyle at t ribut e of <Envelope>

If present , must be
"ht t p:/ / schemas.xmlsoap.org/ soap/ encoding/ "

<Body> element (child element of <Envelope>)

Exact ly one <Body> child element allowed


cont aining exact ly one <Fault> child element

<Fault> child element of <Body>

<faultcode> child element of <Fault>

<faultstring> child element of <Fault>

<detail> child element of <Fault>

SOAP 1.1 allows t he use of foot ers, which are disallowed in SOAP 1.2. A UPnP message MUST NOT have any child element s of t he
<Envelope> element following t he <Body> element .

70

SOAP <Header> element


UPnP working commit t ees and t he UPnP t echnical commit t ee MAY define OPTIONAL or MANDATORY SOAP header ent ries t hat are
included in t he SOAP <Header> element of UPnP act ion and UPnP act ion response messages. In addit ion, vendors MAY include
ot her SOAP header ent ries in t he SOAP <Header> element of UPnP act ion and UPnP act ion response messages. If t here are no
SOAP header ent ries in a message, t he SOAP <Header> element can be omit t ed.
SOAP mustUnderstand Attribute of <Header> element
The must Underst and at t ribut e MUST NOT be added t o SOAP <Header> element t arget ed at (see also actor at t ribut e below)
st andardized UPnP services or t arget ed at cont rol point s t hat int eract wit h st andardized UPnP services, unless it s use has been
explicit ly defined by t he UPnP t echnical commit t ee or a working commit t ee (e.g. UPnP securit y).

The mustUnderstand header at t ribut e MUST NOT be included on non-st andard header ent ries t hat are t arget ed at (see also
act or at t ribut e) st andardized services, as t his breaks t he basic int eroperabilit y of UPnP. mustUnderstand header ent ries MAY
be included on non-st andard header ent ries t hat are neit her t arget ed at (see also actor at t ribut e) st andardized services (e.g.
vendor defined services), nor t arget ed at cont rol point s int eract ing wit h st andardized services.

Table 3-2:

mustUnderstand attribute

SOAP Node Type

v1.0

Transmit t ing Node t arget ing


a st andardized service or a
cont rol point t hat int eract s
wit h a st andardized service.

The mustUnderstand at t ribut e MUST NOT be added t o SOAP header ent ries,
unless t he UPnP t echnical commit t ee or a working commit t ee has explicit ly defined
it s use.

Transmit t ing Node t arget ing


a vendor specific service or
a vendor specific SOAP
node.

MUST t arget endpoint (see actor


sect ion below).

MAY t arget int ermediaries (see actor


sect ion below).

The mustUnderstand at t ribut e MAY


be used at t he discret ion of t he
vendor.

The mustUnderstand at t ribut e MAY be


used at t he discret ion of t he vendor.

All unknown <Header> ent ries are


ignored, except when explicit ly
defined different ly by a working
commit t ee (UPnP Securit y).

All devices MUST honor t he actor (see


actor sect ion below) and
mustUnderstand at t ribut es. If a
header ent ry wit h
mustUnderstand="1" is not
underst ood, t he whole message fails and
a <Faultcode> element MUST be
ret urned.

Receiving Node

v1.1

The SOAP mustUnderstand at t ribut e has a rest rict ed t ype of "xsd:boolean" t hat t akes only 0 or 1 wit h 1 being t rue and
0 being false. A header ent ry wit h t he mustUnderstand at t ribut e set t o a value of 1 MUST be processed by t arget ed nodes
or message processing MUST fail. Such element s are considered MANDATORY header ent ries . A SOAP node is considered t o
underst and a SOAP header ent ry if t hat SOAP node underst ands t he semant ics specified for t he XML expanded name of t he out ermost element informat ion it em of t hat header ent ry. MANDATORY SOAP header ent ries are presumed t o modify t he semant ics of
ot her SOAP header ent ries or SOAP <Body> element s and t herefore MUST be underst ood for correct semant ics. UPnP nodes
receiving header ent ries flagged wit h t he mustUnderstand at t ribut e MUST process and underst and MANDATORY header ent ries
t hat are t arget ed at t hat node or t he node MUST NOT process t he SOAP message at all. If a node fails t o process or underst and a

71

MANDATORY ent ry, t hat node MUST generat e a SOAP Fault wit h t he <faultcode> element set t o "Must Underst and". Support
for MANDATORY header ent ries assures t hat key message part s t hat are t arget ed at a part icular SOAP node will not be
erroneously ignored.

If a <Header> ent ry is a MANDATORY <Header> ent ry and cont ains ent ries not underst ood by t he t arget ed SOAP node, t he SOAP
node MAY at t empt processing wit hout underst anding t he semant ics of t he ext ensions. MANDATORY ext ensions are not possible.
SOAP actor Attribute of <Header> element
The SOAP actor at t ribut e is used in SOAP 1.1 t o ident ify t he URI of SOAP node t hat is t o process t he <Header> ent ry. All SOAP
nodes play t he role of "ht t p:/ / schemas.xmlsoap.org/ soap/ act or/ next " , which is t he first node (device or cont rol point ) t hat
processes t he message. The lack of an actor at t ribut e indicat es t hat t he ent ry is t arget ed at t he dest inat ion. All UPnP defined
<Header> element s MUST be t arget ed at t he dest inat ion, unless explicit ly defined ot herwise by t he UPnP t echnical commit t ee
or a working commit t ee. Therefore, it is RECOMMENDED t hat t he act or at t ribut e is not included on UPnP <Header> ent ries.

<Header> ent ries wit hin messages t hat are sent t o UPnP 1.0 devices or cont rol point s MUST NOT be t arget ed at int ermediaries
(no act or at t ribut e), since UPnP 1.0 devices and cont rol point s might ignore t he act or at t ribut e and parse a <Header> ent ry t hat
is not int ended for t hem.

If <Header> ent ries wit h an act or at t ribut e are t arget ed at an int ermediary and t agged mustUnderstand="1", t he device or
cont rol point MUST NOT ret urn a SOAP Fault cont aining t he <faultcode> element set t o "Must Underst and" due t o failure t o
process t he relevant <Header> element t arget ed at anot her ent it y.
SOAP root Attribute
UPnP 1.1 REQUIRES t hat t he first child element of t he <Body> element MUST be t he root of t he RPC request . Since UPnP 1.1
defines an RPC-archit ect ure, t here can only be one root . The serializat ion root SHOULD NOT use t he root at t ribut e, but it is
NOT PROHIBITED.
SOAP encodingStyle Attribute
UPnP 1.1 REQUIRES t hat devices and cont rol point s MUST be able t o receive messages t hat do not cont ain t he SOAP
encodingStyle at t ribut e, as well as messages t hat cont ain t he SOAP encodingStyle at t ribut e wit h value
"ht t p:/ / schemas.xmlsoap.org/ soap/ encoding/ ". When encodingStyle is not included, t he encodingStyle is
ht t p:/ / schemas.xmlsoap.org/ soap/ encoding/ .

When communicat ing wit h UPnP 1.0 devices or cont rol point s, an encodingStyle at t ribut e MUST be included on t he SOAP
<Envelope> element wit h value "ht t p:/ / schemas.xmlsoap.org/ soap/ encoding/ . When communicat ing wit h UPnP 1.1 devices or
cont rol point s, t he encodingStyle at t ribut e SHOULD be included and, if present , MUST have t he value
"ht t p:/ / schemas.xmlsoap.org/ soap/ encoding/ ".

If addit ional encodings are needed for applicat ion dat a, applicat ions MAY use out of band dat a encoding for t he relevant dat a.

72

SOAP

element

UPnP 1.1 REQUIRES a element . It cont ains body ent ries for UPnP Act ions and Responses. The act ual ent ries are derived
from t he Service Descript ion for t he chosen Act ion. A response is eit her successful, in which case it cont ains out put argument s,
or unsuccessful, when it cont ains a <Fault> element as t he only ent ry.
SOAP <Fault> element of

element

UPnP REQUIRES t he use of SOAP <Fault> element s when a failure response is ret urned. Please see Table 3-2, must Underst and
at t ribut e on usage of t he mustUnderstand at t ribut e for how t he <detail> element MUST be const ruct ed. When a <Header>
element is encount ered t hat is a MANDATORY <Header> element , t he cont rol point or device MUST eit her recognize t he element
or ret urn t he appropriat e SOAP <Fault> element , cont aining t he <faultcode> element set t o MustUnderstand .
Backwards-compat ible services MUST NOT use MANDATORY <Header> element s since previous UDAs allowed unknown <Header>
element s t o be ignored.
Acceptable SOAP Character Encodings
All messages MUST use UTF-8 serializat ion. The device or cont rol point MUST indicat e t he cont ent t ype for all cont rol messages
using t he HTTP charset paramet er.

3.2 Actions
Cont rol point s MAY invoke act ions on a device's services and receive result s or errors back. The act ion, result s, and errors are
encapsulat ed in SOAP, sent via HTTP request s, and received via HTTP responses.

3.2.1 Action invocation


The Simple Obj ect Access Prot ocol (SOAP) defines t he use of XML and HTTP for remot e procedure calls. UPnP 1.1 uses HTTP t o
deliver SOAP 1.1 encoded cont rol messages t o devices and ret urn result s or errors back t o cont rol point s. See sect ion 2.1,
Generic requirement s on HTTP usage on use of HTTP in UPnP 1.1.

UPnP 1.1 deprecat es t he use of t he HTTP Ext ension Framework (RFC 2774) for cont rol. Specifically, cont rol point s MUST send a
request wit h met hod POST and MUST NOT use t he M-POST met hod. Devices MUST NOT rej ect POST met hods wit h a 405 Met hod
Not Allowed HTTP st at us code since t his causes UPnP 1.0 cont rol point s t o issue a request using M-POST.

Below is a list ing of a cont rol message sent using t he POST met hod followed by an explanat ion of t he header fields and body. To
invoke an act ion on a device's service, a cont rol point MUST send a request wit h met hod POST in t he following format . Two
examples are provided: one using t he CONTENT-LENGTH header and one using chunked encoding (wit h 2 chunks). Values in
it alics are placeholders for act ual values.

Not e: XML namespace prefixes do not have t o be t he specific examples shown below (e.g., s or u ); t hey can be any value
t hat obeys t he rules of t he general XML namespace mechanism; a device MUST accept act ion invocat ions t hat use ot her legal XML
namespace prefixes.

73

Action invocation using the CONTENT-LENGTH header Valid with HTTP/1.0 or HTTP/1.1
POST path control URL HTTP/1.0
HOST: hostname:portNumber
CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
USER-AGENT: OS/version UPnP/1.1 product/version
SOAPACTION: "urn:schemas-upnp-org:service:serviceType:v#actionName"
<?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:actionName xmlns:u="urn:schemas-upnp-org:service:serviceType:v">
<argumentName>in arg value</argumentName>
<!-- other in args and their values go here, if any -->
</u:actionName>
</s:Body>
</s:Envelope>

Action invocation using chunked encoding Valid with HTTP/1.1 only


POST path control URL HTTP/1.1
HOST: hostname:portNumber
TRANSFER-ENCODING: "chunked"
CONTENT-TYPE: text/xml; charset="utf-8"
USER-AGENT: OS/version UPnP/1.1 product/version
SOAPACTION: "urn:schemas-upnp-org:service:serviceType:v#actionName"
Length of first chunk in hexadecimal notation
<?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:actionName xmlns:u="urn:schemas-upnp-org:service:serviceType:v">
<argumentName>in arg value</argumentName>
<!-- other in args and their value go here, if any -->
</u:actionName>
</s:Body>
Length of second chunk in hexadecimal notation
</s:Envelope>
0

List ed below are det ails for t he request line, header fields, and body element s appearing in t he list ing above. Field names are
not case sensit ive. All HTTP field values and XML element names are case sensit ive; XML values are not case sensit ive except
where not ed. Except where not ed, REQUIRED element s MUST occur exact ly once (no duplicat es), and RECOMMENDED or
OPTIONAL element s MAY occur at most once.
Request line
POST
Met hod defined by HTTP.
pat h cont rol URL
Pat h component of t he fully qualified cont rol URL for t his service. Single, absolut e pat h (see also RFC 2616, sect ion 3.2.2).
HTTP/ 1.1
The version support ed by t he cont rol point . (Not e: t he cont rol point MUST implement all MANDATORY component s of t he
version specified). MAY be any HTTP version t hat is backwards compat ible t o HTTP/ 1.0 (like HTTP/ 1.1).

74

Header fields
HOST
REQUIRED. Field value cont ains domain name or IP address and OPTIONAL port component s of fully qualified cont rol URL for
t his service. If t he port is empt y or not given, port 80 is assumed.
ACCEPT-LANGUAGE
PROHIBITED. The ACCEPT-LANGUAGE header field MUST NOT be used in cont rol messages.
CONTENT-LENGTH
REQUIRED if Origin Server does not close t he session aft er sending t he act ion invocat ion AND Origin Server does not send t he
act ion invocat ion using chunked encoding.
PROHIBITED if Origin Server sends t he act ion invocat ion using chunked encoding. OPTIONAL ot herwise.
Field value specifies t he lengt h of t he body in byt es. Int eger.
TRANSFER-ENCODING
OPTIONAL for HTTP/ 1.1 and above. Field value specifies whet her t he act ion invocat ion is chunked encoded by having field
value chunked . MUST NOT be specified if CONTENT-LENGTH header field is present .
CONTENT-TYPE
REQUIRED. Field value MUST be t ext / xml; charset ="ut f-8" .
USER-AGENT
OPTIONAL. Specified by UPnP vendor. St ring. Field value MUST begin wit h t he following product t okens (defined by
HTTP/ 1.1). The first product t oken ident ifes t he operat ing syst em in t he form OS name/ OS version, t he second t oken
represent s t he UPnP version and MUST be UPnP/ 1.1, and t he t hird t oken ident ifes t he product using t he form
product name/ product version. For example, USER-AGENT: unix/ 5.1 UPnP/ 1.1 MyProduct / 1.0 . Cont rol point s MUST be
prepared t o accept a higher minor version number of t he UPnP version t han t he cont rol point it self implement s. For
example, cont rol point s implement ing UDA version 1.0 will be able t o int eroperat e wit h devices implement ing
UDA version 1.1. See sect ion 2.5, Service descript ion .
SOAPACTION
REQUIRED header field defined by SOAP. Field value MUST be t he service t ype, hash mark, and name of act ion t o be invoked,
all enclosed in double quot es. The specified service version MUST indicat e t he version of t he service t hat t he cont rol point
want s t o use while invoking t he act ion. It s value may be any version of t he service t ype in which t he specified act ion was
defined. When a cont rol point invokes an act ion t hat has been defined in version K of a service, version number v MUST be
equal or higher t han K. For example, if an act ion has been defined in version 2 of a service, it MUST NOT be invoked using
v=1. Furt hermore; version v MUST be a version t hat is support ed by t he device. For example, for devices t hat support only
version 1 of a service, v MUST be 1. Single URI.
Body
<Envelope>
REQUIRED element defined by SOAP. xmlns namespace at t ribut e MUST be "ht t p:/ / schemas.xmlsoap.org/ soap/ envelope/ ". MUST
include encodingStyle at t ribut e wit h value "ht t p:/ / schemas.xmlsoap.org/ soap/ encoding/ ". A receiver MUST generat e a fault
if it encount ers a message whose <document> element has a local name of "Envelope" but a namespace name t hat is not
"ht t p:/ / schemas.xmlsoap.org/ soap/ envelope/ ". Cont ains t he following sub element s:
<Body>
REQUIRED element defined by SOAP. MUST be qualified wit h SOAP namespace. Cont ains t he following ent ry:
<actionName>
REQUIRED. Name of element is name of act ion t o invoke. xmlns namespace at t ribut e MUST be t he
service t ype enclosed in double quot es. The version specified MUST be t he same version specified in t he
SOAPACTION header field. Case sensit ive. MUST be t he first child element of <Body>. Cont ains t he
following, ordered sub element (s):
<argumentName>
REQUIRED if and only if act ion has in argument s. Value t o be passed t o act ion. Repeat once for
each in argument . (An element name is not qualified by a namespace; element nest ing
cont ext is sufficient .) Case sensit ive. Single dat a t ype as defined by UPnP service descript ion.
Every in argument in t he definit ion of t he act ion in t he service descript ion MUST be
included, in t he same order as specified in t he service descript ion (SCPD) t hat is available
from t he device.
If t he CONTENT-TYPE header field specifies an unsupport ed field value (ot her t hen t ext / xml ) t he device MUST ret urn a 415
Unsupport ed Media Type HTTP st at us code.

75

For fut ure ext ensibilit y and according t o t he requirement s in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8,
UPnP Device Schema , when processing XML like t he list ing above, devices and cont rol point s MUST ignore: (a) any unknown
element s and t heir sub element s or cont ent , and (b) any unknown at t ribut es and t heir values.

Subj ect t o t he const raint s defined in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8, UPnP Device Schema ,
cont rol point s and devices MUST ignore any XML comment s or XML processing inst ruct ions embedded in act ion request s t hat t hey
do not underst and.

When t he value of any argument cont ains one or more charact ers reserved as markup (such as ampersand ( & ) or less t han
( < )), t hen t he t ext MUST be escaped in accordance wit h t he provisions of sect ion 2.4 of t he XML specificat ion and each such
charact er replaced wit h t he equivalent numeric represent at ion or st ring (such as &amp; or &lt ; ). Such charact ers appearing
in URLs MAY also be percent -encoded in accordance wit h t he URL percent -encoding rules specified in sect ions 2.1 and 2.4 of RFC
3986.

Not e t hat because HTTP 1.1 allows use of chunked encoding, some cont rol point s MAY send t he act ion request using chunked
encoding if t he POST met hod specifies HTTP 1.1. Device implement at ions t hat only support HTTP/ 1.0 and t hus do not support
receiving act ion request s using chunked encoding MUST ret urn a 505 HTTP Version Not Support ed HTTP st at us code. Cont rol
point s MUST NOT make HTTP 1.1 chunked POST request s t o devices t hat are known t o support only HTTP 1.0.

On a mult i-homed cont rol point , all fully qualified URLs cont ained in t he act ion argument s t hat refer t o resources on t he cont rol
point MUST be reachable on t he int erface on which t he act ion request is sent .

3.2.2 Action Response


The service MUST complet e invoking t he act ion and respond wit hin 30 seconds, including expect ed t ransmission t ime (measured
from t he t ime t he act ion message is t ransmit t ed unt il t he t ime t he associat ed response is received). Act ions t hat t ake longer
t han t his SHOULD be defined t o ret urn early and send an event when complet e. If t he service fails t o respond wit hin t his t ime,
what t he cont rol point SHOULD do is applicat ion-specific. A mult i-homed device MUST send t he response on t he same
UPnP-enabled int erface on which t he request was received. The service MUST send a successful complet ion response using t he
following format . The following t wo examples illust rat e an act ion response using t he CONTENT-LENGTH header and an act ion
response using chunked encoding. The values in it al ics are placeholders for act ual values.

Not e; XML namespace prefixes do not have t o be t he specific examples shown below (e.g., s or u ); t hey can be any value
t hat obeys t he rules of t he general XML namespace mechanism; cont rol point s MUST accept act ion responses t hat use ot her legal
XML namespace prefixes.

76

Action response using the CONTENT-LENGTH header Valid with HTTP/1.0 or HTTP/1.1
HTTP/1.0 200 OK
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated
SERVER: OS/version UPnP/1.1 product/version
CONTENT-LENGTH: bytes in body
<?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:actionNameResponse xmlns:u="urn:schemas-upnp-org:service:serviceType:v">
<argumentName>out arg value</argumentName>
<!-- other out args and their values go here, if any -->
</u:actionNameResponse>
</s:Body>
</s:Envelope>

Action response using chunked encoding Valid with HTTP/1.1 only


HTTP/1.1 200 OK
TRANSFER-ENCODING: "chunked"
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated
SERVER: OS/version UPnP/1.1 product/version
Length of first chunk in hexadecimal notation
<?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:actionNameResponse xmlns:u="urn:schemas-upnp-org:service:serviceType:v">
<argumentName>out arg value</argumentName>
<!-- other out args and their values go here, if any -->
</u:actionNameResponse>
</s:Body>
</s:Envelope>
0

List ed below are det ails for t he response line, header fields, and body element s appearing in t he list ing above. Field names are
not case sensit ive. All HTTP field values and XML element names are case sensit ive; XML values are not case sensit ive except
where not ed. Except where not ed, REQUIRED element s MUST occur exact ly once (no duplicat es), and RECOMMENDED or
OPTIONAL element s MAY occur at most once.
Response line
HTTP/ 1.1
The highest version support ed by t he origin server t hat is compat ible wit h t he cont rol point t hat issued t he request .
For example, if t he cont rol point specified support for HTTP/ 1.0 in t he request , t he response MUST cont ain HTTP/ 1.0.
200 OK
HTTP defined st at us code indicat ing t hat no HTTP errors were det ect ed.
Header fields
CONTENT-LANGUAGE
PROHIBITED. The CONTENT-LANGUAGE header field MUST NOT be used in cont rol messages.
CONTENT-LENGTH
REQUIRED if Origin Server does not close t he session aft er sending t he response AND Origin Server does not send t he
response using chunked encoding.
PROHIBITED if Origin Server sends t he response using chunked encoding. OPTIONAL ot herwise.

77

Field value specifies t he lengt h of t he body in byt es. Int eger.


TRANSFER-ENCODING
OPTIONAL for HTTP/ 1.1 and above. Field value specifies whet her t he response is chunked encoded by having field value
chunked (in t he example, t he ent ire body is sent in a single chunk). MUST NOT be specified if CONTENT-LENGTH header
field is present .
CONTENT-TYPE
REQUIRED. Field value MUST be t ext / xml; charset ="ut f-8" .
DATE
RECOMMENDED. Field value cont ains dat e when response was generat ed. rfc1123-dat e as defined in RFC 2616.
SERVER
REQUIRED. Specified by UPnP vendor. St ring. Field value MUST begin wit h t he following product t okens (defined by
HTTP/ 1.1). The first product t oken ident ifes t he operat ing syst em in t he form OS name/ OS version, t he second t oken
represent s t he UPnP version and MUST be UPnP/ 1.1, and t he t hird t oken ident ifes t he product using t he form
product name/ product version. For example, SERVER: unix/ 5.1 UPnP/ 1.1 MyProduct / 1.0 . Cont rol point s MUST be
prepared t o accept a higher minor version number of t he UPnP version t han t he cont rol point it self implement s. For
example, cont rol point s implement ing UDA version 1.0 will be able t o int eroperat e wit h devices implement ing
UDA version 1.1.
Body
<Envelope>
REQUIRED element defined by SOAP. xmlns namespace at t ribut e MUST be "ht t p:/ / schemas.xmlsoap.org/ soap/ envelope/ ". MUST
include encodingStyle at t ribut e wit h value "ht t p:/ / schemas.xmlsoap.org/ soap/ encoding/ ". A receiver MUST generat e a fault
if it encount ers a message whose document element has a local name of "Envelope" but a namespace name t hat is not
"ht t p:/ / schemas.xmlsoap.org/ soap/ envelope/ ". Cont ains t he following sub element s:
<Body>
REQUIRED element defined by SOAP. MUST be qualified wit h SOAP namespace. Cont ains t he following ent ry:
<actionNameResponse>
REQUIRED. Name of element is act ion name prepended t o Response. xmlns namespace at t ribut e MUST
be service t ype enclosed in double quot es. Devices t hat support t he same act ion in mult iple namespaces
MUST use t he same namespace in t he response as was used in t he act ion invocat ion. For example, if an
act ion was invoked using namespace:
urn:schemas-upnp-org:service:ContentDirectory:2
The response MUST also use namespace:
urn:schemas-upnp-org:service:ContentDirectory:2
Case sensit ive. MUST be t he first sub element of <Body>. Cont ains t he following sub element :
<argumentName>
REQUIRED if and only if act ion has out argument s. Value ret urned from act ion. Repeat once
for each out argument . If act ion has an argument marked wit h t he <retval/> element , t his
argument MUST be t he first element . (An element name not qualified by a namespace;
element nest ing cont ext is sufficient .) Case sensit ive. Single dat a t ype as defined by UPnP
service descript ion. Every out argument in t he definit ion of t he act ion in t he service
descript ion MUST be included, in t he same order as specified in t he service descript ion (SCPD)
available from t he device.

For fut ure ext ensibilit y and according t o t he requirement s in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8,
UPnP Device Schema , when processing XML like t he list ing above, devices and cont rol point s MUST ignore: (a) any unknown
element s and t heir sub element s or cont ent , and (b) any unknown at t ribut es and t heir values.

Subj ect t o t he const raint s defined in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8, UPnP Device Schema ,
cont rol point s and devices MUST ignore any XML comment s or XML processing inst ruct ions embedded in act ion responses t hat
t hey do not underst and.

On a mult i-homed device, all fully qualified URLs cont ained in response argument s t hat refer t o resources on t he device MUST be
reachable on t he UPnP-enabled int erface on which t he response message is sent .

78

3.2.3 UPnP Action Schema


The UPnP Act ion Schema defines t he st ruct ures and dat a t ypes used in t he body of UPnP act ions and act ion responses. As
explained wit h t he UPnP Device and Service Schemas, t he UPnP Act ion Schema is writ t en in XML synt ax according t o t he
convent ions of XML Schema (Part 1: St ruct ures, Part 2: Dat at ypes). The UPnP Act ion Schema is defined wit hin a UPnP service
t emplat e; however, t he schema MUST conform t o t he format as defined in appendix B.3, UPnP Cont rol Schema . The element s
it defines are used in act ions and act ion responses.

3.2.4 Recommendations and additional requirements


Cont rol point s and devices MUST ignore any XML comment s or XML processing inst ruct ions t hey may receive t hat t hey do not
underst and.

XML namespace prefixes do not have t o be t he specific examples given above (e.g., s or u ); t hey can be any value t hat obeys
t he rules of t he general XML namespace mechanism; cont rol point s MUST accept responses t hat use ot her legal XML namespace
prefixes.

If an act ion has no out argument s, it is valid t o combine t he opening and closing XML t ags (e.g., <actionNameResponse/>
inst ead of <actionNameResponse></actionNameResponse> ).

When t he value of any argument cont ains one or more charact ers reserved as markup (such as ampersand ( & ) or less t han
( < )), t he t ext MUST be escaped in accordance wit h t he provisions of sect ion 2.4 of t he XML specificat ion and each such
charact er replaced wit h t he equivalent numeric represent at ion or st ring (such as &amp; or &lt ; ). Such charact ers appearing
in URLs MAY also be percent -encoded in accordance wit h t he URL percent -encoding rules specified in sect ions 2.1 and 2.4 of RFC
3986.

3.2.5 Action error response


Where t he normal out come of processing a SOAP message would have result ed in t he t ransmission of a SOAP response, but rat her
a SOAP Fault is generat ed inst ead, a receiver MUST t ransmit a SOAP Fault message in place of t he response. If t he service
encount ers an error while invoking t he act ion sent by a cont rol point , t he service MUST send a response wit hin 30 seconds,
including expect ed t ransmission t ime. Out argument s MUST only be used t o ret urn dat a and MUST NOT be used t o convey error
informat ion. Error responses MUST be sent using t he following format . The following t wo examples illust rat e an error response
using t he CONTENT-LENGTH header and an error response using chuncked encoding. Values in it al ics are placeholders for act ual
values.

Not e: XML namespace prefixes do not have t o be t he specific examples shown below (e.g., s or u ); t hey can be any value
t hat obeys t he rules of t he general XML namespace mechanism; cont rol point s MUST error responses t hat use ot her legal XML
namespace prefixes.

79

Error response using the CONTENT-LENGTH header Valid using HTTP/1.0 and HTTP/1.1
HTTP/1.0 500 Internal Server Error
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated
SERVER: OS/version UPnP/1.1 product/version
CONTENT-LENGTH: bytes in body
<?xml version="1.0"?>
<s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<s:Body>
<s:Fault>
<faultcode>s:Client</faultcode>
<faultstring>UPnPError</faultstring>
<detail>
<UPnPError xmlns="urn:schemas-upnp-org:control-1-0">
<errorCode>error code</errorCode>
<errorDescription>error string</errorDescription>
</UPnPError>
</detail>
</s:Fault>
</s:Body>
</s:Envelope>

Error response using chunked encoding Valid using HTTP/1.1 only


HTTP/1.1 500 Internal Server Error
TRANSFER-ENCODING: "chunked"
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated
SERVER: OS/version UPnP/1.1 product/version
Length of first chunk in hexadecimal notation
<?xml version="1.0"?>
<s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<s:Body>
<s:Fault>
<faultcode>s:Client</faultcode>
<faultstring>UPnPError</faultstring>
<detail>
<UPnPError xmlns="urn:schemas-upnp-org:control-1-0">
<errorCode>error code</errorCode>
<errorDescription>error string</errorDescription>
</UPnPError>
</detail>
</s:Fault>
</s:Body>
Length of second chunk in hexadecimal notation
</s:Envelope>
0

List ed below are det ails for t he response line, header fields, and body element s appearing in t he list ing above. HTTP field names
are not case sensit ive. All HTTP field values and XML element names are case sensit ive; XML values are not case sensit ive except
where not ed. Except where not ed, REQUIRED element s MUST occur exact ly once (no duplicat es), and RECOMMENDED or
OPTIONAL element s MAY occur at most once.
Response line
HTTP/ 1.1
The highest version support ed by t he origin server t hat is compat ible wit h t he cont rol point t hat issued t he request .

80

For example, if t he cont rol point specified support for HTTP/ 1.0 in t he request , t he response MUST cont ain HTTP/ 1.0.
500 Int ernal Server Error
HTTP defined st at us code indicat ing t hat an error has been det ect ed.
Header fields
CONTENT-LANGUAGE
PROHIBITED. The CONTENT-LANGUAGE header field MUST NOT be used in cont rol messages.
CONTENT-LENGTH
REQUIRED if Origin Server does not close t he session aft er sending t he response AND Origin Server does not send t he
response using chunked encoding.
PROHIBITED if Origin Server sends t he response using chunked encoding. OPTIONAL ot herwise.
Field value specifies t he lengt h of t he body in byt es. Int eger.
TRANSFER-ENCODING
OPTIONAL for HTTP/ 1.1 and above. Field value specifies whet her t he response is chunked encoded by having field value
chunked (in t he example above t he body is sent in 2 chunks). MUST NOT be specified if CONTENT-LENGTH header field is
present .
CONTENT-TYPE
REQUIRED. Field value MUST be t ext / xml; charset ="ut f-8" .
DATE
RECOMMENDED. Field value cont ains dat e when response was generat ed. rfc1123-dat e as defined in RFC 2616.
SERVER
REQUIRED. Specified by UPnP vendor. St ring. Field value MUST begin wit h t he following product t okens (defined by
HTTP/ 1.1). The first product t oken ident ifes t he operat ing syst em in t he form OS name/ OS version, t he second t oken
represent s t he UPnP version and MUST be UPnP/ 1.1, and t he t hird t oken ident ifes t he product using t he form
product name/ product version. For example, SERVER: unix/ 5.1 UPnP/ 1.1 MyProduct / 1.0 . Cont rol point s MUST be
prepared t o accept a higher minor version number of t he UPnP version t han t he cont rol point it self implement s. For
example, cont rol point s implement ing UDA version 1.0 will be able t o int eroperat e wit h devices implement ing
UDA version 1.1.
Body
<Envelope>
REQUIRED element defined by SOAP. xmlns namespace at t ribut e MUST be "ht t p:/ / schemas.xmlsoap.org/ soap/ envelope/ ". MUST
include encodingStyle at t ribut e wit h value "ht t p:/ / schemas.xmlsoap.org/ soap/ encoding/ ". A receiver MUST generat e a fault
if it encount ers a message whose document element has a local name of "Envelope" but a namespace name t hat is not
"ht t p:/ / schemas.xmlsoap.org/ soap/ envelope/ ". Cont ains t he following sub element s:
<Body>
REQUIRED element defined by SOAP. MUST be qualified wit h SOAP namespace. Cont ains t he following sub
element :
<Fault>
REQUIRED element defined by SOAP. Error encount ered while invoking act ion. MUST be qualified wit h
SOAP namespace. Cont ains t he following sub element s:
<faultcode>
REQUIRED element defined by SOAP. Value MUST be qualified wit h t he SOAP namespace. MUST
be Client for DCP specific errors. When MANDATORY header XML element s wit hin t he SOAP
header cannot be processed it MUST be t he SOAP fault code Must Underst and .
<faultstring>
REQUIRED element defined by SOAP. MUST be UPnPError for DCP specific errors.
<detail>
REQUIRED element defined by SOAP. Cont ains t he following subelement :
<UPnPError>
REQUIRED element for DCP specific errors. MAY be empt y for ot her errors. Cont ains
t he following subelement s:
<errorCode>
REQUIRED element defined by UDA. Code ident ifying what error was
encount ered. See Table 3-3, UPnP Defined Act ion error codes for values.
Int eger.

81

<errorDescription>
RECOMMENDED element defined by UDA. Short descript ion. See Table 3-3,
UPnP Defined Act ion error codes for RECOMMENDED values; ot her values
MAY be used by vendors. Human-readable st ring. RECOMMENDED < 256
charact ers.
The following t able summarizes defined error t ypes and t he corresponding value for t he <errorCode> and
<errorDescription> element s.

Table 3-3:

UPnP Defined Action error codes

ErrorCode

errorDescription

Description

401

Invalid Act ion

No act ion by t hat name at t his service.

402

Invalid Args

Could be any of t he following: not enough in args, args in t he wrong order, one
or more in args are of t he wrong dat a t ype.

403

(Do Not Use)

(This code has been deprecat ed.)

501

Act ion Failed

MAY be ret urned if current st at e of service prevent s invoking t hat act ion.

600

Argument Value Invalid

The argument value is invalid

601

Argument Value Out of


Range

An argument value is less t han t he minimum or more t han t he maximum value


of t he allowed value range, or is not in t he allowed value list .

602

Opt ional Act ion Not


Implement ed

The request ed act ion is opt ional and is not implement ed by t he device.

603

Out of Memory

The device does not have sufficient memory available t o complet e t he act ion.
This MAY be a t emporary condit ion; t he cont rol point MAY choose t o ret ry t he
unmodified request again lat er and it MAY succeed if memory is available.

604

Human Int ervent ion


Required

The device has encount ered an error condit ion which it cannot resolve it self
and required human int ervent ion such as a reset or power cycle. See t he device
display or document at ion for furt her guidance.

St ring Argument Too Long

A st ring argument is t oo long for t he device t o handle properly.

Reserved

These ErrorCodes are reserved for UPnP DeviceSecurit y.

613-699

TBD

Common act ion errors. Defined by UPnP Forum Technical Commit t ee.

700-799

TBD

Act ion-specific errors defined by UPnP Forum working commit t ee.

800-899

TBD

Act ion-specific errors for non-st andard act ions. Defined by UPnP vendor.

605
606-612

3.2.6 UPnP Error Schema


The UPnP Error Schema defines t he st ruct ures and dat a t ypes used in t he body of UPnP error messages. As wit h t he UPnP Device
and Service Schemas, t he UPnP Error Schema is writ t en in XML synt ax and according t o t he convent ions of XML Schema (Part 1:
St ruct ures, Part 2: Dat at ypes). Appendix B.4, UPnP Error Schema cont ains a list ing of t his schema. The element s it defines are
used in error messages.

For fut ure ext ensibilit y and according t o t he requirement s in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8,
UPnP Device Schema , when processing XML like t he list ing above, devices and cont rol point s MUST ignore: (a) any unknown
element s and t heir sub element s or cont ent , and (b) any unknown at t ribut es and t heir values.

82

Subj ect t o t he const raint s defined in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8, UPnP Device Schema ,
cont rol point s and devices MUST ignore any XML comment s or XML processing inst ruct ions embedded in UPnP device and service
descript ions t hat t hey do not underst and.

XML namespace prefixes do not have t o be t he specific examples given above (e.g., s or u ); t hey can be any value t hat obeys
t he rules of t he general XML namespace mechanism; cont rol point s MUST accept responses t hat use ot her legal XML namespace
prefixes.

3.3 Query for variable


The QuerySt at eVariabl e act ion has been deprecat ed by t he UPnP Forum and MUST NOT be used by cont rol point s except in
l imit ed t est ing scenarios. Working commit t ees and vendors MUST explicit ly def ine act ions f or querying of st at e variables f or
which t his capabilit y is desired. Such explicit query act ions MAY include mult iple st at e variables, if desired. For t he f ull
def init ion of QuerySt at eVariable see t he UPnP 1.0 specif icat ion.

3.4 References
RFC 1123
Includes format for dat es, for, e.g., HTTP DATE header field. Available at : ht t p:/ / www/ iet f.org/ rfc/ rfc1123.t xt .
RFC 2616
HTTP: Hypert ext Transfer Prot ocol 1.1. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2616.t xt .
RFC 2774
HTTP Ext ension Framework. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2774.t xt .
RFC 3986
Uniform Resource Ident ifiers (URI): Generic Synt ax.Available at : ht t p:/ / www.iet f.org/ rfc/ rfc3986.t xt .
SOAP
Simple Obj ect Access Prot ocol. Available at : ht t p:/ / www.w3.org/ TR/ 2000/ NOTE-SOAP-20000508.
XML
Ext ensible Markup Language. Available at : ht t p:/ / www.w3.org/ XML.
XML Schema (Part 1: St ruct ures, Part 2: Dat at ypes)
Available at : ht t p:/ / www.w3.org/ TR/ xmlschema-1, ht t p:/ / www.w3.org/ TR/ xmlschema-2.

83

4 Eventing
[Normative]
Event ing is St ep 4 in UPnPnet working. Event ing comes af t er addressing (St ep 0) where devices get a net work address, af t er
discovery (St ep 1) where cont rol point s f ind int erest ing device(s), and af t er descript ion (St ep 2) where cont rol point s learn
about device capabilit ies. Event ing is int imat ely linked wit h cont rol (St ep 3) where cont rol point s send act ions t o devices.
Through event ing, cont rol point s list en t o st at e changes in device(s). Cont rol and event ing are complement ary t o present at ion
(St ep 5) where cont rol point s display a user int erf ace provided by device(s).

Aft er a cont rol point has (1) discovered a device and (2) ret rieved a descript ion of t he device and it s services, t he cont rol point
has t he essent ials for event ing. As sect ion 2, Descript ion explains, a UPnP service descript ion includes a list of act ions t he
service responds t o and a list of variables t hat model t he st at e of t he service at run t ime. If one or more of t hese st at e variables
are event ed, t hen t he service publishes updat es when t hese variables change, and a cont rol point MAY subscribe t o receive t his
informat ion. Two t ypes of event ing are support ed by t his specif icat ion: unicast event ing as found in version 1.0 of t he UPnP
specificat ion where a cont rol point MAY subscribe t o receive variable updat es; and mult icast event ing where variables MAY be
defined as mult icast event s and can be addit ionally sent over UDP t o any list ening device on t he mult icast event address. This
form of event ing is useful when event s which are not relevant t o a specific UPnP int eract ion SHOULD be delivered t o cont rol
point s t o inform users, and when mult iple cont rol l ed devices MAY want t o inform mult iple ot her cont rol l ed devices. Throughout
t his sect ion, publ isher refers t o t he source of t he event s (t ypically a device's service), subscriber refers t o t he dest inat ion of
event s (t ypically a cont rol point ), and t he t erm receiver refers t o t he list ener of mult icast event s (t ypically a cont rol point , but
MAY also be a cont rolled device).

84

4.1 Unicast eventing


Figure 4-1:

Unicast eventing architecture


control point 1
SID1

root device

subscribe
subscribeRsp:SID1

service

renewal:SID1
renewalRsp:SID1
cancel:SID1
event:SID1

device

control point 2
Previously subscribed
SID0

0
S ID
n t:

e
ev

service

To subscribe t o event ing, a subscriber sends a subscript ion message. If t he subscript ion is accept ed, t he publisher responds wit h
a durat ion for t he subscript ion. To keep t he subscript ion act ive, a subscriber MUST renew it s subscript ion before t he subscript ion
expires. When a subscriber no longer needs event ing from a publisher, t he subscriber SHOULD cancel it s subscript ion. This
sect ion explains subscript ion, renewal, and cancellat ion messages in det ail below.

The publisher not es changes t o st at e variables by sending event messages. Event messages cont ain t he names of one of more
st at e variables and t he current value of t hose variables, expressed in XML. A special init ial event message is sent when a
subscriber first subscribes; t his event message cont ains t he names and values for all event ed variables and allows t he subscriber
t o init ialize it s model of t he st at e of t he service. To support scenarios wit h mult iple cont rol point s, event ing can be used t o keep
int erest ed cont rol point s informed about t he effect s of act ions performed by ot her cont rol point s or using ot her mechanisms for
device cont rol (such as front panel cont rols). All subscribers are sent all event messages, subscribers receive event messages for
all event ed variables (not j ust some), and event messages are sent no mat t er why t he st at e variable changed (eit her in response
t o a request ed act ion or because t he st at e t he service is modeling changed). This sect ion explains t he format of event messages
in det ail below.

Some st at e variables MAY change value t oo rapidly for event ing t o be useful. One alt ernat ive is t o filt er, or moderat e, t he
number of event messages sent due t o changes in a variable's value. Some st at e variables may cont ain values t oo large for
event ing t o be useful; for t his, or ot her reasons, a service MAY designat e one or more st at e variables as non event ed and never
send event messages t o subscribers. To det ermine t he current value for such non-event ed variables, cont rol point s MUST poll t he

85

service explicit ly, presuming t hat an act ion is provided t o obt ain t he value of t he st at e variable. This sect ion explains how
variable event ing is described wit hin a service descript ion.

To send and receive subscript ion and event messages, cont rol point s and services use t he following subset of t he overall UPnP
prot ocol st ack. (The overall UPnP prot ocol st ack is list ed at t he beginning of t his document .)

Figure 4-2:

Unicast eventing protocol stack


UPnP vendor [purple-it alic]
UPnP Forum [red-it alic]
UPnP Device Architecture [green-bold]
GENA [navy-bold]
HTTP [black]
TCP [black]
IP [black]

At t he highest layer, subscript ion and event messages cont ain vendor-specific informat ion like URLs for subscript ion and durat ion
of subscript ions or specific variable values. Moving down t he st ack, vendor cont ent is supplement ed by informat ion from a UPnP
Forum working commit t ee, like service ident ifiers or variable names. Messages from t he layers above are host ed in UPnP-specific
prot ocols, defined in t his document . In t urn, t he above messages are delivered via HTTP t hat has been ext ended using addit ional
met hods and header fields. The HTTP messages are delivered via TCP over IP. For reference, colors in [square bracket s] above
indicat e which prot ocol defines specific header fields in t he subscript ion messages list ed below.

The remainder of t his sect ion first explains subscript ion, including det ails of subscript ion messages, renewal messages, and
cancellat ion messages. Second, it explains in det ail how event messages are format t ed and sent t o cont rol point s, and t he init ial
event message. Finally, it explains t he UPnP Device and Service Schemas as t hey pert ain t o event ing.

The generic requirement s on HTTP usage in UPnP 1.1 (as defined in sect ion 2.1, Generic requirement s on HTTP usage of t his
document ) MUST be followed by devices and cont rol point s t hat implement event ing.

Services t hat use event ed complex dat at ypes MUST follow t he requirement s in sect ion 2.5, Service descript ion .

4.1.1 Subscription
A service has event ing if and only if one or more of t he st at e variables are event ed.

If a service has event ing, it publishes event messages t o int erest ed subscribers. The publisher maint ains a list of subscribers,
keeping for each subscriber t he following informat ion.
unique subscript ion ident ifier
REQUIRED. MUST be unique over t he lifet ime of t he subscript ion, however long or short t hat may be. Generat ed by publisher
in response t o subscript ion message. RECOMMEND universally-unique ident ifiers t o ensure uniqueness. Single URI.

86

delivery URL for event messages


REQUIRED. Provided by subscriber in subscript ion message. Single URL.
event key
REQUIRED. Key is 0 for init ial event message. Key MUST be sequent ially numbered for each subsequent event message;
subscribers can verify t hat no event messages have been lost if t he subscriber has received sequent ially numbered event
keys. MUST wrap from 4294967295 t o 1 (32-bit unsigned decimal int eger). Some implement at ions MAY include leading 0
charact ers in t he event key, which MUST be ignored.
subscript ion durat ion
REQUIRED. Amount of t ime, or durat ion unt il subscript ion expires. Single int eger, preceded in subscript ion messages by t he
keyword Second- (no spaces). UPnP 1.0 defines t he use of t he keyword infinite inst ead of an int eger. This keyword is
deprecat ed in UPnP 1.1 (it leads t o problems if cont rol point s disappear wit hout unsubscribing and is hardly used): UPnP 1.1
cont rol point s MUST NOT subscribe using keyword infinite, UPnP 1.1 devices MUST NOT set act ual subscript ion durat ions t o
infinit e . The presence of infinite in a request MUST be silent ly ignored by a UPnP 1.1 device (t he presence of infinit e is
handled by t he device as if t he TIMEOUT header field in a request was not present ) . The keyword infinit e MUST NOT be
ret urned by a UPnP 1.1 device.
HTTP version support ed by t he subscriber
REQUIRED if t he publisher support s chunked encoding of event not ificat ion messages, so t hat chunked messages are not sent
t o subscribers t hat do not support t hem.
A mult i-homed publisher MUST also maint ain informat ion on t he UPnP-enabled int erface on which each subscript ion message was
received. The same int erface MUST be used when publishing event messages t o t he corresponding subscriber.

The publisher SHOULD accept as many subscript ions as it can reasonably maint ain, t aking int o account t hat t he number of event
messages t hat need t o be delivered per event , which increases linearly wit h t he number of subscript ions.

The list of subscribers is updat ed via subscript ion, renewal, and cancellat ion messages explained immediat ely below and event
messages explained lat er in t his sect ion.

To subscribe t o event ing for a service, a subscriber sends a subscript ion message cont aining a URL for t he publisher, a service
ident ifier for t he publisher, and a delivery URL for event messages. The subscript ion message MAY also include a request ed
durat ion for t he subscript ion. The URL and service ident ifier for t he publisher come from a descript ion message. As sect ion 2,
Descript ion explains, a descript ion message cont ains a device descript ion. A device descript ion cont ains (among ot her t hings),
for each service, an event ing URL (obt ained from t he event SubURL element ) and a service ident ifier (in t he serviceId element );
t hese correspond t o t he URL and service ident ifier for t he publisher, respect ively. If event SubURL is an absolut e URL, t he fully
qualified event subscript ion URL is t he event SubURL. If event SubURL is a relat ive URL, t he fully qualified event subscript ion URL
is t he URL resolved from event SubURL in accordance wit h sect ion 5 of RFC 3986, using eit her t he URLBase element , if specified,
or t he URL from which t he device descript ion was ret rieved as t he base URL. If t he event SubURL is empt y, no subscript ions are
possible. The fully qualified event subscript ion URL for t he publisher MUST be unique t o a part icular service wit hin t his device. A
mult i-homed cont rol point t hat sends t he subscript ion message on a part icular UPnP-enabled int erface MUST use t he fully
qualified event ing URL from t he descript ion document received on t hat UPnP-enabled int erface. The delivery URL cont ained in
t he subscript ion message MUST be reachable on t hat int erface.

The subscript ion message is a request t o receive all event messages. No mechanism is provided t o subscribe t o event messages on
a variable-by-variable basis. A subscriber is sent all event messages from t he service. This is one fact or t o be considered when
designing a service.

87

If t he subscript ion is accept ed, t he publisher responds wit h a unique ident ifier for t his subscript ion and a durat ion for t his
subscript ion. A durat ion SHOULD be chosen t hat mat ches assumpt ions about how frequent ly cont rol point s are removed from t he
net work; if cont rol point s are removed every few minut es, t hen t he durat ion SHOULD be similarly short , allowing a publisher t o
rapidly deprecat e any expired subscribers; if cont rol point s are expect ed t o be semi-permanent , t hen t he durat ion SHOULD be
very long, minimizing t he processing and t raffic associat ed wit h renewing subscript ions.

As soon as possible aft er t he subscript ion is accept ed, t he publisher also sends t he first , or init ial event message t o t he
subscriber. This message includes t he names and current values for all event ed variables. (The dat a t ype and range for each
variable is described in a service descript ion. Sect ion 2, Descript ion explains t his in more det ail.) This init ial event message is
always sent , even if t he cont rol point unsubscribes before it is delivered. The device MUST insure t hat t he cont rol point has
received t he response t o t he subscript ion request before sending t he init ial event message, t o insure t hat t he cont rol point has
received t he SID (subscript ion ID) and can t hereby correlat e t he event message t o t he subscript ion.

To keep t he subscript ion act ive, a subscriber MUST renew it s subscript ion before t he subscript ion expires by sending a renewal
message. The renewal message is sent t o t he same URL as t he subscript ion message, but t he renewal message does not include a
delivery URL for event messages; inst ead t he renewal message includes t he subscript ion ident ifier. The response for a renewal
message is t he same as one for a subscript ion message.

If a subscript ion expires, t he subscript ion ident ifier becomes invalid, and t he publisher st ops sending event messages t o t he
subscriber and can clean up it s list of subscribers. If t he subscriber t ries t o send any message ot her t han a subscript ion message,
t he publisher MUST rej ect t he message because t he subscript ion ident ifier is invalid.

When a subscriber no longer needs event ing from a part icular service, t he subscriber SHOULD cancel it s subscript ion. Canceling a
subscript ion generally reduces service, cont rol point , and net work load. If a subscriber is removed abrupt ly from t he net work, it
might be impossible t o send a cancellat ion message. As a fallback, t he subscript ion will event ually expire on it s own unless
renewed.

It is st rongly RECOMMENDED t hat subscribers monit or discovery messages from t he publisher. If t he publisher cancels it s
advert isement s or if t he value of t he BOOTID.UPNP.ORG is increased wit hout a prior ssdp:update message wit h a mat ching
NEXTBOOTID.UPNP.ORG field value, subscribers MUST assume t hat t heir subscript ions have been cancelled.

Below is an explanat ion of t he specific format of request s, responses, and errors for subscript ion, renewal, and cancellat ion
messages.

4.1.2 SUBSCRIBE with NT and CALLBACK


For each service in a device, a descript ion message cont ains an event subscript ion URL (obt ained from t he event SubURL sub
element of service element in t he device descript ion) and t he UPnP service ident ifier (serviceId sub element in service element
in device descript ion). To subscribe t o event ing for a part icular service, a subscript ion message is sent t o t hat service's fully

88

qualified event subscript ion URL. If event SubURL is an absolut e URL, t he fully qualified event subscript ion URL is t he
event SubURL. Ot herwise, if event SubURL is a relat ive URL, t he fully qualified event subscript ion URL is t he URL resolved from
event SubURL in accordance wit h sect ion 5 of RFC 3986, using eit her t he URLBase element , if specified, or t he URL from which
t he device descript ion was ret rieved as t he base URL. The message cont ains t hat service's ident ifier as well as a delivery URL for
event messages. A mult i-homed cont rol point t hat sends t he subscript ion message on a part icular UPnP-enabled int erface MUST
use t he fully qualified event ing URL from t he descript ion document received on t hat int erface. The delivery URL cont ained in t he
subscript ion message MUST be reachable on t hat int erface. A subscript ion message MAY also include a request ed subscript ion
durat ion.

To subscribe t o event ing for a service, a subscriber MUST send a request wit h met hod SUBSCRIBE and NT and CALLBACK header
fields in t he following format . Values in it alics are placeholders for act ual values.

SUBSCRIBE publisher path HTTP/1.1


HOST: publisher host:publisher port
USER-AGENT: OS/version UPnP/1.1 product/version
CALLBACK: <delivery URL>
NT: upnp:event
TIMEOUT: Second-requested subscription duration

(No body for request wit h met hod SUBSCRIBE, but not e t hat t he message MUST have a blank line following t he last HTTP header
field.)

List ed below are det ails for t he request line and header fields appearing in t he list ing above. Field names are not case sensit ive.
All field values are case sensit ive except where not ed.
Request line
SUBSCRIBE
Met hod t o init iat e or renew a subscript ion.
publisher pat h
Pat h component of t he fully qualified event subscript ion URL. Single, absolut e pat h (see also RFC 2616, sect ion 3.2.2).
HTTP/ 1.1
The version support ed by t he cont rol point . (Not e: t he cont rol point MUST implement all MANDATORY component s of t he
version specified). MAY be any HTTP version t hat is backwards compat ible t o HTTP/ 1.0 (like HTTP/ 1.1).
Header fields
HOST
REQUIRED. Field value cont ains domain name or IP address and opt ional port component s of t he fully qualified event
subscript ion URL. If t he port is missing or empt y, port 80 is assumed.
USER-AGENT
OPTIONAL. Specified by UPnP vendor. St ring. Field value MUST begin wit h t he following product t okens (defined by
HTTP/ 1.1). The first product t oken ident ifes t he operat ing syst em in t he form OS name/ OS version, t he second t oken
represent s t he UPnP version and MUST be UPnP/ 1.1, and t he t hird t oken ident ifes t he product using t he form
product name/ product version. For example, USER-AGENT: unix/ 5.1 UPnP/ 1.1 MyProduct / 1.0 . Cont rol point s MUST be
prepared t o accept a higher minor version number of t he UPnP version t han t he cont rol point it self implement s. For
example, cont rol point s implement ing UDA version 1.0 will be able t o int eroperat e wit h devices implement ing
UDA version 1.1. See sect ion 2.5, Service descript ion .
CALLBACK
REQUIRED. Field value cont ains locat ion t o send event messages t o. Defined by UPnP vendor. If t here is more t han one URL,
when t he service sends event s, it will t ry t hese URLs in order unt il one succeeds. One or more URLs each enclosed by angle

89

bracket s ( < and > ). Each URL MUST be an HTTP over TCP URL (prefixed by ht t p:/ / ). The device MUST NOT t runcat e
t his URL in any way; if insufficient memory is available t o st ore t he ent ire CALLBACK URL, t he device MUST rej ect t he
subscript ion. At least one of t he delivery URLs MUST be reachable by t he device.
NT
REQUIRED. Field value cont ains Not ificat ion Type. MUST be upnp:event.
SID
(No SID header field is used t o subscribe.)
TIMEOUT
RECOMMENDED. Field value cont ains request ed durat ion unt il subscript ion expires. Consist s of t he keyword Secondfollowed (wit hout an int ervening space) by an int eger. UPnP 1.0 defined t hat t he int eger can be replaced by t he keyword
infinite. This has been deprecat ed in UPnP 1.1: UPnP 1. 1 cont rol point s MUST NOT subscribe using keyword infinite.
If t here are enough resources t o maint ain t he subscript ion, t he publisher SHOULD accept it . To accept t he subscript ion, t he
publisher assigns a unique ident ifier for t he subscript ion, assigns a durat ion for t he subscript ion, and sends an init ial event
message (explained in det ail lat er in t his sect ion). To accept a subscript ion request , a publisher MUST send a response in t he
following format wit hin 30 seconds, including expect ed t ransmission t ime. A mult i-homed publisher MUST send t he response on
t he same UPnP-enabled int erface on which t he subscript ion message was received. Values in it alics are placeholders for act ual
values.

HTTP/1.1 200 OK
DATE: when response was generated
SERVER: OS/version UPnP/1.1 product/version
SID: uuid:subscription-UUID
CONTENT-LENGTH: 0
TIMEOUT: Second-actual subscription duration

(No body for response t o a request wit h met hod SUBSCRIBE, but not e t hat t he message MUST have a blank line following t he last
HTTP header field.)

If t he device sends t he response over HTTP/ 1.0 wit hout set t ing t he KeepAlive t oken, or over HTTP/ 1.1 wit h t he
CONNECTION: close header field, t he device MUST insure t hat t he TCP FIN flag is sent BEFORE sending t he init ial event message.
In all ot her cases, (unless t he response is chunked), a CONTENT-LENGTH MUST be specified, (and set t o 0), prior t o sending t he
init ial event .

List ed below are det ails for header fields appearing in t he list ing above. Field names are not case sensit ive. All field values are
case sensit ive except where not ed.
Response line
HTTP/ 1.1
The highest version support ed by t he origin server t hat is compat ible wit h t he cont rol point t hat issued t he request .
For example, if t he cont rol point specified support for HTTP/ 1.0 in t he request , t he response MUST cont ain HTTP/ 1.0.
200 OK
HTTP defined st at us code indicat ing t hat no HTTP errors were det ect ed..
Header fields
DATE
RECOMMENDED. Field value cont ains dat e when t he response was generat ed. rfc1123-dat e as defined in RFC 2616.

90

SERVER
REQUIRED. Specified by UPnP vendor. St ring. Field value MUST begin wit h t he following product t okens (defined by
HTTP/ 1.1). The first product t oken ident ifes t he operat ing syst em in t he form OS name/ OS version, t he second t oken
represent s t he UPnP version and MUST be UPnP/ 1.1, and t he t hird t oken ident ifes t he product using t he form
product name/ product version. For example, SERVER: unix/ 5.1 UPnP/ 1.1 MyProduct / 1.0 . Cont rol point s MUST be
prepared t o accept a higher minor version number of t he UPnP version t han t he cont rol point it self implement s. For
example, cont rol point s implement ing UDA version 1.0 will be able t o int eroperat e wit h devices implement ing
UDA version 1.1.
SID
REQUIRED. Field value cont ains Subscript ion Ident ifier. MUST be universally unique. MUST begin wit h uuid:. Defined by UPnP
vendor. See sect ion 1.1.4, UUID format and RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format .
TIMEOUT
REQUIRED. Field value cont ains act ual durat ion unt il subscript ion expires. Keyword Second- followed by an int eger (no
space). SHOULD be great er t han or equal t o 1800 seconds (30 minut es).
CONTENT-LENGTH
REQUIRED if TCP FIN flag cannot be guarant eed t o be sent before t he init ial event is sent . MUST have field value 0 .
If a publisher cannot accept t he subscript ion, or if t here is an error wit h t he subscript ion request , t he publisher MUST send a
response wit h one of t he following errors. The response MUST be sent wit hin 30 seconds, including expect ed t ransmission t ime.

Table 4-4:

HTTP Status Codes indicating a Subscription Error

ErrorCode

errorDescription

Description

400

Incompat ible header


fields

An SID header field and one of NT or CALLBACK header fields are present .

412

Precondit ion Failed

CALLBACK header field is missing or does not cont ain a valid HTTP URL;
or t he NT header field does not equal upnp:event.

5xx

Unable t o accept renewal

If t he publisher is unable t o accept a renewal, it MUST respond wit h an


appropriat e 500-series HTTP st at us code.

Ot her errors, including ot her HTTP st at us codes, MAY be ret urned by layers in t he prot ocol st ack below t he UPnP prot ocols.
Consult document at ion on t hose prot ocols for det ails.

4.1.3 Renewing a subscription with SUBSCRIBE with SID


To renew a subscript ion t o event ing for a part icular service, a renewal message is sent t o t hat service's fully qualified event
subscript ion URL (See sect ion 4.1.2, SUBSCRIBE wit h NT and CALLBACK ). However, unlike an init ial subscript ion message, a
renewal message does not cont ain eit her t he service's ident ifier nor a delivery URL for event messages. Inst ead, t he message
cont ains t he subscript ion ident ifier assigned by t he publisher, providing an unambiguous reference t o t he subscript ion t o be
renewed. Like a subscript ion message, a renewal message MAY also include a request ed subscript ion durat ion. A mult i-homed
cont rol point MUST send t he renewal message using t he same pair of UPnP-enabled int erfaces used for t he init ial subscript ion.

The renewal message uses t he same met hod as t he subscript ion message, but t he t wo messages use a disj oint set of header
fields; renewal uses SID and subscript ion uses NT and CALLBACK. A message t hat includes SID and eit her of NT or CALLBACK
header fields is an error.

To renew a subscript ion t o event ing for a service, a subscriber MUST send a request wit h met hod SUBSCRIBE and SID header field
in t he following format . Values in it alics are placeholders for act ual values.

91

SUBSCRIBE publisher path HTTP/1.1


HOST: publisher host:publisher port
SID: uuid:subscription UUID
TIMEOUT: Second-requested subscription duration

(No body for met hod wit h request SUBSCRIBE, but not e t hat t he message MUST have a blank line following t he last HTTP header
field.)

List ed below are det ails for t he request line and header fields appearing in t he list ing above. Field names are not case sensit ive.
All field values are case sensit ive except where not ed.
Request line
SUBSCRIBE
Met hod t o init iat e or renew a subscript ion.
publisher pat h
Pat h component of t he fully qualified event subscript ion URL. Single, absolut e pat h (see also RFC 2616, sect ion 3.2.2).
HTTP/ 1.1
The version support ed by t he cont rol point . (Not e: t he cont rol point MUST implement all MANDATORY component s of t he
version specified). MAY be any HTTP version t hat is backwards compat ible t o HTTP/ 1.0 (like HTTP/ 1.1)
Header fields
HOST
REQUIRED. Field value cont ains domain name or IP address and opt ional port component s of fully qualified event
subscript ion URL. If t he port is missing or empt y, port 80 is assumed.
CALLBACK
(No CALLBACK header field is used t o renew an event subscript ion.)
NT
(No NT header field is used t o renew an event subscript ion.)
SID
REQUIRED. Field value cont ains Subscript ion Ident ifier. MUST be t he subscript ion ident ifier assigned by publisher in response
t o subscript ion request . MUST be universally unique. MUST begin wit h uuid:. Defined by UPnP vendor. See sect ion 1.1.4,
UUID format and RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format .
TIMEOUT
RECOMMENDED. Field value cont ains request ed durat ion unt il subscript ion expires. Keyword Second- followed by an int eger
(no space). UPnP 1.0 defined t hat t he int eger can be replaced by t he keyword infinite. This has been deprecat ed in UPnP
1.1: UPnP 1.1 cont rol point s MUST NOT subscribe using keyword infinite. See reference above.
To accept a renewal, t he publisher reassigns a durat ion for t he subscript ion and MUST send a response in t he same format and
wit h t he same condit ions as a response t o a request for a new subscript ion, except t hat t he init ial event message is not sent
again.

If a publisher cannot accept t he renewal, or if t here is an error wit h t he renewal request , t he publisher MUST send a response
wit h one of t he following errors. The response MUST be sent wit hin 30 seconds, including expect ed t ransmission t ime.

92

Table 4-5:

HTTP Status Codes indicating a Resubscription Error

ErrorCode

errorDescription

Description

400

Incompat ible header


fields

An SID header field and one of NT or CALLBACK header fields are present .

412

Precondit ion Failed

An SID does not correspond t o a known, un-expired subscript ion;


or t he SID header field is missing or empt y.

5xx

Unable t o accept renewal

If t he publisher is unable t o accept a renewal, it MUST respond wit h an


appropriat e 500-series HTTP st at us code.

Ot her errors, including ot her HTTP st at us codes, MAY be ret urned by layers in t he prot ocol st ack below t he UPnP prot ocols.
Consult document at ion on t hose prot ocols for det ails.

4.1.4 Canceling a subscription with UNSUBSCRIBE


When event ing is no longer needed from a part icular service, a cancellat ion message SHOULD be sent t o t hat service's fully
qualified event subscript ion URL (see sect ion 4.1.2, SUBSCRIBE wit h NT and CALLBACK ). The message cont ains t he subscript ion
ident ifier. A mult i-homed cont rol point MUST send t he cancellat ion message using t he same pair of UPnP-enabled int erfaces used
for t he init ial subscript ion. Canceling a subscript ion generally reduces service, cont rol point , and net work load. If a cont rol point
is removed abrupt ly from t he net work, it might be impossible t o send a cancellat ion message. As a fallback, t he subscript ion will
event ually expire on it s own unless renewed.

To explicit ly cancel a subscript ion t o event ing for a service, a subscriber MUST send a request wit h met hod UNSUBSCRIBE in t he
following format . Values in it alics are placeholders for act ual values.

UNSUBSCRIBE publisher path HTTP/1.1


HOST: publisher host:publisher port
SID: uuid:subscription UUID

(No body for request wit h met hod UNSUBSCRIBE, but not e t hat t he message MUST have a blank line following t he last HTTP
header field.)

List ed below are det ails for t he request line and header fields appearing in t he list ing above. Field names are not case sensit ive.
All field values are case sensit ive except where not ed.
Request line
UNSUBSCRIBE
Met hod t o cancel a subscript ion.
publisher pat h
Pat h component of t he fully qualified event subscript ion URL. Single, absolut e pat h (see also RFC 2616, sect ion 3.2.2).
HTTP/ 1.1
The version support ed by t he cont rol point . (Not e: t he cont rol point MUST implement all MANDATORY component s of t he
version specified). MAY be any HTTP version t hat is backwards compat ible t o HTTP/ 1.0 (like HTTP/ 1.1)

93

Header fields
HOST
REQUIRED. Field value cont ains domain name or IP address and opt ional port component s of fully qualified event
subscript ion URL. If t he port is missing or empt y, port 80 is assumed.
CALLBACK
(No CALLBACK header field is used t o cancel an event subscript ion.)
NT
(No NT header field is used t o cancel an event subscript ion.)
SID
REQUIRED. Field value cont ains Subscript ion Ident ifier. MUST be t he subscript ion ident ifier assigned by publisher in response
t o subscript ion request . Must be universally unique. Must begin wit h uuid:. Defined by UPnP vendor. See sect ion 1.1.4,
UUID format and RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format .
TIMEOUT
(No TIMEOUT header field is used t o cancel an event subscript ion.)
To cancel a subscript ion, a publisher MUST send a response in t he following format wit hin 30 seconds, including expect ed
t ransmission t ime.

HTTP/1.1 200 OK

Response line
HTTP/ 1.1
The highest version support ed by t he origin server t hat is compat ible wit h t he cont rol point t hat issued t he request .
For example, if t he cont rol point specified support for HTTP/ 1.0 in t he request , t he response MUST cont ain HTTP/ 1.0.
200 OK
HTTP defined st at us code indicat ing t hat no HTTP errors were det ect ed.
If t here is an error wit h t he cancellat ion request , t he publisher MUST send a response wit h one of t he following errors. The
response MUST be sent wit hin 30 seconds, including expect ed t ransmission t ime.

Table 4-6:

HTTP Status Codes indicating a Cancel Subscription Error

ErrorCode

errorDescription

Description

400

Incompat ible header


fields

An SID header field and one of NT or CALLBACK header fields are present .

412

Precondit ion Failed

An SID does not correspond t o a known, un-expired subscript ion;


or t he SID header field is missing or empt y.

Ot her errors, including ot her HTTP st at us codes, MAY be ret urned by layers in t he prot ocol st ack below t he UPnP prot ocols.
Consult document at ion on t hose prot ocols for det ails.

94

4.2 Multicast Eventing


Figure 4-3:

Multicast eventing architecture


multicast

control point 4
control point 3
control point 2

root device 0

Multicast event
multicast
Multicast event

event

control point 1

service
Multicast event

Multicast event
device

service
root device 4

Multicast event

root device 3
root device 2
root device 1

Multicast event

Multicast event

Multicast event

The publisher MAY not e changes t o st at e variables by sending mul t icast event messages. Mult icast event messages cont ain t he
names of one or more st at e variables and t he current value of t hose variables, expressed in XML. To send and receive mult icast
event messages, cont rol point s and services use t he following subset of t he overall UPnP prot ocol st ack. (The overall UPnP
prot ocol st ack is list ed at t he beginning of t his document .)

Figure 4-4:

Mulitcast eventing protocol stack


UPnP vendor [purple-it alic]
UPnP Forum [red-it alic]
UPnP Device Architecture [green-bold]
Multicast Eventing [navy-bold]
UDP [black]
IP [black]

95

At t he highest layer, mult icast event messages cont ain vendor-specific informat ion like vendor-specific st at e variable or specific
variable values. Moving down t he st ack, vendor cont ent is supplement ed by informat ion from a UPnP Forum working commit t ee,
such as service ident ifiers or variable names. Messages from t he layers above are host ed in UPnP-specific prot ocols t o t ransport
event s in a similar format t o unicast UPnP event s, but over a mult icast address where subscript ionless event ing fit s t he desired
usage. These messages are based on t he HTTP prot ocol header and body format , but are not HTTP compliant because t hey are
defined over UDP socket s. Throughout t his sect ion, t he same format t ing and ext ension rules for SSDP as set fort h in sect ion 1.1.2,
SSDP message header fields and sect ion 1.1.3, SSDP header field ext ensions are used t o give HTTP-like header field
format t ing. In addit ion, services t hat use event ed complex dat at ypes MUST follow t he requirement s in sect ion 2.5, Service
descript ion . Last ly, like SSDP, t o limit net work congest ion, t he t ime-t o-live (TTL) of each IP packet for each mult icast message
SHOULD default t o 2 and SHOULD be configurable. This SHOULD be t he same value as t hat used in SSDP. When t he TTL is great er
t han 1, it is possible for mult icast messages t o t raverse mult iple rout ers; t herefore cont rol point s and devices using non-Aut oIP
addresses MUST send an IGMP Join message so t hat rout ers will forward mult icast messages t o t hem (t his is not necessary when
using an Aut o-IP address since packet s wit h Aut o-IP addresses will not be forwarded by rout ers).

Mult icast event ing is inherent ly unreliable since it is based on UDP. In addit ion, t here will be a great er possibilit y of message loss
wit h great er packet size. To increase t he probabilit y of successf ul t ransmission, each message MAY be ret ransmit t ed one or more
t imes. Therefore, UPnP working commit t ees MUST specify t he event size and event ret ransmission rules, based on t heir need for
reliabilit y.

4.3 Event messages


A service publishes changes t o cert ain st at e variables by sending event messages. These messages cont ain t he names of one or
more st at e variables and t he current value of t hose variables. Event messages MUST be sent in a t imely manner so t hat
subscribers are accurat ely informed about t he st at e of t he service and can provide a responsive user int erface. If t he value of
more t han one variable is changing at t he same t ime, t he publisher SHOULD bundle t hese changes int o a single event message t o
reduce processing and net work t raffic.

As explained above, an init ial event message is sent when a subscriber first subscribes; t his event message cont ains t he names
and values for all event ed variables and allows t he subscriber t o init ialize it s model of t he st at e of t he service. This message
SHOULD be sent as soon as possible aft er t he publisher accept s a subscript ion. This message MUST be sent , even if t he cont rol
point unsubscribes before t he message is delivered. Subscript ion does not cause mult icast event messages.

Mult icast event messages are const rained t o being t ransport ed in a single UDP payload. This considerat ion is import ant when
ident ifying variables t hat are t o be mult icast . If t he cumulat ive size of t he variables t hat are eligible for being sent by mult icast
exceeds t he UDP packet s capacit y, it may be necessary t o send mult iple, dist inct mult icast event s.

Bot h unicast and mult icast event messages are t agged wit h an event key. In unicast event ing, a separat e event key MUST be
maint ained by t he publisher for each subscript ion t o facilit at e error det ect ion (as explained below). The event key for a

96

subscript ion is init ialized t o 0 when t he publisher sends t he init ial event message. For each subsequent event message, t he
publisher increment s (by one) t he event key for a subscript ion, and includes t hat updat ed key in t he event message. The event
key for mult icast event s is also init ialized t o 0 when t he publisher sends t he init ial event message. For each subsequent mult icast
event message, t he publisher increment s (by one) t he event key for t he mult icast event s, and includes t hat updat ed key in t he
event message. Any implement at ion of event keys MUST handle overflow and wrap t he event key from 4294967295 back t o 1 (not
0). Unicast subscribers and mult icast receivers MUST also handle t his special case when t he next event key is not an increment of
t he previous key. The key MUST be implement ed as a 4 Byt e (32 bit ) unsigned int eger.

All UPnP event messages MUST be encoded using UTF-8.

4.3.1 Error Cases


For unicast event ing, t he publisher MUST send all event messages t o t he subscriber unt il t he subscript ion expires even when t he
subscriber fails t o respond. When a subscriber has missed one or more event messages, t he subscriber MAY synchronize wit h t he
device s event ed st at e by unsubscribing and re-subscribing. By doing so, t he subscriber will get a new subscript ion ident ifier, a
new init ial event message, and a new event key.

For mult icast event ing, since UDP is inherent ly unreliable, ret ransmission of a mult icast event message (using t he same SEQ field
value) can increase t he reliabilit y. The receiver MUST int erpret t he same SEQ field value from separat e mult icast event messages
from a same service (ident ified by USN field value) as being t he exact ly t he same message sent mult iple t imes and MUST
t herefore ignore such duplicat es. Some st at e variables may change value t oo rapidly for some environment s, for example
ent erprises. Working commit t ees MUST specify t raffic const raint s for t he DCP given t hese concerns and guidelines. Working
commit t ees SHOULD consider bot h t he int erval for t ransmission of mult icast event s per event t ype (LVL:) and t he ret ransmission
rules for part icular event inst ances.

4.3.2 Unicast eventing: Event messages: NOTIFY


To send an event message, a publisher MUST send a request wit h met hod NOTIFY using t he following format . The following t wo
examples illust rat e an event message using t he CONTENT-LENGTH header and an event message using chunked encoding. Values
in it alics are placeholders for act ual values.

Event messages sent t o different subscribers t hat have t he same sequence number MUST cont ain t he same cont ent except for t he
HOST header field. A mult i-homed device MUST send t he event message using t he same pair of UPnP-enabled int erfaces used for
t he init ial subscript ion.

Not e: XML namespace prefixes do not have t o be t he specific examples shown below (e.g., s or u ); t hey can be any value
t hat obeys t he rules of t he general XML namespace mechanism; cont rol point s MUST accept event messages t hat use ot her legal
XML namespace prefixes.

97

Event message using the CONTENT-LENGTH header Valid with HTTP/1.0 or HTTP/1.1
NOTIFY delivery path HTTP/1.0
HOST: delivery host:delivery port
CONTENT-TYPE: text/xml; charset="utf-8"
NT: upnp:event
NTS: upnp:propchange
SID: uuid:subscription-UUID
SEQ: event key
CONTENT-LENGTH: bytes in body
<?xml version="1.0"?>
<e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">
<e:property>
<variableName>new value</variableName>
</e:property>
Other variable names and values (if any) go here.
</e:propertyset>

Event message using chunked encoding Valid with HTTP 1.1 only
NOTIFY delivery path HTTP/1.1
HOST: delivery host:delivery port
CONTENT-TYPE: text/xml; charset="utf-8"
NT: upnp:event
NTS: upnp:propchange
SID: uuid:subscription-UUID
TRANSFER-ENCODING: "chunked"
SEQ: event key
Length of chunk 1 in hexadecimal notation
<?xml version="1.0"?>
<e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">
<e:property>
<variableName>new value</variableName>
</e:property>
Other variable names and values (if any) go here.
</e:propertyset>
0

List ed below are det ails for t he request line, header fields, and body element s appearing in t he list ing above. Field names are
not case sensit ive. All field values are case sensit ive except where not ed. All body element s and at t ribut es are case sensit ive;
body values are not case sensit ive except where not ed. Except where not ed, REQUIRED element s MUST occur exact ly once (no
duplicat es), and RECOMMENDED or OPTIONAL element s MAY occur at most once. In part icular, a single propertyset element
MUST NOT include more t han one property element t hat specifies t he same variableName element ; separat e event not ificat ion
messages MUST be used.
Request line
NOTIFY
Met hod t o not ify client about event .
delivery pat h
Pat h component of delivery URL (CALLBACK header field in subscript ion message). Dest inat ion for event message. Single,
absolut e pat h (see also RFC 2616). MUST be from one of t he URLs cont ained in t he CALLBACK header field, wit hout
t runcat ion or modificat ion.
HTTP/ 1.1
Highest HTTP version support ed by t he device. (Not e: chunked encoding MUST NOT be used if t he cont rol point support s
only HTTP 1.0).

98

Header fields
HOST
REQUIRED. Field value cont ains domain name or IP address and opt ional port component s of delivery URL (CALLBACK header
field in subscript ion message). If t he port is missing or empt y, port 80 is assumed.
ACCEPT-LANGUAGE
(No ACCEPT-LANGUAGE header field is used in event messages.)
CONTENT-LENGTH
REQUIRED if Origin Server does not close t he session aft er sending t he response AND Origin Server does not send t he
response using chunked encoding.
PROHIBITED if Origin Server sends t he response using chunked encoding. OPTIONAL ot herwise.
Field value specifies t he lengt h of t he body in byt es. Int eger.
TRANSFER-ENCODING
OPTIONAL for HTTP/ 1.1 and above. Field value specifies whet her t he response is chunked encoded by having field value
chunked (in t he example above t he body is sent in a single chunk). MUST NOT be specified if CONTENT-LENGTH header
field is present .
CONTENT-TYPE
REQUIRED. Field value MUST be t ext / xml; charset ="ut f-8"
NT
REQUIRED. Field value cont ains Not ificat ion Type. MUST be upnp:event.
NTS
REQUIRED. Field value cont ains Not ificat ion Sub Type. MUST be upnp:propchange.
SID
REQUIRED. Field value cont ains Subscript ion Ident ifier. MUST be universally unique. MUST begin wit h uuid:. Defined by UPnP
vendor. See sect ion 1.1.4, UUID format and RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format .
SEQ
REQUIRED. Field value cont ains Event Key. MUST be 0 for init ial event message. MUST be increment ed by 1 for each event
message sent t o a part icular subscriber. To prevent overflow, MUST be wrapped from 4294967295 t o 1. 32-bit unsigned
value represent ed as a single decimal int eger wit hout leading zeroes (some implement at ions MAY include leading zeroes,
which SHOULD be ignored by t he recipient ).
Body
<propertyset>
REQUIRED. xmlns namespace at t ribut e MUST be urn:schemas-upnp-org:event-1-0. Cont ains t he following sub element :
property>
REQUIRED. Repeat once for each variable name and value in t he event message. MUST be qualified by t he
namespace prefix defined in t he xmlns at t ribut e of t he <propertyset> element . Cont ains t he following sub
element :
<variableName>
REQUIRED. Element is name of a st at e variable t hat changed (<name> sub element of
<stateVariable> element in service descript ion). MUST NOT be qualified wit h any namespace. Value
is t he new value for t his st at e variable. Case sensit ive. Single dat a t ype as specified by UPnP service
descript ion.
For fut ure ext ensibilit y and according t o t he requirement s in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8,
UPnP Device Schema , when processing XML like t he list ing above, devices and cont rol point s MUST ignore: (a) any unknown
element s and t heir sub element s or cont ent , and (b) any unknown at t ribut es and t heir values. Not e t hat when subscribing t o
event ing wit h a service t hat is of a higher version t han what is support ed by t he cont rol point , event not ificat ions MAY be sent by
t he service t o t he cont rol point cont aining st at e variable names t hat are not recognized by t he cont rol point . The cont rol point
SHOULD discard and ignore such unrecognized st at e variables wit hin event not ificat ion messages.

When t he new value of any variable cont ains one or more charact ers reserved as markup (such as ampersand ( & ) or less t han
( < )), t he t ext MUST be escaped in accordance wit h t he provisions of sect ion 2.4 of t he XML specificat ion and each such
charact er replaced wit h t he equivalent numeric represent at ion or st ring (such as &amp; or &lt ; ). Such charact ers appearing

99

in URLs t hat appear as values MAY also be percent -encoded in accordance wit h t he URL percent -encoding rules specified in
sect ions 2.1 and 2.4 of RFC 3986.

On a mult i-homed device, all fully-qualified URLs cont ained in event body t hat refer t o resources on t he device MUST be
reachable on t he UPnP-enabled int erface on which t he event message is sent .

Subj ect t o t he const raint s defined in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8, UPnP Device Schema ,
cont rol point s and devices MUST ignore any XML comment s or XML processing inst ruct ions embedded in UPnP event messages t hat
t hey do not underst and. Not e t hat because HTTP 1.1 allows use of chunked encoding, some devices MAY send t he event
not ificat ion using chunked encoding if t he SUBSCRIBE request specified HTTP 1.1. It is t herefore RECOMMENDED t hat all
implement at ions t hat include HTTP 1.1 in t he SUBSCRIBE request support receiving chunked encoding.

To acknowledge receipt of t his event message, a subscriber MUST respond wit hin 30 seconds, including expect ed t ransmission
t ime. A mult i-homed subscriber MUST send t he response using t he same pair of UPnP-enabled int erfaces used for t he event
message. If a subscriber does not respond wit hin 30 seconds, or if t he publisher is unable t o connect t o t he subscript ion URL, t he
publisher SHOULD abandon sending t his message t o t he subscriber but MUST keep t he subscript ion act ive and send fut ure event
messages t o t he subscriber unt il t he subscript ion expires or is cancelled. The subscriber MUST send a response in t he following
format .

HTTP/1.1 200 OK

Response line
HTTP/ 1.1
Highest HTTP version support ed by t he cont rol point t hat is compat ible wit h t he device t hat sent t he event message.
200 OK
HTTP defined st at us code indicat ing t hat no HTTP errors were det ect ed.
(No body for a request wit h met hod NOTIFY, but not e t hat t he message MUST have a blank line following t he last HTTP header
field.)

If a device sends an event t o a cont rol point using HTTP/ 1.0 wit hout t he KeepAlive t oken, t he cont rol point MUST close t he
socket aft er responding. If a device sends an event t o a cont rol point using HTTP/ 1. 1 and set s t he Connect ion:CLOSE t oken, t he
cont rol point MUST close t he socket aft er responding.

If t here is an error wit h t he event message, t he subscriber MUST respond wit h one of t he following errors. The response MUST be
sent wit hin 30 seconds, including expect ed t ransmission t ime.

100

Table 4-7:

HTTP Status Codes indicating a Notify Error

ErrorCode

errorDescription

Description

400

Bad request

The NT or NTS header field is missing;


or t he request is malformed.

412

Precondit ion Failed

An SID does not correspond t o a known, un-expired subscript ion;


or t he NT header field does not equal upnp:event;
or t he NTS header field does not equal upnp:propchange;
or t he SID header field is missing or empt y.

Ot her errors, including ot her HTTP st at us codes, MAY be ret urned by layers in t he prot ocol st ack below t he UPnP prot ocols.
Consult document at ion on t hose prot ocols for det ails.

4.3.3 Multicast Eventing: Event messages: NOTIFY


To send a mult icast event message, a publisher MUST send a message wit h met hod NOTIFY using t he following format . The
following example illust rat es an event message using t he CONTENT-LENGTH header. Values in it al ics are placeholders for act ual
values.

A mult i-homed publisher MUST mult icast t he event message on each of it s UPnP-enabled int erfaces. Event messages sent on
different UPnP-enabled int erfaces t hat have t he same sequence number MUST cont ain t he same cont ent except for possibly t he
HOST header field and any fully-qualified URLs cont ained in t he event body. The HOST header field of an advert isement MUST be
t he st andard mult icast event ing address specified for t he prot ocol (IPv4 or IPv6) used on t he int erface. All fully-qualified URLs
cont ained in t he event body t hat refer t o resources on t he device MUST be reachable on t he UPnP-enabled int erface on which
t he event message is sent .

Not e: XML namespace prefixes do not have t o be t he specific example shown below (e.g., s or u ); t hey can be any value t hat
obeys t he rules of t he general XML namespace mechanism; cont rol point s MUST accept event messages t hat use ot her legal XML
namespace prefixes.
Multicast event message using the CONTENT-LENGTH header Valid with HTTP/1.0 or HTTP/1.1
NOTIFY * HTTP/1.0
HOST: 239.255.255.246:7900 *** note the port number is different than SSDP ***
CONTENT-TYPE: text/xml; charset="utf-8"
USN: Unique Service Name for the publisher
SVCID: ServiceID from SCPD
NT: upnp:event
NTS: upnp:propchange
SEQ: monotonically increasing sequence count
LVL: event importance
BOOTID.UPNP.ORG: number increased each time device sends an initial announce or update
message
CONTENT-LENGTH: bytes in body
<?xml version="1.0"?>
<e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">
<e:property>
<variableName>new value</variableName>
</e:property>
<!-- Other variable names and values (if any) go here. -->
</e:propertyset>

101

List ed below are det ails for t he request line, header fields, and body element s appearing in t he list ing above. Field names are
not case sensit ive. All field values are case sensit ive except where not ed. All body element s and at t ribut es are case sensit ive;
body values are not case sensit ive except where not ed. Except where not ed, REQUIRED element s MUST occur exact ly once (no
duplicat es), and RECOMMENDED or OPTIONAL element s MAY occur at most once. In part icular, a single propertyset element
MUST NOT include more t han one property element t hat specifies t he same variableName element ; separat e event not ificat ion
messages MUST be used.
Request line
MUST be NOTIFY * HTTP/ 1.1
Header fields
HOST
REQUIRED. Field value MUST be 239.255.255.246:7900. Please not e t hat port number 7900 is different from SSDP port
number 1900.
CONTENT-LENGTH
REQUIRED. Field value specifies t he lengt h of t he body in byt es. Int eger. Chunked encoding MUST NOT be used for mult icast
event messages.
CONTENT-TYPE
REQUIRED. Field value MUST be text/ xml; charset="utf-8" .
USN
REQUIRED. Field value cont ains Unique Service Name for t he publisher. Ident ifies a unique inst ance of a service in a unique
inst ance of a device. It MUST be one of t he following forms. The prefix (before t he double colon) MUST mat ch t he value of
t he UDN element in t he device descript ion. (Sect ion 2, Descript ion explains t he UDN element .) Single URI.
uuid:device-UUID::urn:schemas-upnp-org:service:serviceType:ver
where device-UUID is specified by t he UPnP vendor; serviceType and ver are defined by t he UPnP Forum working
commit t ee. See sect ion 1.1.4, UUID format and RECOMMENDED generat ion algorit hms for t he MANDATORY UUID
format .
uuid:device-UUID::urn:domain-name:service:serviceType:ver
where device-UUID, domain-name, serviceType and ver are defined by t he UPnP vendor. See sect ion 1.1.4, UUID
format and RECOMMENDED generat ion algorit hms for t he MANDATORY UUID format . Period charact ers in t he
domain name MUST be replaced by hyphens in accordance wit h RFC 2141.
SVCID
REQUIRED. Field value cont ains ServiceID from t he SCPD t o uniquely ident ify which service generat ed t he event . As defined
in sect ion 2.2, Generic requirement s on XML usage
NT
REQUIRED. Field value cont ains Not ificat ion Type. MUST be upnp:event.
NTS
REQUIRED. Field value cont ains Not ificat ion Sub Type. MUST be upnp:propchange.
SEQ
REQUIRED. Field value cont ains Event Key. The numeric sequence count MUST be 0 for init ial mult icast event message.
MUST be increment ed by 1 for each mult icast event message per a service; however, when a mult icast message is
ret ransmit t ed, it MUST be sent wit h it s original event key. To prevent overflow, MUST be wrapped from 4294967295 t o 1.
32-bit unsigned value represent ed as a single decimal int eger wit hout leading zeroes (leading zeroes, if present , MUST be
ignored by t he recipient ).
LVL
REQUIRED. Field value MUST be a st ring in UTF-8. Event level allows t he receiver t o first level filt er messages based on t he
value and is defined by t he UPnP Technical Commit t ee. See Table 4-8, Mult icast event levels for t he Event Levels defined
wit h t his version of t he UPnP archit ect ure. UPnP Working Commit t ees MUST specify event level values when defining event s
t hat will be mult icast .
The following t able summarizes defined event levels and t he expect ed meaning of t hose values. Event levels defined by t he
UPnP Forum Technical Commit t ee st art wit h t he prefix upnp: . Vendor and ot her ext ensions out side t he UPnP Forum MUST
be prefixed by t he domain name of t he defining organizat ion. For example: domain.org:/ alert s/ level/

102

Table 4-8:

Multicast event levels


Event Level

Description

upnp:/ emergency

The event carries crit ical informat ion t hat t he device


SHOULD act upon immediat ely.

upnp:/ fault

The event carries informat ion relat ed t o an error


case

upnp:/ warning

The event carries informat ion t hat is a non-crit ical


condit ion t hat t he device MAY want t o process or
pass t o t he user

upnp:/ info

The event carries informat ion about t he normal


operat ion of t he device t hat may be of int erest t o
end-users. This informat ion is simply informat ive
and does not indicat e any abnormal condit ion or
st at us such as a warning or fault . Ot her event levels
are defined for t hose purposes.

upnp:/ debug

The event carries debug informat ion t ypically used


by programmers and t est engineers t o evaluat e t he
int ernal operat ion of t he device. This informat ion is
t ypically not displayed t o end users.

upnp:/ general

For event s t hat fit int o no ot her defined cat egory

<domain>:/ <l evel >

Example vendor ext ension. Domain is t he ICANN


domain name for t he vendor and level is an arbit rary
st ring defined by t he vendor. E.g.
domain.org:/ alert s/ t ype/

BOOTID.UPNP.ORG
REQUIRED. As defined in sect ion 1.2, and 1.2.2.
Body
<propertyset>
REQUIRED. xmlns namespace MUST be urn:schemas-upnp-org:event-1-0 . Cont ains t he following sub element :
<property>
REQUIRED. Repeat once for each variable name and value in t he event message. MUST be qualified by t he
namespace prefix defined in t he xmlns at t ribut e of t he <propertyset> element . Cont ains t he following sub
element :
<variableName>
REQUIRED. Element is name of a st at e variable t hat changed (name sub element of stateVariable
element in service descript ion). MUST NOT be qualified wit h any namespace. Value is t he new value for
t his st at e variable. Case sensit ive. Single dat a t ype as specified by UPnP service descript ion.
Not e t hat for simplicit y many of t he header fields for mult icast event ing are t he same as for unicast event ing. These include:
HOST, CONTENT-TYPE, USN, NT, NTS, and SEQ. In addit ion, t he body of t he message (propert yset ) has t he same format as
unicast event s.

For fut ure ext ensibilit y and according t o t he requirement s in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8,
UPnP Device Schema , when processing XML like t he list ing above, devices and cont rol point s MUST ignore: (a) any unknown
element s and t heir sub element s or cont ent , and (b) any unknown at t ribut es and t heir values. Subj ect t o t he const raint s defined
in sect ion 2.7, Non-st andard vendor ext ensions and sect ion 2.8, UPnP Device Schema , cont rol point s and devices MUST
ignore any XML comment s or XML processing inst ruct ions embedded in UPnP device and service descript ions t hat t hey do not
underst and. The cont rol point SHOULD discard and ignore unrecognized st at e variables wit hin mult icast event not ificat ion
messages.

103

When t he new value of any variable cont ains one or more charact ers reserved as markup (such as ampersand ( & ) or less t han
( < )), t he t ext MUST be escaped in accordance wit h t he provisions of sect ion 2.4 of t he XML specificat ion and each such
charact er replaced wit h t he equivalent numeric represent at ion or st ring (such as &amp; or &lt ; ). Such charact ers appearing
in URLs t hat appear as values MAY also be percent -encoded in accordance wit h t he URL percent -encoding rules specified in
sect ions 2.1 and 2.4 of RFC 3986.

4.4 UPnP Event Schema


The UPnP Event Schema defines t he st ruct ures and dat a t ypes used in t he body of UPnP event not ificat ions. As explained wit h
t he UPnP Device and Service Schemas, t he UPnP Event Schema is writ t en in XML synt ax according t o t he convent ions of XML
Schema (Part 1: St ruct ures, Part 2: Dat at ypes). The UPnP Event Schema is defined wit hin a UPnP service t emplat e; however, t he
schema MUST conform t o t he format as defined in appendix B.5, UPnP Event Schema . The element s it defines are used in
event not ificat ions.

As explained in sect ion 2, Descript ion , t he UPnP Service Schema also specifies a sendEvents at t ribut e for a st at e variable.
The default value for t his at t ribut e is yes . To denot e t hat a st at e variable is event ed, t he value of t his at t ribut e is yes (or
t he at t ribut e is omit t ed) in a service descript ion; t o denot e t hat a st at e variable is non-event ed, t he value is no . Not e t hat if
all of a service's st at e variables are non-event ed, t he service has not hing t o publish, and cont rol point s cannot subscribe and will
not receive event messages from t he service.

4.5 Augmenting the UPnP Device and Service Schemas


Some st at e variables may change value t oo rapidly for event ing t o be useful. UPnP Forum Working Commit t ees or UPnP vendors
may document moderat ion in t he number of event messages sent due t o changes in a variable s value. Event moderat ion may
include limit at ion on t he frequency in report ing change of a st at e variable value or a minimum degree of change t hat must occur
before a change is report ed.

Paramet er

Descript ion

maximumRate

Single numeric value (in seconds) of t ype int eger or float . St at e variable v MUST NOT be part of an
event message more oft en t han every n seconds. If v is t he only st at e variable changing, t hen an
event message cont aining t he st at e variable MUST NOT be generat ed more oft en t han every n
seconds. If v has changed sooner t han n seconds from t he last event message t hat cont ains v, t hen an
event message cont aining t he current value of v MUST be sent in a t imely manner aft er n seconds
from t he previous event message cont aining v. If v has not changed wit hin n seconds following t he
last event message t hat cont ains v, t hen when v does change an event message wit h t he current
value of v MUST be sent in a t imely manner. Specifying a maximumRate value is useful for variables
t hat model frequent ly changing st at e variables.

minimumDelta

Single numeric value (minimum change required) whose t ype MUST mat ch t he corresponding st at e
variable. St at e variable v MUST NOT be part of an event message unless it s value has changed (plus
or minus) by at least minimumDelta since t he last t ime an event message was sent t hat cont ains v.
Only valid for st at e variables wit h a numeric (int eger or float ) dat a t ype. Specifying a minimumDelta
value is useful for variables t hat model cont inuously changing st at e variables.

The publisher MAY send out any changed moderat ed variable when an event goes out . The publisher MUST meet moderat ion rules
described above, but t he publisher MAY flush recent changes when it sends out an event message.

104

Not e t hat moderat ion affect s event s only and not st at e t able updat es. Specifically, cont rol act ions which ret urn t he value of
st at e variables MAY ret urn a more current value t han published via event ing. Put anot her way, moderat ion means t hat not all
st at e t able changes result in event s.

Decisions about which variables t o event and any possible moderat ion is up t o t he appropriat e UPnP Forum working commit t ee
(for st andard services) or a UPnP vendor (for non-st andard services).

4.6 References
RFC 2616
HTTP: Hypert ext Transfer Prot ocol 1.1. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2616.t xt .
RFC 3986
Uniform Resource Ident ifiers (URI): Generic Synt ax. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc3986.t xt .
XML
Ext ensible Markup Language. Available at : ht t p:/ / www.w3.org/ TR/ 2000/ REC-xml-20001006.
XML Schema (Part 1: St ruct ures, Part 2: Dat at ypes)
Available at : ht t p:/ / www.w3.org/ TR/ xmlschema-1, ht t p:/ / www.w3.org/ TR/ xmlschema-2.

105

5 Presentation
[Normative]
Present at ion is St ep 5 in UPnPnet working. Present at ion comes af t er addressing (St ep 0) where devices get net work addresses,
af t er discovery (St ep 1) where cont rol point s f ind int erest ing device(s), and af t er descript ion (St ep 2) where cont rol point s
learn about device capabilit ies. Present at ion exposes an HTML-based user int erf ace f or cont rol l ing and/ or viewing device st at us.
Present at ion is complement ary t o cont rol (St ep 3) where cont rol point s send act ions t o devices, and event ing (St ep 4) where
cont rol point s list en t o st at e changes in device(s).

Aft er a cont rol point has (1) discovered a device and (2) ret rieved a descript ion of t he device, t he cont rol point is ready t o begin
present at ion. If a device has a URL for present at ion, t hen t he cont rol point can ret rieve a page from t his URL, load t he page int o
a browser and, depending on t he capabilit ies of t he page, allow a user t o cont rol t he device and/ or view device st at us. The
degree t o which each of t hese can be accomplished depends on t he specific capabilit ies of t he present at ion page and device.

Figure 5-1:

Presentation architecture
root device
control point

HTTP GET
HTTP RESP

description
----------presentation URL
------

service

device/service operation
device

browser
HTML page

service
service

The URL for present at ion is obt ained from t he present at ionURL element in t he device descript ion. If present at ionURL is an
absolut e URL, t he fully qualified present at ion URL is t he present at ionURL. Ot herwise, if present at ionURL is a relat ive URL, t he
fully qualified present at ion URL is t he URL resolved from present at ionURL in accordance wit h sect ion 5 of RFC 3986, using eit her
t he URLBase element , if specified, or t he URL from which t he device descript ion was ret rieved as t he base URL. A mult i-homed
cont rol point t hat at t empt s t o ret rieve a present at ion page on a part icular UPnP-enabled int erface MUST use t he fully qualified
present at ion URL from t he descript ion document received on t hat int erface. The device descript ion is delivered via a descript ion
message. Sect ion 2, Descript ion explains t he device descript ion and descript ion messages in det ail.

Ret rieving a present at ion page is a simple HTTP-based process and uses t he following subset of t he overall UPnP prot ocol st ack.
(The overall UPnP prot ocol st ack is list ed at t he beginning of t his document .)

106

Figure 5-2:

Presentation protocol stack


UPnP vendor [purple-it alic]
UPnP Device Architecture [green-bold]
HTTP [black]
TCP [black]
IP [black]

At t he highest layer, t he present at ion page is specified by a UPnP vendor. Moving down t he st ack, t he UPnP Device Archit ect ure
specifies t hat t his page be writ t en in HTML. The page is delivered via HTTP over TCP over IP. For reference, colors in [square
bracket s] are included for consist ency wit h ot her sect ions in t his document .

To ret rieve a present at ion page, t he cont rol point issues an HTTP GET request t o t he present at ion URL, and t he device ret urns a
present at ion page. Responses t o HTTP GET request s for present at ion pages MUST be sent using t he same address on t he same
int erface on which t he HTTP GET was received. The generic requirement s on HTTP usage in UPnP 1.1 (as defined in sect ion 2.1,
Generic requirement s on HTTP usage of t his document ) MUST be followed by devices and cont rol point s t hat implement
present at ion.

Unlike t he UPnP Device and Service Templat es, and st andard device and service t ypes, t he capabilit ies of t he present at ion page
are complet ely specified by t he UPnP vendor. The page MUST be an HTML page; it is RECOMMENDED t hat t he page be based upon
XHTML-Basic. However, ot her design aspect s are left t o t he vendor t o specify. This includes, but is not limit ed t o, all capabilit ies
of t he cont rol point 's browser, script ing language or browser plug-ins used, and means of int eract ing wit h t he device. To
implement a present at ion page, a UPnP vendor MAY wish t o use UPnP mechanisms for cont rol and/ or event ing, leveraging t he
device's exist ing capabilit ies but is not const rained t o do so.

Present at ion pages SHOULD use mechanisms provided by HTML for localizat ion (e.g., META t ag wit h charset at t ribut e). Cont rol
point s SHOULD use t he ACCEPT-LANGUAGE and CONTENT-LANGUAGE feat ure of HTTP t o t ry t o ret rieve a localized present at ion
page. Specifically, a cont rol point MAY include a HTTP ACCEPT-LANGUAGE header field in t he request for a present at ion page; if
an ACCEPT-LANGUAGE header field is present in t he request , t he response MUST include a CONTENT-LANGUAGE header field t o
ident ify t he page's language.

It is RECOMMENDED t hat fully qualified URLs t o resources on t he device are not embedded in HTML present at ion pages, but t hat
relat ive URLs are used inst ead, so t hat t he host port ion of t he embedded URLs does not need t o be modified when sent on
different UPnP-enabled int erfaces.

5.1 References
RFC 3986
Uniform Resource Ident ifiers (URI): Generic Synt ax. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc3986.t xt .
HTML
HyperText Markup Language. Available at : ht t p:/ / www.w3.org/ TR/ ht ml4.

107

XHTMLBasic
Available at : ht t p:/ / www.w3.org/ TR/ xht ml-basic/ .

108

Appendix A.

IP Version 6 Support

[Normative]

A.1

Introduction

Most of t oday's Int ernet uses IPv4, which is now nearly t went y years old. IPv4 has been remarkably resilient in spit e of it s age,
but it is beginning t o have problems. Most import ant ly, t here is a growing short age of IPv4 addresses, which are needed by all
new machines added t o t he Int ernet . Deployment of large numbers of UPnP devices will only exacerbat e t he short age.

IPv6 fixes a number of problems in IPv4, such as t he limit ed number of available IPv4 addresses. It also adds many improvement s
t o IPv4 in areas such as rout ing and net work aut o configurat ion. IPv6 is expect ed t o gradually replace IPv4, wit h t he t wo
coexist ing for a number of years during a t ransit ion period.

This Annex describes mechanisms by which devices and cont rol point s based on t he UPnP Device Archit ect ure MAY be used on
IPv6 net works.

A.2

General Principles

Devices and cont rol point s MUST support IPv4-only, and MAY also support IPv6. IPv6-only devices and cont rol point s are NOT
allowed in UPnP, since t hese cannot int eroperat e wit h IPv4-only cont rol point s and devices. All IPv6 devices and cont rol point s
are t herefore inherent ly mult i-homed and must adhere t o all mult i-homed behaviors described in t he rest of t he document .

The following requirement s apply t o devices and cont rol point s using t he UPnP Device Archit ect ure over IPv6:

Devices and cont rol point s MUST obt ain a link-local address according t o RFC 2462. Devices and cont rol point s SHOULD use
t he same address as previously used whenever possible. Appendix A.3.2, Short overview of prot ocol specified by RFC 2462
present s a short overview of t he t heory of operat ion as specified by RFC 2462.

Devices and cont rol point s MUST t ry t o obt ain (t his may fail) a global address in each advert ised prefix wit h t he A bit set
according t o RFC 2462 (st at eless aut oconfigurat ion) and MAY t ry t o obt ain an IP address using DHCPv6, according t o RFC
3315 (st at eful aut oconfigurat ion, DHCPv6). Devices and cont rol point s SHOULD use t he same address as previously used
whenever possible. A device MAY decide not t o use it s link-local addresses for UPnP if it support s UPnP on at least one
global address on t he same int erface. This reduces overhead involved wit h announcing t he device on all it s addresses. A
device MUST offer UPnP on one of it s global addresses if it offers UPnP on a link-local address and it has successfully
obt ained a global address. This promot es int eroperabilit y and visibilit y of t he UPnP device in larger net works.

Devices and cont rol point s MUST list en for mult icast messages on link local scope FF02::C, sit e local scope FF05::C and
global scope FF0E::C (even if t he device or cont rol point does not have a global address,it MUST list en t o all scopes). See
also RFC 4291 for scope definit ions.

109

Devices MUST mult icast SSDP messages for each of t he UPnP-enabled int erfaces. The scope of mult icast SSDP messages
MUST be link local FF02::C if t he message is sent from a link local address. If t he message is sent from a global address it
MUST be mult icast using eit her global scope FF0E::C or sit e local scope FF05::C. In net works wit h complex t opologies and
overlapping sit es, use of global scope is RECOMMENDED.

The hop limit of each IP packet for a global scope mult icast message wit h a permanent ly assigned mult icast address (e.g.
FF0E::C for SSDP and FF0E::130 for mult icast event ing) SHOULD be set t o 254 and SHOULD be configurable.

Devices and cont rol point s MAY select t he int erface or int erfaces over which UPnP is enabled, when t he device or cont rol
point support s mult iple int erfaces.

Devices MUST list en for unicast SSDP t raffic on all it s UPnP-enabled addresses.

A.2.1

Device operation

A device support ing bot h IPv4 and IPv6 simult aneously MUST be advert ised using t he same USN on bot h IPv4 and IPv6 and MUST
have ident ical device descript ion document s and service descript ion document s when accessed from bot h prot ocols. The device
must also conform t o ot her mult i-homed descript ions in t he respect ive sect ions of t he document .

A.2.2

Control point operation

Cont rol point s can use t he mat ching USNs of IPv4 and IPv6 announcement s of dual st ack IPv4/ IPv6 devices t o t reat dual-st ack
devices as a single device. For example,a cont rol point can subscribe t o event s on IPv6 and invoke act ions on IPv4 based on t he
st at e informat ion received on t he IPv6 int erface. In addit ion, t he cont rol point must also conform t o ot her mult i-homed
descript ions in t he respect ive sect ions of t he document .

A.3

Addressing

RFC 2462 and RFC 3315 describe how a device or cont rol point obt ains an IPv6 address. Unlike when using IPv4, where each
device or cont rol point MUST have a DHCP client t o t ry t o obt ain an address init ially, DHCP is not always necessary in an IPv6
net work. Addresses are aut omat ically configured in new ways.

IPv6 mult icast addresses are formed using a component of t he address t o det ermine t he propagat ion of t he message sent . The
component is called scope and for UPnP 1.1, t he scope MUST be one of: link local, sit e local or global. Furt her, since t he
mult icast addresses used are permanent ly assigned, t he scope is encompassing. That is, link local scope is cont ained in sit e local
scope which is cont ained in global scope.

In IPv6 net works, a link-local address is det ermined per int erface on t he device or cont rol point , and t herefore IPv6 devices or
cont rol point s will always have a link-local address. In addit ion, unicast addresses are also det ermined for each int erface
alt hough a device or cont rol point MAY or MAY NOT have a global address. Typical IPv6 devices or cont rol point s are mult i-homed
because t hey always have at least t wo addresses wit h which t hey can receive packet s a link-local address for local link t raff ic

110

and a rout able global address. In some scenarios, devices or cont rol point s MAY only have a link-local address; reasons for t his
include device or cont rol point sophist icat ion (and t hereby device or cont rol point capabilit y) and administ rat ive policy. Linklocal addresses are assigned immediat ely at t he device or cont rol point , wit hout referring t o an out side server such as a DHCP
server. Global addresses are det ermined t hrough t he use of RA (Rout er Advert isement ) messages in conversat ion wit h t he local
rout er.

This sect ion describes t he IPv6 aut oconfigurat ion of unicast link-local addresses in more det ail. In addit ion t o t he address
assigned by t his process, each device or cont rol point , act ing as a normal IPv6 host , list ens for t raffic on several mult icast
addresses: node-local scope all-nodes mult icast address FF01::1; link-local scope all-nodes mult icast address FF02::1; and
mult icast addresses of j oined groups on each int erface.

Not e t hat in most implement at ions, t he act ions described are likely performed by t he IPv6 st ack and do not require any special
coding by UPnP implement ers.

A.3.1

Summary of boot/startup process


For IPv4, Aut o-IP addressing is performed as specified in sect ion 0, Addressing of t his document .

Opt ionally, for IPv6, address assignment is performed as specified in RFC 2462 and RFC 3315. A short summary of t he
prot ocol is provided below.

Not e t hat it is possible t o obt ain a global IPv4 address and only a link-local IPv6 address, or t he ot her way around.

A.3.2
1.

Short overview of protocol specified by RFC 2462

Host s generat e a link-local address for t he int erface. They t est uniqueness using Neighbor Solicit at ion messages cont aining
t he t ent at ive address.

2.

Host s obt ain a Rout er Advert isement or det ermine t hat no rout ers are present

Host s can send a Rout er Solicit at ion t o obt ain an advert isement quickly

3.

Rout er Advert isement s specify what sort of aut oconfigurat ion a host SHOULD do, if no rout ers are present , st at eful
aut oconfigurat ion MUST be invoked. Implement at ions MAY have an opt ion t o disable aut oconfigurat ion, but t he default
SHOULD be t hat aut oconfigurat ion is enabled.

A "ManagedFlag" flag indicat es whet her host s SHOULD use st at eful aut oconfigurat ion t o obt ain addresses (false by
default ).

111

An "ot her st at eful configurat ion" flag (false by default ) indicat es whet her host s SHOULD use st at eful aut oconfigurat ion
t o obt ain addit ional informat ion (excluding addresses). By default , st at eless aut oconfigurat ion is used.

4.

In t he presence of Rout er Advert isement s wit h ManagedFlag=false, Rout er Advert isement s cont ain prefixes t hat ident ify t he
subnet (s) associat ed wit h a link. A (global) address is formed by combining a prefix wit h t he ident it y of t he int erface
(t ypically MAC address) on which IPv6 is used.

5.

In t he presence of Rout er Advert isement s wit h ManagedFlag=t rue, DHCPv6 MUST be used t o obt ain an address.

6.

Host s will cont inually receive new advert isement s, adding t o and refreshing informat ion received in previous advert isement s.

7.

To speed t he aut oconfigurat ion process, a host MAY generat e it s link-local address (and verify it s uniqueness) in parallel
wit h wait ing for a Rout er Advert isement .

A.4

Discovery

The UPnP discovery phase does not subst ant ially change when used over IPv6. All definit ions of sect ion 1, Discovery of t his
document MUST be followed, except when a change is ment ioned in t his sect ion.

IGMP is t he prot ocol used by IPv4 t o ensure t hat incoming mult icast t raffic is forwarded by a rout er t o t he net work segment t o
which t he rout er is at t ached. IGMP requires t hat t he devices and cont rol point s at t ached t o t he net work segment cont act t he
rout er t o not ify it of t heir int erest in cert ain mult icast addresses. The prot ocol t hat provides t his service in IPv6 is Mult icast
List ener Discovery prot ocol (MLD). Cont rol point s and devices MUST part icipat e in t he prot ocol for any IPv6 mult icast scope t hat
is not link local and is list ened t o by an int erface.

IP Addresses embedded in UPnP messages and descript ions sent in response t o request s received on IPv6 addresses will generally
be lit eral addresses format t ed according t o RFC 2732 (including t hose in discovery messages, t he URLBase element of t he device
descript ion (if specified), and HTTP HOST header fields). Toget her wit h t he UUID, t he BOOTID.UPNP.ORG header field allows
cont rol point s t o recognize when a message received on a different prot ocol or address is referring t o t he same device t hat is
mult i-homed (in t his case, t he BOOTID.UPNP.ORG field value will be t he same in all announcement s), as opposed t o being a new
advert isement from a device which has changed from one prot ocol or address t o anot her (in t his case, t he BOOTID.UPNP.ORG
field value will differ bet ween t he old and t he new announcement ).

For backward compat ibilit y wit h cont rol point s implement ing UPnP over IPv6 according t o t he provisions of Annex A t o UPnP
Device Archit ect ure version 1.0, devices SHOULD include an OPT header field and NLS header field in addit ion t o t he
BOOTID.UPNP.ORG header field. The OPT header field is defined by t he HTTP Ext ension Framework (RFC 2774); t he OPT header
field is used (rat her t han MAN) because it is possible for a cont rol point t o funct ion wit hout recognizing t he NLS header field,
alt hough t he user experience will be subopt imal (and IPv4-only cont rol point s may not recognize NLS). The NLS field value, as
defined in Annex A t o UPnP Device Archit ect ure version 1.0, cont ains a st ring value which must change whenever t he net work

112

configurat ion of t he device changes. It was recommended in t hat Annex t hat a GUID be used as t he NLS field value, but ot her
mechanisms for producing a unique value were permit t ed. Since under UPnP Device Archit ect ure version 1.1 t he
BOOTID.UPNP.ORG field value is required t o be unique on each device reboot or configurat ion change, t he field value of t he NLS
header field can be set t he same as t he field value of t he BOOTID.UPNP.ORG header field t o simplify implement at ion.

A.4.1

Advertisement

For IPv6, a device advert ises over IPv6 according t o t he following guidelines:

SSDP announcement s are sent t o [FF0X::C]:1900 (wit h X being set appropriat ely depending on t he mult icast
scope upon which t he announcement is being sent ). Cont rol point s list en t o t hese addresses and port s t o det ect when
new devices are available on t he net work.

As described in sect ion 1.2.2 Device available - NOTIFY wit h ssdp:alive , announcement s sent over IPv6 MAY have a
different CACHE-CONTROL field value and MAY be sent wit h a different frequency t han announcement s sent over IPv4.
When all advert isement s, bot h over IPv4 and IPv6, have expired, t he cont rol point MUST assume t hat t he device (or
service) is no longer available.

The SSDP HOST field value cont ains an IPv6 address inst ead of an IPv4 address. The Int ernet Assigned Numbers
Aut horit y (IANA) has regist ered mult icast address and port for SSDP: an address MUST be of t he form FF0X::C. This is
a variable scope mult icast address where X is changed t o represent t he appropriat e scope. For example, a device
advert ising on t he local link would use a scope of 2 and address FF02::C. Port 1900 MUST be specified. For example,
for a global scope broadcast t he HOST header field is: HOST: [FF0E::C]:1900. In IPv6 announcement s, t he SSDP HOST
header field will t ypically cont ain a lit eral IPv6 address, format t ed according t o RFC 2732, followed by a port number.

The SSDP LOCATION field value cont ains t he URL of t he root device descript ion document . Typically, a lit eral IPv6
address format t ed according t o RFC 2732 will be used. An IPv6 address MUST be cont ained wit hin bracket s if a port is
specified. The host address in t he URL MUST be valid wit hin t he current scope (t he address or scope on which t he
announcement is being sent ). Specifically, a device advert ising over IPv6 MUST NOT use an IPv4 address in t he SSDP
LOCATION header field.

The OPT and NLS header fields SHOULD be included.

The example below incorporat es t his synt ax.

NOTIFY * HTTP/1.1
HOST: [FF02::C]:1900
CACHE-CONTROL: max-age = seconds until advertisement expires
LOCATION: URL for UPnP description of this device
OPT: "http://schemas.upnp.org/upnp/1/0/"; ns=01
01-NLS: same value as BOOTID field value
NT: notification type
NTS: ssdp:alive

113

SERVER: OS/version UPnP/1.1 product/version


BOOTID.UPNP.ORG: number increased each time device sends an initial announce or update
message
CONFIGID.UPNP.ORG: number used for caching description information
USN: composite identifier for the advertisement

A.4.2

Advertisement: Device unavailable

All ssdp:byebye messages MUST be sent t o t he IPv6 mult icast address as described in sect ion A.4.1 Advert isement , and SHOULD
cont ain t he OPT and NLS header fields. Ot herwise, t he behavior is t he same as IPv4. An example of an ssdp:byebye message has
t he following synt ax.

NOTIFY * HTTP/1.1
HOST: [FF02::C]:1900
NT: notification type
OPT: "http://schemas.upnp.org/upnp/1/0/"; ns=01
01-NLS: same value as BOOTID field value
NTS: ssdp:byebye
BOOTID.UPNP.ORG: number increased each time device sends an initial announce or update
message
CONFIGID.UPNP.ORG: number used for caching description information
USN: composite identifier for the advertisement

A.4.3

Advertisement: Device update

All ssdp:updat e messages MUST be sent t o t he IPv6 mult icast address as described in sect ion A.4.1 Advert isement , and SHOULD
cont ain t he OPT and NLS header fields. Ot herwise, t he behavior is t he same as IPv4. An example of an ssdp:updat e message has
t he following synt ax.

NOTIFY * HTTP/1.1
HOST: [FF02::C]:1900
LOCATION: URL for UPnP description for root device
NT: notification type
OPT: "http://schemas.upnp.org/upnp/1/0/"; ns=01
01-NLS: same value as BOOTID field value
NTS: ssdp:update
USN: composite identifier for the advertisement
BOOTID.UPNP.ORG: BOOTID value that the device has used in its previous announcements
CONFIGID.UPNP.ORG: number used for caching description information
NEXTBOOTID.UPNP.ORG: new BOOTID value that the device will use in subsequent announcements
SEARCHPORT.UPNP.ORG: number identifies port on which device responds to unicast M-SEARCH

A.4.4

Search

When a cont rol point is added t o t he net work, it MAY send mult icast M-SEARCH request s on it s IPv4 address(es), IPv6 address(es),
or bot h. When searching over IPv6, a cont rol point can freely choose t he scope of t he search (link local scope, sit e scope,
administ rat ive scope, organizat ional scope, global scope), allowing it t o bet t er direct it s search. It should be not ed t hat t he
source address of t he M-SEARCH can influence how and where t he M-SEARCH is rout ed. Aside from using an IPv6 mult icast
address and including an IPv6 address in t he header fields, M-SEARCH messages are unchanged. An example of an M-SEARCH
message has t he following synt ax. In addit ion, M-SEARCH messages MAY be unicast t o IPv6 addresses of known devices, similar t o
IPv4 unicast M-SEARCH messages.

114

M-SEARCH * HTTP/1.1
HOST: [FF02::C]:1900
MAN: "ssdp:discover"
MX: seconds to delay response
ST: search target

A.4.5

Search response

To be found, a device MUST send a response t o t he source IP address and port t hat sent t he request t o t he mult icast address, and
SHOULD include t he OPT and NLS header fields in t he message. An example of a search response message has t he following
synt ax.

HTTP/1.1 200 OK
CACHE-CONTROL: max-age = seconds until advertisement expires
DATE: when response was generated
EXT:
LOCATION: URL for UPnP description of this device
SERVER: OS/version UPnP/1.1 product/version
OPT: "http://schemas.upnp.org/upnp/1/0/"; ns=01
01-NLS: same value as BOOTID field value
ST: search target
BOOTID.UPNP.ORG: number increased each time device sends an initial announce or update
message
CONFIGID.UPNP.ORG: number used for caching description information
USN: composite identifier for the advertisement

A.5

Description

Descript ion document s MUST be sent using t he same address on which t he HTTP GET was received. Ot herwise, behavior is t he
same as IPv4.

A.6

Control

Responses t o SOAP messages during t he Cont rol phase MUST be sent on t he same address on which t he request was received.
Ot herwise, behavior is t he same as IPv4.

A.7

Eventing

When subscribing t o event s over IPv6, t he <deliveryURL> (or URLs) specified in t he CALLBACK header field of t he SUBSCRIBE
message MUST be reachable by t he device. This means, for example, when sending a SUBSCRIBE request t o a device using a linklocal IPv6 address, t he <deliveryURL> MUST specify an IPv6 address on t he same link, preferably a link-local address.

IPv4 addresses MUST NOT be included in t he CALLBACK header field of a SUBSCRIBE message sent over IPv6. IPv6 addresses MUST
NOT be included in t he CALLBACK header field of a SUBSCRIBE message sent over IPv4.

IPv6 mult icast event messages MUST be sent t o [FF0X::130]:7900 (wit h X being equal t o t he address scope used in
advert isement ). To receive IPv6 mult icast event messages, cont rol point s MUST list en t o t hese addresses and port s.

115

To send a mult icast event message, a publisher MUST send a message wit h met hod NOTIFY in t he following format . Values in
it alics below are placeholders for act ual values. Refer t o sect ion 4.3.3 Mult icast Event ing: Event messages: NOTIFY for
explanat ion of t he element s. All IP addresses cont ained in t he event MUST be IPv6 format and scoped as above.

NOTIFY * HTTP/1.1
HOST: [FF0X::130]:7900 *** note the address and the port number are different from SSDP ***
CONTENT-TYPE: text/xml; charset="utf-8"
USN: Unique Service Name for the publisher
SVCID: ServiceID from SCPD
NT: upnp:event
NTS: upnp:propchange
SEQ: monotonically increasing sequence count
LVL: event importance
BOOTID.UPNP.ORG: number increased each time device sends an initial announce or an update
message
<?xml version="1.0"?>
<e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">
<e:property>
<variableName>new value</variableName>
</e:property>
<!-- Other variable names and values (if any) go here. -->
</e:propertyset>

A.8

Presentation

Responses t o HTTP GET request s for present at ion pages MUST be sent using t he same address on t he same int erface on which t he
HTTP GET was received.

Present at ion pages ret rieved over IPv6 MUST NOT cont ain IPv4 addresses. Present at ion pages ret rieved over IPv4 MUST NOT
cont ain IPv6 addresses.

It is RECOMMENDED t hat fully qualified URLs t o resources on t he device are not embedded in HTML present at ion pages, but t hat
relat ive URLs are used inst ead, so t hat t he host port ion of t he embedded URLs does not need t o be modified t o mat ch t he
address on which t he GET was received.

A.9

References

RFC 2732
Format for Lit eral IPv6 Addresses in URLs. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2732.t xt .
RFC 2774
HTTP Ext ension Framework. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2774.t xt .
RFC 2462
IPv6 St at eless Address Aut oconfigurat ion. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc2462.t xt .
RFC 3315
Dynamic Host Configurat ion Prot ocol for IPv6 (DHCPv6). Available at : ht t p:/ / www.iet f.org/ rfc/ rfc3315.t xt .
RFC 3986
Uniform Resource Ident ifiers (URI): Generic Synt ax. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc3986.t xt .
RFC 4291
IP Version 6 Addressing Archit ect ure. Available at : ht t p:/ / www.iet f.org/ rfc/ rfc4291.t xt .

116

Appendix B.

Schemas

[Informative]

B.1

UPnP Device Schema

Below is t he UPnP Device Schema for devices (see also sect ion 2.10, UPnP Dat at ype Schema ). The element s it defines are used
in UPnP Device Templat es; t hey are colored green t hroughout t his specificat ion. Immediat ely following t his is a brief explanat ion
of t he XML Schema element s, at t ribut es, and values used. The reference t o XML Schema at t he end of t he sect ion has furt her
det ails.

UPnP 1.0 specifies t hat t he namespace of t he device schema is urn:schemas-upnp-org:device-1-0 . UPnP 1.1 does not change
t hat namespace, but redefines it in a backwards-compat ible way by rest rict ing t he order in which element s can be sent and
REQUIRING t he presence of t he configId at t ribut e. Therefore, t he schema below specifies t he synt ax t o which a UPnP 1.1
Device Descript ion Document has t o adhere. UPnP 1.1 cont rol point s also SHOULD expect Device Descript ion Document s from
UPnP 1.0 devices t hat can send element s in any order, and will not have t he configId at t ribut e.

<xsd:schema targetNamespace="urn:schemas-upnp-org:device-1-0"
xmlns="urn:schemas-upnp-org:device-1-0"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="root" type="rootType"/>
<xsd:complexType name="deviceType">
<xsd:sequence>
<xsd:element name="deviceType">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:anyURI">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="friendlyName">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="manufacturer">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="manufacturerURL" minOccurs="0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:anyURI">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>

117

</xsd:complexType>
</xsd:element>
<xsd:element name="modelDescription" minOccurs="0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="modelName">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="modelNumber" minOccurs="0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="modelURL" minOccurs="0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:anyURI">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="serialNumber" minOccurs="0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="UDN">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:anyURI">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="UPC" minOccurs="0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="iconList" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="icon" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>

118

<xsd:element name="mimetype">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="width">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:int">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="height">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:int">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="depth">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:int">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="url">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:anyURI">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="serviceList">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="service" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="serviceType">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:anyURI">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>

119

</xsd:element>
<xsd:element name="serviceId">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:anyURI">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="SCPDURL">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:anyURI">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="controlURL">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:anyURI">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="eventSubURL">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:anyURI">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="deviceList" type="deviceListType" minOccurs="0"/>
<xsd:element name="presentationURL" minOccurs="0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:anyURI">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
<xsd:complexType name="deviceListType">
<xsd:sequence>
<xsd:element name="device" type="deviceType" maxOccurs="unbounded"/>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
<xsd:complexType name="rootType">

120

<xsd:sequence>
<xsd:element name="specVersion">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="major">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:int">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="minor">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:int">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="URLBase" minOccurs="0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:anyURI">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="device" type="deviceType"/>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
</xsd:sequence>
<xsd:attribute name="configId" type="xsd:int"/>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:schema>

<element>
Defines a new element . name at t ribut e defines element name. type at t ribut e defines t he dat a t ype for t he cont ent of
element . minOccurs at t ribut e defines minimum number of t imes t he element MUST occur; default is
minOccurs="1"; OPTIONAL element s have minOccurs="0". maxOccurs at t ribut e defines maximum number of
t imes t he element MUST occur; default is maxOccurs="1"; element s t hat can appear one or more t imes have
maxOccurs="unbounded". For a more det ailed descript ion, see t he XML Schema specificat ion.
<complexType>
Defines a new dat a t ype, oft en cont aining sub-element s. For a more det ail descript ion, see t he XML Schema
specificat ion.
<attribute>
Defines a new at t ribut e for t he purpose of declaring in which element s it MAY appear. Like any XML element , t he
<at t ribut e> element MAY have at t ribut es of it s own. The use at t ribut e wit hin t his element indicat es whet her t he
at t ribut e MUST be present ; OPTIONAL at t ribut es have use="optional". For a more det ail descript ion, see t he XML
Schema specificat ion.

121

B.2

UPnP Service Schema

Below is t he UPnP Service Schema (see also sect ion 2.9, UPnP Service Schema ). The element s it defines are used in UPnP
Service Templat es; t hey are colored green t hroughout t his specificat ion. Immediat ely following t his is a brief explanat ion of t he
XML Schema element s, at t ribut es, and values used. The reference t o XML Schema at t he end of t he sect ion has furt her det ails.

UPnP 1.0 specifies t hat t he namespace of t he service schema is urn:schemas-upnp-org:service-1-0 . UPnP 1.1 does not change
t hat namespace, but redefines it in a backwards-compat ible way by rest rict ing t he order in which element s can be sent and
requiring t he presence of t he configId at t ribut e. Therefore, t he schema below specifies t he synt ax t o which a UPnP 1.1 SCPD
has t o adhere. UPnP 1.1 cont rol point s also SHOULD expect SCPDs from UPnP 1.0 devices t hat can send element s in any order,
and will not have t he configId at t ribut e.

<xsd:schema targetNamespace="urn:schemas-upnp-org:service-1-0"
xmlns="urn:schemas-upnp-org:service-1-0"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="scpd" type="scpdType"/>
<xsd:complexType name="directionType">
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
<xsd:complexType name="dataTypeType">
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="type" type="xsd:string"/>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
<xsd:complexType name="scpdType">
<xsd:sequence>
<xsd:element name="specVersion">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="major">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:int">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="minor">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:int">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="actionList" minOccurs="0">

122

<xsd:complexType>
<xsd:sequence>
<xsd:element name="action" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="argumentList" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="argument" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="direction">
<xsd:complexType>
<xsd:simpleContent>
<xsd:restriction base="directionType">
<xsd:enumeration value="in"/>
<xsd:enumeration value="out"/>
</xsd:restriction>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="retval" minOccurs="0">
<xsd:complexType>
<xsd:complexContent>
<xsd:restriction base="xsd:anyType">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="relatedStateVariable">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>

123

</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="serviceStateTable">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="stateVariable" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="dataType">
<xsd:complexType>
<xsd:simpleContent>
<xsd:restriction base="dataTypeType">
<xsd:enumeration value="ui1"/>
<xsd:enumeration value="ui2"/>
<xsd:enumeration value="ui4"/>
<xsd:enumeration value="i1"/>
<xsd:enumeration value="i2"/>
<xsd:enumeration value="i4"/>
<xsd:enumeration value="int"/>
<xsd:enumeration value="r4"/>
<xsd:enumeration value="r8"/>
<xsd:enumeration value="number"/>
<xsd:enumeration value="fixed.14.4"/>
<xsd:enumeration value="float"/>
<xsd:enumeration value="char"/>
<xsd:enumeration value="string"/>
<xsd:enumeration value="date"/>
<xsd:enumeration value="dateTime"/>
<xsd:enumeration value="dateTime.tz"/>
<xsd:enumeration value="time"/>
<xsd:enumeration value="time.tz"/>
<xsd:enumeration value="boolean"/>
<xsd:enumeration value="bin.base64"/>
<xsd:enumeration value="bin.hex"/>
<xsd:enumeration value="uri"/>
<xsd:enumeration value="uuid"/>
</xsd:restriction>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="defaultValue" minOccurs="0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:choice minOccurs="0">
<xsd:element name="allowedValueList">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="allowedValue" maxOccurs="unbounded">

124

<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="allowedValueRange">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="minimum">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:double">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="maximum">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:double">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="step" minOccurs="0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:double">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
</xsd:choice>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:attribute name="sendEvents" default="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="1"/>
<xsd:enumeration value="0"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="multicast" default="0">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="1"/>
<xsd:enumeration value="0"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
</xsd:complexType>

125

</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
</xsd:sequence>
<xsd:attribute name="configId" type="xsd:int"/>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:schema>
<element>
Defines a new element . name at t ribut e defines element name. type at t ribut e defines t he dat a t ype for t he cont ent of
element . minOccurs at t ribut e defines minimum number of t imes t he element MUST occur; default is
minOccurs="1"; OPTIONAL element s have minOccurs="0". maxOccurs at t ribut e defines maximum number of
t imes t he element MUST occur; default is maxOccurs="1"; element s t hat can appear one or more t imes have
maxOccurs="unbounded". For a more det ailed descript ion, see t he XML Schema specificat ion.
<complexType>
Defines a new dat a t ype, oft en cont aining sub-element s. For a more det ail descript ion, see t he XML Schema
specificat ion.
<attribute>
Defines a new at t ribut e for t he purpose of declaring in which element s it MAY appear. Like any XML element , t he
<at t ribut e> element MAY have at t ribut es of it s own. The use at t ribut e wit hin t his element indicat es whet her t he
at t ribut e MUST be present ; OPTIONAL at t ribut es have use="optional". For a more det ail descript ion, see t he XML
Schema specificat ion.

B.3

UPnP Control Schema

Below is t he t emplat e for UPnP Cont rol Schemas (see also sect ion 3.2.3, UPnP Act ion Schema ). The element s it defines are
used in act ions and act ion responses; t hey are colored green t hroughout t his specificat ion. Immediat ely following t his is a brief
explanat ion of t he XML Schema element s, at t ribut es, and values used. The reference t o XML Schema at t he end of t he sect ion
has furt her det ails.

<xsd:schema targetNamespace="urn:schemas-upnp-org:service:[serviceType:v]"
xmlns="urn:schemas-upnp-org:service:[serviceType:v]"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="[actionName]" type="[actionName]Type"/>
<xsd:element name="[actionName]Response" type="[actionName]ResponseType"/>
<xsd:complexType name="[actionName]Type">
<xsd:sequence>
<!-- Use this for an argument of simple content. -->
<xsd:element name="[argumentName]">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="[argumentType]">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<!-- Use this for an argument of complex content. -->
<xsd:element name="[argumentName]" type="[argumentType]"/>
<!-- Other arguments and their types go here, if any. -->
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
<xsd:complexType name="[actionName]ResponseType">
<xsd:sequence>

126

<!-- Use this for an argument of simple content. -->


<xsd:element name="[argumentName]">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="[argumentType]">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<!-- Use this for an argument of complex content. -->
<xsd:element name="[argumentName]" type="[argumentType]"/>
<!-- Other arguments and their types go here, if any. -->
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:schema>
<element>
Defines a new element . name at t ribut e defines element name. type at t ribut e defines t he dat a t ype for t he cont ent of
element . minOccurs at t ribut e defines minimum number of t imes t he element MUST occur; default is
minOccurs="1"; OPTIONAL element s have minOccurs="0". maxOccurs at t ribut e defines maximum number of
t imes t he element MUST occur; default is maxOccurs="1"; element s t hat can appear one or more t imes have
maxOccurs="unbounded". For a more det ailed descript ion, see t he XML Schema specificat ion.
<complexType>
Defines a new dat a t ype, oft en cont aining sub-element s. For a more det ail descript ion, see t he XML Schema
specificat ion.
<attribute>
Defines a new at t ribut e for t he purpose of declaring in which element s it MAY appear. Like any XML element , t he
<at t ribut e> element MAY have at t ribut es of it s own. The use at t ribut e wit hin t his element indicat es whet her t he
at t ribut e MUST be present ; OPTIONAL at t ribut es have use="optional". For a more det ail descript ion, see t he XML
Schema specificat ion.

B.4

UPnP Error Schema

Below is t he t emplat e for UPnP Error Schemas (see also sect ion 3.2.6, UPnP Error Schema ). The element s it defines are used in
error messages; t hey are colored green t hroughout t his specificat ion. Immediat ely following t his is a brief explanat ion of t he XML
Schema element s, at t ribut es, and values used. The reference t o XML Schema at t he end of t he sect ion has furt her det ails.

<xsd:schema targetNamespace="urn:schemas-upnp-org:control-1-0"
xmlns="urn:schemas-upnp-org:control-1-0"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="UPnPError" type="UPnPErrorType"/>
<xsd:complexType name="UPnPErrorType">
<xsd:sequence>
<xsd:element name="errorCode">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:int">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name="errorDescription">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>

127

</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:schema>
<element>
Defines a new element . name at t ribut e defines element name. type at t ribut e defines t he dat a t ype for t he cont ent of
element . minOccurs at t ribut e defines minimum number of t imes t he element MUST occur; default is
minOccurs="1"; OPTIONAL element s have minOccurs="0". maxOccurs at t ribut e defines maximum number of
t imes t he element MUST occur; default is maxOccurs="1"; element s t hat can appear one or more t imes have
maxOccurs="unbounded". For a more det ailed descript ion, see t he XML Schema specificat ion.
<complexType>
Defines a new dat a t ype, oft en cont aining sub-element s. For a more det ail descript ion, see t he XML Schema
specificat ion.
<attribute>
Defines a new at t ribut e for t he purpose of declaring in which element s it MAY appear. Like any XML element , t he
<at t ribut e> element MAY have at t ribut es of it s own. The use at t ribut e wit hin t his element indicat es whet her t he
at t ribut e MUST be present ; OPTIONAL at t ribut es have use="optional". For a more det ail descript ion, see t he XML
Schema specificat ion.

B.5

UPnP Event Schema

Below is t he t emplat e for t he UPnP Event Schema (see also sect ion 4.4, UPnP Event Schema ). The element s it defines are used
in event not ificat ions; t hey are colored green t hroughout t his specificat ion. Immediat ely following t his is a brief explanat ion of
t he XML Schema element s, at t ribut es, and values used. The reference t o XML Schema at t he end of t he sect ion has furt her
det ails.

<xsd:schema targetNamespace="urn:schemas-upnp-org:event-1-0"
xmlns="urn:schemas-upnp-org:event-1-0"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="propertyset" type="propertysetType"/>
<xsd:complexType name="propertysetType">
<xsd:sequence>
<xsd:element name="property" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<!-- Use this for a stateVariable of simple content. -->
<xsd:element name="[stateVariableName]" form="unqualified">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="[stateVariableType]">
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<!-- Use this for a stateVariable of complex content. -->
<xsd:element name="[stateVariableName]" type="[stateVariableType]"
form="unqualified"/>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:element>
<xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax"/>
</xsd:sequence>
<xsd:anyAttribute namespace="##other" processContents="lax"/>
</xsd:complexType>
</xsd:schema>

128

<element>
Defines a new element . name at t ribut e defines element name. type at t ribut e defines t he dat a t ype for t he cont ent of
element . minOccurs at t ribut e defines minimum number of t imes t he element MUST occur; default is
minOccurs="1"; OPTIONAL element s have minOccurs="0". maxOccurs at t ribut e defines maximum number of
t imes t he element MUST occur; default is maxOccurs="1"; element s t hat can appear one or more t imes have
maxOccurs="unbounded". For a more det ailed descript ion, see t he XML Schema specificat ion.
<complexType>
Defines a new dat a t ype, oft en cont aining sub-element s. For a more det ail descript ion, see t he XML Schema
specificat ion.
<attribute>
Defines a new at t ribut e for t he purpose of declaring in which element s it MAY appear. Like any XML element , t he
<at t ribut e> element MAY have at t ribut es of it s own. The use at t ribut e wit hin t his element indicat es whet her t he
at t ribut e MUST be present ; OPTIONAL at t ribut es have use="optional". For a more det ail descript ion, see t he XML
Schema specificat ion.

B.6

Schema references

XML
Ext ensible Markup Language. Available at : ht t p:/ / www.w3.org/ XML.
XML Schema (Part 1: St ruct ures, Part 2: Dat at ypes)
Available at : ht t p:/ / www.w3.org/ TR/ xmlschema-1, ht t p:/ / www.w3.org/ TR/ xmlschema-2.
Namespaces in XML
Available at : ht t p:/ / www.w3.org/ TR/ REC-xml-names/ .

129