Description: Service description

2. Description

2.3 Description: Service description

The UPnP description for a service defines actions and their arguments, and state variables and their data type, range, and event characteristics.

Each service may have zero or more actions. Each action may have zero or more arguments. Any combination of these arguments may be input or output parameters. If an action has one or more output arguments, one these arguments may be marked as a return value. Each argument should correspond to a state variable. This direct-manipulation programming model reinforces simplicity.

Each service must have one or more state variables.

In addition to defining non-standard services, UPnP vendors may add actions and services to standard devices, and may embed standard services and devices in non-standard devices.

To illustrate these points, below is a listing with placeholders (in italics) for actual elements and values. For a standard UPnP service, some of these placeholders would be defined by a UPnP Forum working committee (colored red) or specified by a UPnP vendor (purple). For a non-standard service, all of these placeholders would be specified by a UPnP vendor. (Elements defined by the UPnP Device Architecture are colored green for later reference.) Immediately following the listing is a detailed explanation of the elements, attributes, and values.

<?xml version="1.0"?>

</specVersion>

<name>actionName</name>

<name>formalParameterName</name>

<relatedStateVariable>stateVariableName</relatedStateVariable>

</argument>

Declarations for other arguments defined by UPnP Forum working committee (if any) go here

</argumentList>

</action>

Declarations for other actions defined by UPnP Forum working committee (if any) go here

Declarations for other actions added by UPnP vendor (if any) go here </actionList>

<name>variableName</name>

<dataType>variable data type</dataType>

<defaultValue>default value</defaultValue>

<allowedValue>enumerated value</allowedValue>

Other allowed values defined by UPnP Forum working committee (if any) go here </allowedValueList>

</stateVariable>

<name>variableName</name>

<dataType>variable data type</dataType>

<defaultValue>default value</defaultValue>

<minimum>minimum value</minimum>

<step>increment value</step>

</allowedValueRange>

</stateVariable>

Declarations for other state variables defined by UPnP Forum working committee (if any) go here

Declarations for other state variables added by UPnP vendor (if any) go here </serviceStateTable>

</scpd>

