• 沒有找到結果。

Control: Action

在文檔中 UPnP Forum ...1 (頁 50-57)

3. Control

3.2 Control: Action

Control points may invoke actions on a device's services and receive results or errors back. The action, results, and errors are encapsulated in SOAP, sent via HTTP requests, and received via HTTP responses.

3.2.1 Control: Action: Invoke

The Simple Object Access Protocol (SOAP) defines the use of XML and HTTP for remote procedure calls. UDA uses SOAP to deliver control messages to devices and return results or errors back to control points.

SOAP defines additional HTTP headers, and to ensure that these are not confused with other HTTP extensions, SOAP follows the HTTP Extension Framework (RFC 2774) and specifies a SOAP-unique URI in the MAN header and prefixes the HTTP method with M-.

In this case, the method is M-POST. Using M-POST requires the HTTP server to find and understand the SOAP-unique URI and SOAP-specific headers.

To provide firewalls and proxies greater administrative flexibility, SOAP specifies that requests must first be attempted without the MAN header or M- prefix. If the request is rejected with a response of "405 Method Not Allowed", then a second request must be sent using the MAN header and M-prefix. If that request is rejected with a response of "501 Not Implemented" or "510 Not Extended", the request fails. (Other HTTP responses should be processed according to the HTTP specification.)

Below is a listing of a control message sent using the POST method (without the MAN header) followed by an explanation of the headers and body. This is immediately followed by a listing of a control message sent using the M-POST method and MAN header.

To invoke an action on a device's service, a control point must send a request with method POST 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: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>

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 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, which must be “utf-8”.

MAN

(No MAN header in request with method POST.) SOAPACTION

Required header defined by SOAP. Must be the service type, hash mark, and name of action to be invoked, all enclosed in double quotes. If used in a request with method M-POST, header name must be qualified with HTTP name space defined in MAN header. Single URI. The specified service version MUST indicate the version of the service that the control point wants to use while invoking the action. Its value may be any version of the service type in which the specified action was defined.

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:

actionName

Required. Name of element is name of action to invoke. xmlns namespace attribute must be the service type enclosed in double quotes; the version specified must be the same version specified in the SOAPACTION header. Case sensitive. Must be the first sub element of Body. Contains the following, ordered sub element(s):

argumentName

Required if and only if action has in arguments. Value to be passed to action. Repeat once for each in argument. (Element name not qualified by a namespace; element nesting context is sufficient.) Case sensitive. Single data type as defined by UPnP service description. Every “in”

argument in the definition of the action in the service description must be included, in the same order as specified in the service description (SCPD) that was downloaded from the device.

If the CONTENT-TYPE header specifies an unsupported value (other then “text/xml”) the device must return an HTTP status code

“415 Unsupported Media Type”.

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.

Devices and control points 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; devices must accept requests that use other legal XML namespace prefixes.

If an action has no “in” arguments, it is valid to combine the opening and closing XML tags (e.g., “<actionname/>” instead of

“<actionname></actionname>”).

When the value of any argument 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 “&amp;” or “&lt;”). Such characters appearing in URLs may also be escaped in accordance with the URL escaping rules specified in Section 2.4 of RFC 2396.

Note that because HTTP 1.1 allows use of chunked encoding, some control points may send the action request using chunked encoding if the POST method header specifies HTTP 1.1. Device implementations that do not support receiving action requests using chunked encoding should return a 505 HTTP Version Not Supported error.

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 in the following format. Values in italics are placeholders for actual values.

M-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"

MAN: "http://schemas.xmlsoap.org/soap/envelope/"; ns=01

01-SOAPACTION: "urn:schemas-upnp-org:service:serviceType:v#actionName"

(Message body for request with method M-POST is the same as body for request with method POST. See above.)

Request line M-POST

Method defined by HTTP Extension Framework (RFC 2774).

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, which must be “utf-8”.

MAN

Required. Must be "http://schemas.xmlsoap.org/soap/envelope/". ns directive defines namespace (e.g., 01) for other SOAP headers (e.g., SOAPACTION).

