3. Control
3.3 Control: Query for variable
606 Action not authorized The action requested requires authorization and the sender was not authorized.
607 Signature failure The sender's signature failed to verify.
608 Signature missing The action requested requires a digital signature and there was none provided.
609 Not encrypted This action requires confidentiality but the action was not delivered encrypted.
610 Invalid sequence The <sequence> provided was not valid.
611 Invalid control URL The controlURL within the <freshness> element does not match the controlURL of the action actually invoked (or the controlURL in the HTTP header).
612 No such session The session key reference is to a non-existent session. This could be because the device has expired a session, in which case the control point needs to open a new one.
600-699 TBD Common action errors. Defined by UPnP Forum Technical Committee.
700-799 TBD Action-specific errors for standard actions. Defined by UPnP Forum working committee.
800-899 TBD Action-specific errors for non-standard actions. Defined by UPnP vendor.
For future extensibility, when processing XML like the listing above, devices and control points must ignore: (a) any unknown elements and their sub elements or content, and (b) any unknown attributes and their values.
Control points and devices shall ignore any XML comments or XML processing instructions they may receive that they do not understand.
XML namespace prefixes do not have to be the specific examples given above (e.g., “s” or “u”); they can be any value that obeys the rules of the general XML namespace mechanism; control points must accept responses that use other legal XML namespace prefixes.
3.3.1 Control: Query: Invoke
To query for the value of a state variable, a control point must send a request in the following format. Values in italics are placeholders for actual values.
POST path of control URL HTTP/1.1
HOST: host of control URL:port of control URL CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
SOAPACTION: "urn:schemas-upnp-org:control-1-0#QueryStateVariable"
<s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<s:Body>
<u:QueryStateVariable xmlns:u="urn:schemas-upnp-org:control-1-0">
<u:varName>variableName</u:varName>
</u:QueryStateVariable>
</s:Body>
</s:Envelope>
Listed below are details for the request line, headers, and body elements appearing in the listing above. All header values and element names are case sensitive; values are not case sensitive except where noted. Except where noted, the order of elements is insignificant. Except where noted, required elements must occur exactly once (no duplicates), and recommended or optional elements may occur at most once.
Request line POST
Method defined by HTTP.
path of control URL
Path component of URL for control for this service (controlURL sub element of service element of device description).
Single, relative URL.
HTTP/1.1
HTTP version.
Headers HOST
Required. Domain name or IP address and optional port components of URL for control for this service (controlURL sub element of service element of device description). If the port is empty or not given, port 80 is assumed.
ACCEPT-LANGUAGE
(No ACCEPT-LANGUAGE header is used in control messages.) CONTENT-LENGTH
Required. Length of body in bytes. Integer.
CONTENT-TYPE
Required. Must be text/xml. Should include character coding used, e.g., utf-8.
MAN
(No MAN header in request with method POST.) SOAPACTION
Required header defined by SOAP. Must be "urn:schemas-upnp-org:control-1-0#QueryStateVariable". If used in a request with method M-POST, header name must be qualified with HTTP name space defined in MAN header. Single URI.
Body Envelope
Required element defined by SOAP. xmlns namespace attribute must be "http://schemas.xmlsoap.org/soap/envelope/".
Must include encodingStyle attribute with value "http://schemas.xmlsoap.org/soap/encoding/". Contains the following sub elements:
Body
Required element defined by SOAP. Should be qualified with SOAP namespace. Contains the following sub element:
QueryStateVariable
Required element defined by UPnP. Action name. xmlns namespace attribute must be
"urn:schemas-upnp-org:control-1-0". Must be the first sub element of Body. Contains the following, ordered sub element:
varName
Required element defined by UPnP. Variable name. Must be qualified by
QueryStateVariable namespace. Values is name of state variable to be queried. String.
For future extensibility, when processing XML like the listing above, as specified by the Flexible XML Processing Profile (FXPP), devices and control points must ignore: (a) any unknown elements and their sub elements or content, and (b) any unknown attributes and their values.
If a request with POST is rejected with a response of "405 Method Not Allowed", then a control point must send a second request with method M-POST and MAN as explained above.
3.3.2 Control: Query: Response
To answer a query for the value of a state variable, the service must respond within 30 seconds, including expected transmission time. If the service fails to respond within this time, what the control point should do is application-specific. The service must send a response in the following format. Values in italics are placeholders for actual values.
HTTP/1.1 200 OK
CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated EXT:
SERVER: OS/version UPnP/1.0 product/version
<s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<s:Body>
<u:QueryStateVariableResponse xmlns:u="urn:schemas-upnp-org:control-1-0">
<return>variable value</return>
</u:QueryStateVariableResponse>
</s:Body>
</s:Envelope>
Listed below are details for the response line, headers, and body elements appearing in the listing above. All header values and element names are case sensitive; values are not case sensitive except where noted. Except where noted, the order of elements is insignificant. Except where noted, required elements must occur exactly once (no duplicates), and recommended or optional elements may occur at most once.
Response line HTTP/1.1
HTTP version.
200 OK
HTTP success code.
Headers
CONTENT-LANGUAGE
(No CONTENT-LANGUAGE header is used in control messages.) CONTENT-LENGTH
Required. Length of body in bytes. Integer.
CONTENT-TYPE
Required. Must be text/xml. Should include character coding used, e.g., utf-8.
DATE
Recommended. When response was generated. “rfc1123-date” as defined in RFC 2616.
EXT
Required. Confirms that the MAN header was understood. (Header only; no value.) SERVER
Required. Concatenation of OS name, OS version, UPnP/1.0, product name, and product version. String.
Body Envelope
Required element defined by SOAP. xmlns namespace attribute must be "http://schemas.xmlsoap.org/soap/envelope/".
Must include encodingStyle attribute with value "http://schemas.xmlsoap.org/soap/encoding/". Contains the following sub elements:
Body
Required element defined by SOAP. Should be qualified with SOAP namespace. Contains the following sub element:
QueryStateVariableResponse
Required element defined by UPnP and SOAP. xmlns namespace attribute must be "urn:schemas-upnp-org:control-1-0". Must be the first sub element of Body. Contains the following sub element:
return
Required element defined by UPnP. (Element name not qualified by a namespace;
element nesting context is sufficient.) Value is current value of the state variable specified in varName element in request.
For future extensibility, when processing XML like the listing above, as specified by the Flexible XML Processing Profile (FXPP), devices and control points must ignore: (a) any unknown elements and their sub elements or content, and (b) any unknown attributes and their values.
When the value of any variable contains one or more characters reserved as markup (such as ampersand (“&”) or less than (“<”)), the text must be escaped in accordance with the provisions of section 2.4 of the XML specification and each such character replaced with the equivalent numeric representation or string (such as “&” or “<”). Such characters appearing in URLs may also be escaped in accordance with the URL escaping rules specified in Section 2.4 of RFC 2396.
If the service cannot provide a value for the variable, then the service must send a response within 30 seconds, including expected transmission time. The response must be sent in the following format. Values in italics are placeholders for actual values.
HTTP/1.1 500 Internal Server Error CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated EXT:
SERVER: OS/version UPnP/1.0 product/version
<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>
</s:Fault>
</s:Body>
</s:Envelope>
Listed below are details for the response line, headers, and body elements appearing in the listing above. All header values and element names are case sensitive; values are not case sensitive except where noted. Except where noted, the order of elements is insignificant. Except where noted, required elements must occur exactly once (no duplicates), and recommended or optional elements may occur at most once.
Response line HTTP/1.1
HTTP version.
500 Internal Server Error HTTP error code.
Headers
CONTENT-LANGUAGE
(No CONTENT-LANGUAGE header is used in control messages.) CONTENT-LENGTH
Required. Length of body in bytes. Integer.
CONTENT-TYPE
Required. Must be text/xml. Should include character coding used, e.g., utf-8.
DATE
Recommended. When response was generated. “rfc1123-date” as defined in RFC 2616.
EXT
Required. Confirms that the MAN header was understood. (Header only; no value.) SERVER
Required. Concatenation of OS name, OS version, UPnP/1.0, product name, and product version. String. Must accurately reflect the version number of the UPnP Device Architecture supported by the device. Control points must be prepared to accept a higher version number than the control point itself implements. For example, control points implementing UDA version 1.0 will be able to interoperate with devices implementing UDA version 1.1.
Body Envelope
Required element defined by SOAP. xmlns namespace attribute must be "http://schemas.xmlsoap.org/soap/envelope/".
Must include encodingStyle attribute with value "http://schemas.xmlsoap.org/soap/encoding/". Contains the following sub elements:
Body
Required element defined by SOAP. Should be qualified with SOAP namespace. Contains the following sub element:
Fault
Required element defined by SOAP. Why the service did not return a value for the variable. Should be qualified with SOAP namespace. Contains the following sub elements:
faultcode
Required element defined by SOAP. Value should be qualified with SOAP namespace.
Must be Client.
faultstring
Required element defined by SOAP. Generic UPnP string describing errorCode. See table immediately below for values.
detail
Required element defined by SOAP. Contains the following sub elements:
UPnPError
Required element defined by UPnP. Contains the following sub elements:
errorCode
Required element defined by UPnP. Code identifying what error was encountered. See table immediately below for values. Integer.
errorDescription
Recommended element defined by UPnP. Short description. See table immediately below for values. String. Recommend < 256 characters.
The following table summarizes defined error types and the corresponding value for the errorCode and errorDescription elements.
errorCode errorDescription Description 401 Invalid Action No action by that name at this service.
404 Invalid Var No state variable by that name at this service.
600-624 TBD Common action errors. Defined by UPnP Forum Technical Committee.
625-649 TBD Reserved for future use.
650-674 TBD Action-specific errors for standard actions. Defined by UPnP Forum working committee.
675-699 TBD Action-specific errors for non-standard actions. Defined by UPnP vendor.
The device shall return the error code 401 Invalid Action if the QueryStateVariable action is not implemented.
For future extensibility, devices and control points must ignore (a) any unknown elements and their sub elements or content, and (b) any unknown attributes and their values.
3.4 Control references