Listed below are details for each of the elements, attributes, and values appearing in the listing above. All elements and attributes (including action, argument, and state variable 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.

xml

Required for all XML documents. Case sensitive.

scpd

Required. Must have urn:schemas-upnp-org:service-1-0 as the value for the xmlns attribute; this references the UPnP Template Language (explained below). Case sensitive. Contains all other elements describing the service, i.e., contains the following sub elements:

specVersion

Required. Contains the following sub elements:

major

Required. Major version of the UPnP Device Architecture. Must be 1.

minor

Required. Minor version of the UPnP Device Architecture. Must be 0 in devices that implement UDA version 1.0. 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.

actionList

Required if and only if the service has actions. (Each service may have >= 0 actions.) Contains the following sub element(s):

action

Required. Repeat once for each action defined by a UPnP Forum working committee. If UPnP vendor differentiates service by adding additional actions, repeat once for each additional action.

Contains the following sub elements:

name

Required. Name of action. Must not contain a hyphen character (-, 2D Hex in UTF-8) nor a hash character (#, 23 Hex in UTF-8). Case sensitive. First character must be a USASCII letter (A-Z, a-z), USASCII digit (0-9), an underscore ("_"), or a non-experimental Unicode letter or digit greater than U+007F. Succeeding characters must be a USASCII letter (A-Z, a-z), USASCII digit (0-9), an underscore ("_"), a period ("."), a Unicode combiningchar, an extender, or a non-experimental Unicode letter or digit greater than U+007F. The first three letters must not be "XML" in any combination of case.

• For standard actions defined by a UPnP Forum working committee, must not begin with X_ nor A_.

• For non-standard actions specified by a UPnP vendor and added to a standard service, must begin with X_.

String. Should be < 32 characters.

argumentList

Required if and only if parameters are defined for action. (Each action may have >= 0 parameters.) Contains the following sub element(s):

argument

Required. Repeat once for each parameter. Contains the following sub elements:

name

Required. Name of formal parameter. Should be name of a state variable that models an effect the action causes. Must not contain a hyphen character (-, 2D

Hex in UTF-8). First character must be a USASCII letter (A-Z, a-z), USASCII digit (0-9), an underscore ("_"), or a non-experimental Unicode letter or digit greater than U+007F. Succeeding characters must be a USASCII letter (A-Z, a-z), USASCII digit (0-9), an underscore ("_"), a period ("."), a Unicode combiningchar, an extender, or a non-experimental Unicode letter or digit greater than U+007F.

The first three letters must not be "XML" in any combination of case.String.

Case sensitive. Should be < 32 characters.

direction

Required. Whether argument is an input or output parameter. Must be in xor out. Any in arguments must be listed before any out arguments.

retval

Optional. Identifies at most one out argument as the return value. If included, must be the first out argument. (Element only; no value.)

relatedStateVariable

Required. Must be the name of a state variable. Case Sensitive. Defines the type of the argument; see further explanation below.

serviceStateTable

Required. (Each service must have > 0 state variables.) Contains the following sub element(s):

stateVariable

Required. Repeat once for each state variable defined by a UPnP Forum working committee. If UPnP vendor differentiates service by adding additional state variables, repeat once for each additional variable. sendEvents attribute defines whether event messages will be generated when the value of this state variable changes; non-evented state variables have sendEvents="no";

default is sendEvents="yes". Contains the following sub elements:

name

Required. Name of state variable. Must not contain a hyphen character (-, 2D Hex in UTF-8). First character must be a USASCII letter (A-Z, a-z), USASCII digit (0-9), an underscore ("_"), or a non-experimental Unicode letter or digit greater than U+007F. Succeeding characters must be a USASCII letter (A-Z, a-z), USASCII digit (0-9), an underscore ("_"), a period ("."), a Unicode combiningchar, an extender, or a non-experimental Unicode letter or digit greater than U+007F. The first three letters must not be "XML" in any combination of case. Case sensitive.

• For standard variables defined by a UPnP Forum working committee, must not begin with X_ nor A_.

• For non-standard variables specified by a UPnP vendor and added to a standard service, must begin with X_.

String. Should be < 32 characters.

dataType

Required. Same as data types defined by XML Schema, Part 2: Datatypes. Defined by a UPnP Forum working committee for standard state variables; specified by UPnP vendor for extensions. Must be one of the following values:

ui1

Unsigned 1 Byte int. Same format as int without leading sign.

ui2

Unsigned 2 Byte int. Same format as int without leading sign.

ui4

Unsigned 4 Byte int. Same format as int without leading sign.

1 Byte int. Same format as int.

2 Byte int. Same format as int.

i4 4 Byte int. Same format as int. Must be between -2147483648 and 2147483647.

int

Fixed point, integer number. May have leading sign. May have leading zeros.

(No currency symbol.) (No grouping of digits to the left of the decimal, e.g., no commas.)

r4 4 Byte float. Same format as float. Must be between 3.40282347E+38 to 1.17549435E-38.

r8 8 Byte float. Same format as float. Must be between -1.79769313486232E308

4.94065645841247E-324 and 1.79769313486232E308 for positive values, i.e., IEEE 64-bit (8-Byte) double.

number Same as r8.

fixed.14.4

Same as r8 but no more than 14 digits to the left of the decimal point and no more than 4 to the right.

float

Floating point number. Mantissa (left of the decimal) and/or exponent may have a leading sign. Mantissa and/or exponent may have leading zeros. Decimal character in mantissa is a period, i.e., whole digits in mantissa separated from fractional digits by period. Mantissa separated from exponent by E. (No currency symbol.) (No grouping of digits in the mantissa, e.g., no commas.) char

Unicode string. One character long.

string

Unicode string. No limit on length.

date

Date in a subset of ISO 8601 format without time data.

dateTime

Date in ISO 8601 format with optional time but no time zone.

dateTime.tz

Date in ISO 8601 format with optional time and optional time zone.

time

Time in a subset of ISO 8601 format with no date and no time zone.

time.tz

Time in a subset of ISO 8601 format with optional time zone but no date.

boolean

“0” for false or “1” for true. The values “true”, “yes”, “false”, or “no” may also be used but are not recommended.

bin.base64

MIME-style Base64 encoded binary BLOB. Takes 3 Bytes, splits them into 4 parts, and maps each 6 bit piece to an octet. (3 octets are encoded as 4.) No limit on size.

bin.hex

Hexadecimal digits representing octets. Treats each nibble as a hex digit and encodes as a separate Byte. (1 octet is encoded as 2.) No limit on size.

uri

Universal Resource Identifier.

uuid

Universally Unique ID. Hexadecimal digits representing octets. Optional embedded hyphens are ignored.

defaultValue

Recommended. Expected, initial value. Defined by a UPnP Forum working committee or delegated to UPnP vendor. Must match data type. Must satisfy allowedValueList or allowedValueRange constraints.

allowedValueList

Recommended. Enumerates legal string values. Prohibited for data types other than string. At most one of allowedValueRange and allowedValueList may be specified. Sub elements are ordered (e.g., see NEXT_STRING_BOUNDED). Contains the following sub elements:

allowedValue

Required. A legal value for a string variable. Defined by a UPnP Forum working committee for standard state variables; specified by UPnP vendor for extensions. string. Must be < 32 characters.

allowedValueRange

Recommended. Defines bounds for legal numeric values; defines resolution for numeric values. Defined only for numeric data types. At most one of allowedValueRange and allowedValueList may be specified. Contains the following sub elements:

minimum

Required. Inclusive lower bound. Defined by a UPnP Forum working committee or delegated to UPnP vendor. Single numeric value.

maximum

Required. Inclusive upper bound. Defined by a UPnP Forum working committee or delegated to UPnP vendor. Single numeric value.

step

Recommended. Size of an increment operation, i.e., value of s in the operation v = v + s. Defined by a UPnP Forum working committee or delegated to UPnP vendor. Single numeric value.

The relatedStateVariable element of an argument definition must be the name of a state variable defined in the same service description. relatedStateVariable defines the type of the argument; there is not necessarily any semantic relationship between an argument and the relatedStateVariable used to define its type. relatedStateVariable must specify the name of a

stateVariable in the serviceStateTable which has the same dataType, allowedValueList, and allowedValueRange as the argument. If no stateVariable exists with an appropriate definition, the working committee (or vendor) must define an additional state variable for that purpose; state variables which are defined solely for the purpose of describing the type of an argument should have a name that includes the prefix “A_ARG_TYPE_”.

The allowedValueList and allowedValueRange elements may be used to indicate optional device capabilities. Working committees may require all values in the list or range to be supported by all vendors (no options), require a minimum subset with additional values being optional, or allow vendors to entirely decide which portions or the list or range to support. Vendors may add additional, vendor-specific values to the allowedValueList by using the “X_” prefix on the vendor-defined allowedValues, if permitted by working committees. However, it should be noted that greater flexibility in optional capabilities reduces the number of values that control points can depend on to be present, with corresponding impacts on interoperability. If device capabilities are expected to change during device operation, working committees should define separate actions to detect device capabilities rather than embedding capabilities information in the service description, because the latter requires cancellation of advertisements and readvertisement each time the service description document is changed. If the service description is used to convey capabilities information, the device must omit from the service description any optional elements (actions, allowedValues, etc.) that are not implemented.

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 embedded in UPnP device and service descriptions that they do not understand.

UPnP service descriptions shall be encoded using UTF-8.

When the value of any text element or attribute 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.Note that it is logically possible for a service to have no actions but have state variables and eventing; though unlikely, such a service would be an autonomous information source. However, a service with no state variables is prohibited.

Unlike device descriptions, service descriptions and associated values should not use locale-specific values; this includes service descriptions, values of action arguments, and values of state variables. Instead, most action arguments and state variables should

standard form into the correct language and/or format for the locale. For example, dates are represented in a locale-independent format (ISO 8601), and integers are represented without locale-specific formatting (e.g., no currency symbol, no grouping of digits). String values should be represented in either a standard 'locale' or in a locale-independent manner. Variables with an allowedValueList should use token values in the language of UPnP standards and not reflect strings intended to be displayed in a localized user interface.

However, there may be some cases where an action's behavior is locale-dependent. In this case, an argument should be defined to indicate the locale, perhaps using the same encoding as the ACCEPT-LANGUAGE and CONTENT-LANGUAGE headers (RFC 1766).

If there are multiple locale-dependent actions, the service may include an action to set a state variable to indicate the locale and eliminate the need to pass a locale identifier separately to each action.

Services standardized by UPnP Forum working committees have an integer version. Every later version of a service must be a superset of the previous version, i.e., it must include all actions and state variables exactly as they are defined by earlier versions of the service. The UPnP service type remains the same across all versions of a service whereas the service version must be larger for later versions. Versions of device and service templates may have non-integer versions (such as “0.9”) during development in the working committee, but this must become an integer upon standardization. Devices and services may have a version number greater than the major version number of the architecture they are designed for (e.g., “Power:2” may be designed to work on UDA version 1.0).

在文檔中 UPnP Forum ...1 (頁 33-39)