关于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.