关于UPnP Device Architecture 2.0的阅读笔记(十三)

设备控制

控制相关协议

    为触发动作或获取状态变量,控制点(设备)使用一系列的协议栈来完成数据传输.     消息使用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. &,<>)的,应该使用别名(&amp &lt)代替

    动作错误响应

    处理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.