SOAPACTION

Required header defined by SOAP. Must be the service type, hash mark, and name of action to be invoked, all enclosed in double quotes. The specified service version MUST indicate the version of the service that the control point wants to use while invoking the action. Its value may be any version of the service type in which the specified action was defined. If used in a request with method M-POST, header name must be qualified with HTTP name space defined in MAN header. Single URI.

3.2.2 Control: Action: Response

The service must complete invoking the action and respond within 30 seconds, including expected transmission time (measured from the time the action message is transmitted until the time the associated response is received). Actions that take longer than this should be defined to return early and send an event when complete. 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 <?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>

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, which must be “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 minor version number (but the same major 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:

actionNameResponse

Required. Name of element is action name prepended to Response. xmlns namespace attribute must be service type enclosed in double quotes; the version specified must be the same version specified in the SOAPACTION header in the original invocation request. Case sensitive. Must be the first sub element of Body. Contains the following sub element:

argumentName

Required if and only if action has out arguments. Value returned from action. Repeat once for each out argument. If action has an argument marked as retval, this argument must be the first element. (Element name not qualified by a namespace; element nesting context is sufficient.) Case sensitive. Single data type as defined by UPnP service description. Every “out” argument in the definition of the action in the service description must be included, in the same order as specified in the service description (SCPD) available from the device.

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.

If an action has no “out” arguments, it is valid to combine the opening and closing XML tags (e.g., “<actionnameResponse/>”

instead of “<actionnameResponse></actionnameResponse>”).

When the value of any argument 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 “&amp;” or “&lt;”). 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 a control point uses an HTTP/1.0 binding on a SOAP request without setting the KeepAlive token, the Device MUST close the socket after responding. If a control point uses an HTTP/1.1 binding on a SOAP request, and sets the Connection: CLOSE token, the Device MUST close the socket after responding.

Note that because HTTP 1.1 allows use of chunked encoding, some devices may send the action response using chunked encoding if the POST request specifies HTTP 1.1. It is therefore recommended that all implementations that include HTTP 1.1 in the POST request support receiving chunked encoding.

If the service encounters an error while invoking the action sent by a control point, the service must send a response within 30 seconds, including expected transmission time. Out arguments must not be used to convey error information; out arguments must only be used to return data; error responses 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 <?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>

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, which must be “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. Error encountered while invoking action. Should be qualified with SOAP namespace. Contains the following sub elements:

faultcode

Required element defined by SOAP. Value must be qualified with the SOAP namespace. Must be Client.

faultstring

Required element defined by SOAP. Must be UPnPError.

detail

Required element defined by SOAP. Contains the following subelement:

UPnPError

Required element defined by UDA. Contains the following subelements:

errorCode

Required element defined by UDA. Code identifying what error was encountered. See table immediately below for values. Integer.

errorDescription

Recommended element defined by UDA. Short description. See table immediately below for recommended values; other values may be used by vendors. Human-readable 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.

402 Invalid Args Could be any of the following: not enough in args, too many in args, no in arg by that name, one or more in args are of the wrong data type.

403 (Do Not Use) (This code has been deprecated.)

501 Action Failed May be returned in current state of service prevents invoking that action.

600 Argument Value Invalid The argument value is invalid

601 Argument Value Out of Range An argument value is less than the minimum or more than the maximum value of the allowedValueRange, or is not in the allowedValueList.

602 Optional Action Not Implemented The requested action is optional and is not implemented by the device.

603 Out of Memory The device does not have sufficient memory available to complete the action.

This may be a temporary condition; the control point may choose to retry the unmodified request again later and it may succeed if memory is available.

604 Human Intervention Required The device has encountered an error condition which it cannot resolve itself and required human intervention such as a reset or power cycle. See the device display or documentation for further guidance.

605 String Argument Too Long A string argument is too long for the device to handle properly.

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.

在文檔中 UPnP Forum ...1 (頁 50-57)

相關文件