设备控制
控制相关协议
为触发动作或获取状态变量,控制点(设备)使用一系列的协议栈来完成数据传输.消息使用SOAP(简单对象访问协议)消息头和消息体来格式化.
UPnP支持SOAP1.1,所有的设备和控制点应该支持SOAP1.1的所有必须(Mandatory)的特点
动作
控制点允许触发设备服务的动作,并接收动作结果或返回错误.这些动作,结果,错误以SOAP格式封装,通过HTTP请求或响应来发送.动作触发(请求)
SOAP定义了XML和HTTP在RPC(远程过程调用)中的使用.UPnP2.0使用HTTP来发送SOAP1.1封装的控制消息给设备,并返回给控制点结果或错误信息.UPnP反对使用HTTP Extension Framework(RFC2774)来进行控制.具体而言就是,一个控制点应该发送一个以POST方法开头的请求而非M-POST,设备不应该以"405 Method Not Allowed"状态码拒绝POST方法请求因为这会使UPnP1.0版的CP发送一个M-POST请求.
下面是两种CP发送的动作请求的格式
1)使用CONTENT-LENGTH头信息的触发动作消息(HTTP/1.0和HTTP1.1)
POST path control URL HTTP/1.0 ##请求行,POST为HTTP方法
HOST: hostname:portNumber ##头信息
CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
USER-AGENT: OS/version UPnP/2.0 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>
2)使用分块编码的触发动作消息(仅支持HTTP/1.1)
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/2.0 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
动作响应
服务应该完成动作触发并在30秒内进行响应.如果一个动作的完成时间超过这个,应该提前返回并在完成时发送一个事件.如果服务在这段时间内失败,控制点应该怎么做由具体的应用程序决定.
响应消息的具体格式:
1)使用CONTENT-LENGTH头信息(HTTP/1.0或HTTP/1.1)
HTTP/1.0 200 OK
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated
SERVER: OS/version UPnP/2.0 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>
2)使用分块编码的响应(仅HTTP/1.1)
HTTP/1.1 200 OK
TRANSFER-ENCODING: "chunked"
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated
SERVER: OS/version UPnP/2.0 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
UPnP动作Schema
UPnP动作Schema定义了动作请求和动作响应的消息体中的数据类型和结构.
它在UPnP服务模版中定义.
建议和额外的要求
控制点和设备应该忽略掉接收到的所有其不识别的XML内容或者XML指令
XML名字空间前缀可以任意,只要遵循基本的XML名字空间机制.
对于不含值的XML标签,写成封闭形式.
对于值中含有保留的标签符号(e.g. &,<>)的,应该使用别名(& <)代替
动作错误响应
处理SOAP消息过程会产生一个正常的输出响应,但也会产生一个SOAP Fault.
动作输出参数应该仅仅被用来发送数据而不能用于传递错误信息.
出错响应应该使用下面的格式被发送:
1)使用CONTENT_LENGTH的响应消息
HTTP/1.0 500 Internal Server Error
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated
SERVER: OS/version UPnP/2.0 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>
2)使用分块编码的错误响应(仅HTTP/1.1)
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/2.0 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
UPnP出错Schema
UPnP出错Schema定义了出错响应消息中使用到的数据结构和类型.
与设备Schema和描述Schema类似,都采用XML语法并遵循XML Schema的规则.
获取变量
获取状态变量(QueryStateVariable)动作已经被UPnP论坛弃用,不应该将它用于控制点.
当需要使用这个功能时,应该先式地定义一个获取状态变量的动作.
参考
RFC 1123, 时间日期格式: http://www/ietf.org/rfc/rfc1123.txt.
RFC 2616, HTTP: Hypertext Transfer Protocol 1.1 : http://www.ietf.org/rfc/rfc2616.txt.
RFC 2774, HTTP Extension Framework : http://www.ietf.org/rfc/rfc2774.txt.
RFC 3986, Uniform Resource Identifiers (URI): Generic Syntax.Available at: http://www.ietf.org/rfc/rfc3986.txt.
SOAP, Simple Object Access Protocol : http://www.w3.org/TR/2000/NOTE-SOAP-20000508.
XML, Extensible Markup Language : http://www.w3.org/XML.
XML Schema (Part 1: Structures, Part 2: Datatypes) : http://www.w3.org/TR/xmlschema-1, http://www.w3.org/TR/xmlschema-2.