DCP Specification
An Internet of Things Protocol

DCP - An Internet of Things Protocol - Chris Armbruster

Welcome to the Device Control Protocol (DCP), designed for the "Internet of Things" - interfacing everyday devices over networks.  This online reference is everything you will need to learn more and get started using the protocol.  It includes a complete hyperlinked specification and an XML Document Type Definition for controlling "things" and exchanging data between devices. 

Chris Armbruster
Creator

 



Network Devices

Abstract

The Device Control Protocol (DCP) is an application level protocol optimized for the integration, monitoring and control of devices or "things" on a network. It provides a framework for integrating unconventional network devices attached to networks directly, wirelessly or as computer periphery.  DCP is a generic, object-oriented protocol which supports connection and connectionless communication between resources. It employs an open ended set of methods for indicating the purpose of a request and builds on the discipline of reference provided by the Uniform Resource Identifier (URI), for indicating the object to which these methods are to be applied. By the typing and negotiation of device data representation, DCP allows applications and devices to be built independently of data representation while maintaining interoperability. It defines an extensible object model that enables the developer to expose objects, properties, methods, and events of a device. Plug-and-play characteristics may be implemented for devices through the reserved user interface and device driver objects. The Device Control Protocol has been designed to provide a natural and comfortable extension of the Internet to "things."

This reference assumes knowledge of the Transmission Control Protocol (TCP), the Universal Datagram Protocol (UDP), TCP/IP communications, and Object Oriented Programming (OOP).


Quick Tour of Features

The Device Control Protocol Reference includes the following features.

DCP Protocol Standard

The DCP Specification is a protocol standard, similar to an Internet RFC, which makes developing devices and applications that leverage this Internet-based device control technology simple.  It is a complete hyperlinked reference to the protocol.

XML Document Type Definition for DCP

The DCP XML DTD is an Extensible Markup Language Document Type Definition for DCP.  It is a hierarchical markup language that can be used to represent device states, properties and events.  Device object models may also be described with the DCP XML DTD.  The architecture of DCP exhibits the abstraction of device data from the protocol itself.  As such, use of this DTD with DCP is not required. All that is required is that the recipient of the representation be able to understand and process it. For your reference, the XML DTD is available here should you wish to use it.


Overview

DCP is a protocol designed for communication with and between network devices. While the File Transfer Protocol (FTP) was designed for transferring files and the Hypertext Transfer Protocol (HTTP) emphasizes the transfer of media, DCP focuses on controlling and monitoring devices connected to the Internet.  In the context of DCP, a device is any resource attached to a network and is not necessarily a terminal or network infrastructure equipment.  DCP is a protocol for controlling network devices and should not be compared with DCOM and CORBA, which are binary standards for network components.

DCP addresses the increasing demand for integrating non-traditional network devices by specifying a common language for devices to interoperate with each other, as well as Internet applications. It provides a protocol standard for devices that embed Internet technology and connect to networks directly in addition to devices that connect to networks as computer periphery.

Applications for DCP are endless, but here are a few examples:

    • Distributed security systems and security monitoring
    • Integration and control of factory production machinery
    • Remote data collection
    • Load shedding and remote metering for utility providers
    • Environmental control systems
    • Consumer electronics and home appliance integration
    • Device browsers that work with any DCP device
    • Applications that provide logic for a network of devices

The Device Control Protocol is a generic, object-oriented protocol which employs a session / transaction paradigm that may be implemented on both connection and connectionless communication between resources. The object-oriented features of DCP allow the protocol to be easily applied to real world objects, or devices. Since the protocol supports both connection and connectionless communication, it offers facilities for reliable and secure communication, as well as broadcast and light-weight messaging.

DCP is extensible and leverages existing Internet technology and standards. It employs an open-ended set of methods for indicating the purpose of a transaction request, allowing expansion methods to be added. The Device Control Protocol builds on the discipline of reference provided by the Uniform Resource Identifier (URI), for indicating the object to which methods are to be applied. DCP extends URI’s to include objects, properties, methods and events in a style that object oriented programmers are used to.

Although an XML document type definition for device data has been defined, use of the representation with DCP is not required. All that is required is that the recipient of the representation be able to understand and process it. The architecture of DCP exhibits the abstraction of device data from the protocol itself. By the typing and negotiation of device data representation, DCP allows applications and devices to be built independently of data representation while maintaining interoperability. This allows for the expansion of data representation types without changing the protocol, allowing developers to separate the transfer of data from the data itself. Since DCP negotiates device data representation, multiple representation types may be supported with ease.

The Device Control Protocol allows the developer to communicate with devices as if they were objects by specifying a core set of facilities which include:

  1. getting a device property
  2. setting a device property
  3. tethering to a device property
  4. calling a device method
  5. subscribing to a device event
  6. transmitting a device event
  7. administrating sessions with devices
  8. discovering the devices attached to a network

DCP further extends it capabilities through a collection of reserved objects.   Developers may expose properties, methods, and events of device through a reserved object model object. This allows applications and other devices to query and browse the capabilities of a device.  Plug and play characteristics may be implemented for DCP aware devices through the reserved user interface and device driver objects.  This allows user interfaces and device drivers to be embedded inside devices.   These reserved objects only specify exposition, negotiation and transfer of the objects.  Although the devices may be implemented with DCP, the technology chosen is at the discretion of the developer.

DCP provides a natural and comfortable extension of the Internet to devices. It has been designed to leverage the massive infrastructure, huge physical network, and large embedded base of software standards and knowledge associated with the Internet. It is also designed to offer an object-oriented approach to embedding the Internet in devices.   The result is a powerful, extensible protocol that allows developers to seamlessly connect devices to the Internet in a comfortable and simple fashion.


PURPOSE

The purpose of DCP is

  1. to enable remote control and monitoring of devices and applications on the Internet
  2. to promote the integration of non-traditional devices on networks
  3. to give network devices "plug-and-play" characteristics
  4. to encourage the development of distributed Internet applications and devices
  5. to shield a user from variations in specific protocols and interfaces for applications and devices

TERMINOLOGY

This resource uses a number of terms to refer to roles played by participants in and objects of DCP communication.  Several new terms and new contexts for existing terms are introduced.  It is recommended that even the seasoned Internet developer review the terms before proceeding to other areas of this reference.

Application -  a program or process attached to a network that is capable of DCP communication.  Throughout this reference, the terms "application", "device" and "resource" are used interchangeably.
Client -  a network resource that issues requests to a server.  In typical client/server environments, resources usually play one role or the other.  This is not the case for DCP.  In DCP, devices typically play roles as both clients and servers by issuing requests to other devices and servicing requests from other devices.   To avoid confusion in this resource, the term client will not be used when making reference to a DCP transaction.  Instead, the device initiating a transaction will be referred to as the initiator.  The term initiator is intended to only be used in the context of the DCP transaction that it is associated with.
Connection -  a transport layer virtual circuit established between two network resources for the purpose of communication.  In DCP, when the mode of service is connection-oriented, the initiator establishes a connection with the target before making a request.
Device -  a piece of physical equipment attached to a network that is capable of DCP communication.  A device is not limited to traditional network hardware (like terminals, switches and routers), but it includes unconventional network devices (like security systems, environmental control systems and factory machinery).  Throughout this reference, the terms "device", "application" and "resource" are used interchangeably.
Entity -  a particular representation or rendition of device data that may be enclosed within a request or response message. An entity consists of meta-information in the form of entity headers and content in the form of an entity body.
Host -  any resource on a network that provides services of any kind to other resources on the network and is qualified by a valid Internet host name or IP address.
Initiator -  refers to the device or application that initiates or starts a transaction with another DCP resource (the target).  In both open-loop and closed-loop transactions, the initiator is the resource that initiates the transaction by making a DCP request and the target is the resource that processes it.  In a client/server model, resources usually play a single messaging or processing role.   This is not the case for DCP, so the term client will not be used in this reference to avoid confusion.  Instead, the term initiator will be used and carry the meaning described above.  Since most DCP devices play multiple roles,  the term initiator only has meaning in the context of the transaction that it refers to.
Message -  the basic unit of DCP communication and consists of a structured sequence of octets matching the syntax defined in this resource and transmitted via a connection or datagram.  DCP transactions are made up of messages.  In DCP there are two types of messages, requests and responses.  DCP Messages have request or response lines, headers and bodies.
Mode of Service (MOS) -  the method used by a network to provide communication services between two processes.  In short, a mode of service specifies how a communication layer performs an operation.  DCP makes reference to two modes of service, connection-oriented and connectionless.  Connection-oriented services create a virtual circuit, which gives the illusion of a physical communication path or point-to-point connection.  To an application using a connection oriented mode of service, the communication channel appears to be a solid, unbroken path for communication.   A connection-oriented mode of service is similar to telephone communication.   A connectionless mode of service provides communication in the form of a delivery service.  In other words, a connectionless mode of service does not establish a point-to-point connection.  There is no illusion of a solid, unbroken communication path.  Communication takes place as a series of datagrams that are delivered by the network through potentially different paths and at varying rates.
Object Model -  a hierarchical object oriented structure that describes a resource's properties, methods and events.  It contains all the information necessary for having a DCP conversation with a resource.  An object model may be used to expose the accessible characteristics of a resource.
Request -a DCP request message.  DCP transactions are initiated by a request message being sent from the initiator to the target.
Resource -  a device, application program or process attached to a network that is capable of DCP communication.  Throughout this reference, the terms "resource", "device" and "application" are used interchangeably.
Response -  a DCP response message.  DCP closed-loop transactions are completed by a response message being sent from the target to the initiator.
Server -  a network resource that services requests from a client.  In typical client/server environments, resources usually play one role or the other.  This is not the case for DCP.  In DCP, devices typically play roles as both clients and servers by initiating transactions with other devices and processing transactions started by other devices.   To avoid confusion in this resource, the term server will not be used.  Instead, the device servicing a transaction will be referred to as the target.  This term is intended to only be used in the context of the DCP transaction that it is associated with.
Session -  a DCP conversation between two devices.  Once a session is opened, any combination of DCP transactions may take place.  Sessions apply to both connection-oriented and connectionless modes of service and should not be considered the same as a connection.  Sessions are identified by a session ID, not a TCP connection.
Target -  a resource that processes a DCP transaction initiated by another resource, known as the initiator.  In both open-loop and closed-loop transactions, the target processes transactions.  The target completes closed-loop transactions by sending a response message to the initiator.  In a client/server model, resources usually play a single messaging or processing role.  Since this is not the case for DCP, the term server will not be used in this reference to avoid confusion.  Instead, the term target will be used and carry the meaning described above.  Since most DCP devices play multiple roles,  the term target only has meaning in the context of the transaction that it refers to.
Tether -  a feature of DCP communication that allows a resource to bind itself to a property of another resource.  The DCP tether facilitates a continuous (as opposed to event driven) stream of property data from the target to the initiator.
Transaction -  a piece of DCP communication that occurs within a session.  Many transactions can occur within a single session.  Transactions may be of an open-loop or closed-loop nature.  Open-loop transactions consist of a DCP request message that is sent from an initiator to a target and the processing performed by the target to satisfy the request.  Closed-loop transactions are identical to open-loop transactions except that they also include a DCP response message sent from the target to the initiator to acknowledge the request and return device data when appropriate.

OVERALL OPERATION

The DCP protocol follows a session / transaction paradigm that may be implemented on both connection-oriented and connectionless modes of service.  A DCP conversation behaves as follows:

  1. An initiator resource opens a DCP session with a target resource.

  2. Any number of DCP transactions are performed within the session by either party.

  3. The DCP session is closed.

DCP sessions and transactions can be compared to a conversation between people.  A session is like an entire conversation and transactions are like statements (or questions and answers).  Just as many statements are made by both parties in a conversation, many transactions can be made by both participants in a single DCP session. 

Within a session, any combination of transactions can take place.   There are two general types of DCP transactions and each of these may occur in either direction:

  1. open-loop

  2. closed-loop

Open-loop transactions are one-way communication scenarios that are initiated by one resource and processed by another. They do not include a response.  A closed-loop transaction is a two-way communication scenario that, in addition to the message that initiates the transaction, includes a response.  DCP devices are likely to initiate and process both open-loop and closed-loop transactions.

In both open-loop and closed-loop transactions, a request is sent from an initiator resource to a target resource in the form of a request method, URI and protocol version followed by headers and a MIME-like message with possible body content.  For closed-loop transactions, a response follows in the form of a status line, including a protocol version and status code followed by headers and a MIME-like message with possible body content.  Message headers are used to communicate and negotiate content representation of the body, permitting DCP applications and devices to be built independently of data representation while maintaining interoperability. 

CONVENTIONS

All mechanisms in this reference are specified in both prose and an augmented Bakus-Naur Form (BNF) similar to that used by Internet RFC 822.  Implementers of DCP will need to be familiar with the BNF notation in order to understand this reference.  For convenience, this resource includes an overview of BNF that is sufficient for comprehending the DCP specification.


AUGMENTED BNF

The augmented BNF includes the following constructs:

name = definition :  The name of a rule is simply the name itself (without any enclosing "<" and ">") and is separated from its definition by the equal character "=". White space is only significant in that indentation of continuation lines is used to indicate a rule definition that spans more than one line. Certain basic rules are in a special style, such as sp, lws, ht, crlf, etc. Angle brackets are used within definitions whenever their presence will facilitate discerning the use of rule names.

Note: Contrary to some RFCs, this specification does not represent basic rules in all uppercase letters.  Rather, a special style is used as indicated above.
"literal" :  Quotation marks surround literal text. Unless stated otherwise, the text is case-insensitive.
rule1 | rule2 :  Elements separated by a bar ("|") are alternatives, e.g., "yes | no" will accept yes or no.
(rule1 rule2) :  Elements enclosed in parentheses are treated as a single element. Thus, "(elem (foo | bar) elem)" allows the token sequences "elem foo elem" and "elem bar elem".
*rule :  The character "*" preceding an element indicates repetition. The full form is "<n>*<m>element" indicating at least <n> and at most <m> occurrences of element. Default values are 0 and infinity so that "*(element)" allows any number, including zero; "1*element" requires at least one; and "1*2element" allows one or two.
[rule] :  Square brackets enclose optional elements; "[foo bar]" is equivalent to "*1(foo bar)".
n rule :  Specific repetition: "<n>(element)" is equivalent to "<n>*<n>(element)"; that is, exactly <n> occurrences of (element). Thus 2digit is a 2-digit number, and 3alpha is a string of three alphabetic characters.
#rule :  A construct "#" is defined, similar to "*", for defining lists of elements. The full form is "<n>#<m>element" indicating at least <n> and at most <m> elements, each separated by one or more commas (",") and optional linear white space (lws). This makes the usual form of lists very easy; a rule such as "( *lws element *( *lws "," *lws element ))" can be shown as "1#element". Wherever this construct is used, null elements are allowed, but do not contribute to the count of elements present. That is, "(element), , (element)" is permitted, but counts as only two elements. Therefore, where at least one element is required, at least one non-null element must be present. Default values are 0 and infinity so that "#(element)" allows any number, including zero; "1#element" requires at least one; and "1#2element" allows one or two.
; comment :  A semi-colon below, above or set off some distance to the right of rule text, starts a comment that continues to the end of line. This is a simple way of including useful notes in parallel with the specifications.

Note: This reference also includes comments in the same style as this paragraph preceded by "Note:" in this font-face and color rather than using the ";" indicator.
implied *lws :  The grammar described by this specification is word-based. Except where noted otherwise, linear white space (lws) can be included between any two adjacent words (token or quotedString), and between adjacent tokens and delimiters (tSpecials), without changing the interpretation of a field. At least one delimiter (tSpecials) must exist between any two tokens, since they would otherwise be interpreted as a single token. However, applications should attempt to follow "common form" when generating DCP constructs.

BASIC RULES

The following rules are used throughout this specification to describe basic parsing constructs. The US-ASCII coded character set is defined by ANSI X3.4-1986.

Syntax
octet = <any 8-bit sequence of data>
char = <any US-ASCII character (octets 0 - 127)>
upAlpha = <any US-ASCII uppercase letter "A".."Z">
loAlpha = <any US-ASCII lowercase letter "a".."z">
alpha = upAplha | loAlpha
digit = <any US-ASCII digit "0".."9">
ctl = <any US-ASCII control character (octets 0 - 31) and DEL (127)>
cr = <US-ASCII CR, carriage return (13)>
lf = <US-ASCII LF, linefeed (10)>
sp = <US-ASCII SP, space (32)>
ht = <US-ASCII HT, horizontal-tab (9)>
<"> = <US-ASCII double-quote mark (34)>
crlf = cr lf  

Note: DCP defines the octet sequence cr lf as the end-of-line marker for all protocol elements except the entity body.  The end-of-line marker within an entity body is defined by its associated media type.
lws = [crlf] 1*( sp | ht

Note: DCP headers may be folded onto multiple lines if each continuation line begins with a space or horizontal tab. All linear white space, including folding, has the same semantics as sp.  However, folding of header lines is not expected by some applications, and should not be generated by DCP applications.
text = <any octet except ctl, but including lws

Note: The text rule is only used for descriptive field contents and values that are not intended to be interpreted by the message parser. Words of *text may contain octets from character sets other than US-ASCII.  Recipients of header field text containing octets outside the US-ASCII character set may assume that they represent ISO-8859-1 characters.
hex = "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f" | digit
word = token | quotedString  

Note: Many DCP header field values consist of words separated by lws or special characters. These special characters must be in a quotedString to be used within a parameter value.
token = 1*<any char except ctl or tSpecials>
tSpecials = "(" | ")" | "<" | ">" | "@" | "," | ";" | ":" | "\" | <"> | "/" | "[" | "]" | "?" | "=" | "{" | "}" | sp | ht
comment = "(" *( cText | comment ) ")" 

Note: Comments may be included in some DCP header fields by surrounding the comment text with parentheses. Comments are only allowed in fields containing "comment" as part of their field value definition. In all other fields, parentheses are considered part of the field value.
cText = <any text excluding "(" and ")">
quotedString = ( <"> *(qdText) <">

Note: A string of text is parsed as a single word if it is quoted using double-quote marks.
qdText = <any char except <"> and ctl, but including lws>

Note: Single-character quoting using the backslash ("\") character is not permitted in DCP.

PROTOCOL PARAMETERS

The implementation of DCP involves various protocol parameters.  These include protocol versions, uniform resource identifiers, character sets, content codings, media types and product tokens. They will be described in this section.


PROTOCOL VERSIONS

DCP uses a "<major>.<minor>" numbering scheme to indicate versions of the protocol. The protocol versioning policy is intended to allow the sender to indicate the format of a message and its capacity for understanding further DCP communication, rather than the features obtained via that communication. No change is made to the version number for the addition of message components which do not affect communication behavior or which only add to extensible field values. The <minor> number is incremented when the changes made to the protocol add features which do not change the general message parsing algorithm, but which may add to the message semantics and imply additional capabilities of the sender. The <major> number is incremented when the format of a message within the protocol is changed.

The version of a DCP message is indicated by a dcpVersion field in the first line of the message. If the protocol version is not specified, the recipient must assume that the message is in the DCP/1.0 format.

Syntax
dcpVersion = "DCP" "/" 1*digit "." 1*digit

Note that the major and minor numbers should be treated as separate integers and that each may be incremented higher than a single digit. Thus, DCP/2.4 is a lower version than DCP/2.13, which in turn is lower than DCP/12.3. Leading zeros should be ignored by recipients and never generated by senders.

This reference defines the 1.0 version of the DCP protocol. DCP applications must include a dcpVersion of "DCP/1.0".

DCP/1.0 targets must:

  • recognize the format of the requestLine for DCP/1.0 requests;
  • understand any valid request in the format of DCP/1.0;
  • respond appropriately with a message in the same protocol version used by the initiator if a response is required.

DCP/1.0 initiators must:

  • recognize the format of the statusLine for DCP/1.0 responses;
  • understand any valid response in the format of DCP/1.0.

Proxy and gateway applications must be careful in forwarding requests that are received in a format different than that of the application's native DCP version. Since the protocol version indicates the protocol capability of the sender, a proxy/gateway must never send a message with a version indicator that is greater than its native version. If a higher version request is received, the proxy/gateway must either downgrade the request version or respond with an error. Requests with a version lower than that of the application's native format may be upgraded before being forwarded; the proxy/gateway's response to that request must follow the server requirements listed above.


UNIFORM RESOURCE IDENTIFIERS

URIs have been known by many names: WWW addresses, Universal Document Identifiers, Universal Resource Identifiers, and finally the combination of Uniform Resource Locators (URL) and Names (URN). URIs are simply formatted strings which identify, via name, location, object instance, property, method, event or any other characteristic, a network resource.  For Internet access protocols, it is necessary in most cases to define the encoding of the access algorithm into something concise enough to be termed address. URIs which refer to objects accessed via a specific Internet protocol, such as DCP, are known as Uniform Resource Locators (URLs).

GENERAL URI SEMANTICS

URIs in DCP can be represented in absolute form or relative to some known base URI, depending upon the context of their use. The two forms are differentiated by the fact that absolute URIs always begin with a scheme name followed by a colon.

Syntax
uri = ( absoluteUri | relativeUri ) [ "#" fragment ]
absoluteUri = scheme ":" *( uchar | reserved )
relativeUri = netPath | absPath | relPath
netPath = "//" netLoc [ absPath ]
absPath = "/" relPath
relPath = [ path ] [ ";" params ] [ "?" query ]
path = fSegment *( "/" segment )
fSegment = 1*pchar
segment = *pchar
params = param *( ";" param )
param = *( pchar | "/" )
scheme = 1*( alpha | digit | "+" | "-" | "." )
netLoc = *( pchar | ";" | "?" )
query = *( uchar | reserved )
fragment = *( uchar | reserved )
pchar = uchar | ":" | "@" | "&" | "=" | "+"
uchar = unreserved | escape
unreserved = alpha | digit | safe | extra | national
escape = "%" hex hex
reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+"
extra = "!" | "*" | "'" | "(" | ")" | ","
safe = "$" | "-" | "_" | "."
unsafe = ctl | sp | <"> | "#" | "%" | "<" | ">"
national = <any octet excluding alpha, digit, reserved, extra, safe, and unsafe>

For definitive information on URL syntax and semantics, see RFC 1738 and RFC 1808. The BNF above includes national characters not allowed in valid URLs as specified by RFC 1738, since DCP resources are not restricted in the set of unreserved characters allowed to represent the relPath part of addresses, and DCP proxies may receive requests for URIs not defined by RFC 1738.

DCP URL

The "DCP" scheme is used to locate network resources via the DCP protocol. This section defines the scheme-specific syntax and semantics for DCP URLs.

Syntax
dcpUrl = dcpScheme ":" "//" host [":" port] [absDcpPath]
dcpScheme = "dcp" | "dcpu" | "dcps"

Note: The scheme "dcp" requires that commands are issued via a reliable or connection-oriented protocol (within the Internet, TCP), while the scheme "dcpu" identifies an unreliable or connectionless protocol (within the Internet, UDP). The scheme "dcps" indicates that a TCP connection secured by TLS must be used.
host = <A legal Internet host domain name or IP address (in dotted-decimal form), as defined by RFC 1123>
port = *digit
absDcpPath = "/" relDcpPath
relDcpPath = objectPath
objectPath = ["/" objectSegment *("." objectSegment)] ["." objectMember]
objectSegment = objectName ["(" handle ")"]

Note: An object is an exposed resource of a host or parent object that can have properties, methods, events and child objects.
objectName = ["*"] 1*( alpha | digit )
handle = argList

Note: A handle is a set of instantiation properties pertaining to an object that specifies the instance of the object.
argList = attribute "=" [value] *("," attribute "=" [value])
attribute = 1*( alpha | digit )
value = token | quotedString
objectMember = property | method | event
property = 1*( alpha | digit ) ["=" [value]] 

Note: A property is one piece of object data exposed by the object model that may be read and optionally written. Objects may have many properties.
method = 1*( alpha | digit ) "(" [argList] ")"

Note: A method is a process that may be invoked and applied against the object of which it is a member.  Objects may have many methods.

event = 1*( alpha | digit )

Note: An event is the occurrence of a meaningful predefined device incident.  Objects may have many events.

If the port is empty or not given, port 2500 is assumed. The semantics are that the identified resource is located at the target listening for TCP connections and UDP messages on that port of that host, and the dcpRequestUri for the resource is absDcpPath. If the absDcpPath is not present in the URL, it must be given as "/" when used as a dcpRequestUri.

Note: Although the DCP protocol is independent of the transport layer protocol, the DCP URL only identifies resources by their TCP location, and thus non-TCP resources must be identified by some other URI scheme.

The canonical form for "DCP" URLs is obtained by converting any upAlpha characters in host to their loAlpha equivalent (hostnames are case-insensitive), eliding the [ ":" port] if the port is 2500, and replacing an empty absDcpPath with "/".

DATE AND TIME FORMATS

DCP/1.0 applications allow three different formats for the representation of date/time stamps: RFC 1123 Date, RFC 850 Date and ANSI C Time Date.

Examples
Sun, 06 Nov 1994 08:49:37 GMT
Note: RFC 1123 Format
 
Sunday, 06-Nov-94 08:49:37 GMT
Note: RFC 1036 Format
 
Sun Nov 6 08:49:37 1994
Note: ANSI C (asctime) Format

The first format is preferred as an Internet standard and represents a fixed-length subset of that defined by RFC 1123. The second format is in common use, but is based on the obsolete RFC 850 date format and lacks a four-digit year. DCP/1.0 initiators and targets that parse the date value should accept all three formats, though they must never generate the third (ANSI C) format.

Note: Recipients of date values are encouraged to be robust in accepting date values that may have been generated by non-DCP applications.

All DCP/1.0 date/time stamps must be represented in Universal Time (UT), also known as Greenwich Mean Time (GMT), without exception. This is indicated in the first two formats by the inclusion of "GMT" as the three-letter abbreviation for time zone, and should be assumed when reading the ANSI C format.

Syntax
dcpDate = rfc1123Date | rfc850Date | ascTime
rfc1123Date = wkDay "," sp date1 sp time sp "GMT"
rfc850Date = weekDay "," sp date2 sp time sp "GMT"
ascTime = wkDay sp date3 sp time sp 4digit
date1 = 2digit sp month sp 4digit
Note: day month year
date2 = 2digit "-" month "-" 2digit
Note: day-month-year
date3 = month sp ( 2digit | ( SP 1digit ))
Note month day
time = 2digit ":" 2digit ":" 2digit 
Note: 00:00:00 - 23:59:59
wkDay = "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" | "Sun"
weekDay "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday"
month "Jan" | "Feb" | "Mar" | "Apr" | "May" | "Jun" | "Jul" | "Aug" | "Sep" | "Oct" | "Nov" | "Dec"
Note: DCP requirements for the date/time stamp format apply only to their usage within the protocol stream. Initiators and targets are not required to use these formats for user presentation, request logging, etc.

CHARACTER SETS

DCP uses the same definition of the term "character set" as that described for MIME.  The term "character set" is used in this reference to refer to a method used with one or more tables to convert a sequence of octets into a sequence of characters. Note that unconditional conversion in the other direction is not required, in that not all characters may be available in a given character set and a character set may provide more than one sequence of octets to represent a particular character. This definition is intended to allow various types of character encodings, from simple single-table mappings such as US-ASCII to complex table switching methods such as those that use ISO 2022's techniques. However, the definition associated with a MIME character set name must fully specify the mapping to be performed from octets to characters. In particular, use of external profiling information to determine the exact mapping is not permitted.

Note: This use of the term "character set" is more commonly referred to as a "character encoding."  However, DCP shares the same terminology as MIME.

DCP character sets are identified by case-insensitive tokens. The IANA Character Set registry defines the complete set of tokens. However, because that registry does not define a single, consistent token for each character set, the DCP preferred names for those character sets most likely to be used with DCP entities are defined here. These character sets include those registered by RFC 1521 (the US-ASCII and ISO-8859 character sets) and other names specifically recommended for use within MIME charSet parameters.

Syntax
charSet = "US-ASCII" | "ISO-8859-1" | "ISO-8859-2" | "ISO-8859-3" | "ISO-8859-4" | "ISO-8859-5" | "ISO-8859-6" | "ISO-8859-7" | "ISO-8859-8" | "ISO-8859-9" | "ISO-2022-JP" | "ISO-2022-JP-2" | "ISO-2022-KR" | "UNICODE-1-1" | "UNICODE-1-1-UTF-7" | "UNICODE-1-1-UTF-8" | token

Although DCP allows an arbitrary token to be used as a charSet value, any token that has a predefined value within the IANA Character Set registry must represent the character set defined by that registry. Applications should limit their use of character sets to those defined by the IANA registry.

The character set of an entity body should be labeled as the lowest common denominator of the character codes used within that body, with the exception that no label is preferred over the labels US-ASCII or ISO-8859-1.


CONTENT CODINGS

Content coding values are used to indicate an encoding transformation that has been applied to a resource data. Content codings are primarily used to allow information to be compressed or encrypted without losing the identity of its underlying media type. 

Syntax
contentCoding = "x-gzip" | "x-compress" | token

Note: DCP applications should consider "gzip" and "compress" to be equivalent to "x-gzip" and "x-compress", respectively.

All content-coding values are case-insensitive. DCP uses contentCoding values in the Content-Encoding header field. Although the value describes the content-coding, what is more important is that it indicates what decoding mechanism will be required to remove the encoding. Note that a single program may be capable of decoding multiple content-coding formats. Values specified by this reference are defined below.

 Definitions
x-gzip -  an encoding format produced by the file compression program "gzip" (GNU zip) developed by Jean-loup Gailly. This format is typically a Lempel-Ziv coding (LZ77) with a 32 bit CRC.
x-compress -  The encoding format produced by the file compression program "compress". This format is an adaptive Lempel-Ziv-Welch coding (LZW).

Note: Use of program names for the identification of encoding formats is not desirable and should be discouraged for future encodings. Their use here is representative of historical practice, not good design.


MEDIA TYPES

DCP uses Internet Media Types in the Content-Type header field in order to provide open and extensible data typing.

Syntax

The mainType, subType, and pAttribute terms are case-insensitive. The pValue term may or may not be case-sensitive, depending on the semantics of the parameter name.  lws must not be generated between the mainType and subType, or between a pAttribute and its pValue. Upon receipt of a mediaType with an unrecognized pAttribute, the mediaType should be treated as if the unrecognized pAttribute and its pValue were not present.

Note: Media type values are registered with the Internet Assigned Number Authority (IANA). The media type registration process is outlined in RFC 1590. Use of non-registered media types is discouraged.

CANONICALIZATION

Internet media types are registered with a canonical form. In general, an entity body transferred via DCP must be represented in the appropriate canonical form prior to its transmission. If the body has been encoded with a content encoding, the underlying data should be in canonical form prior to being encoded.

Media subTypes of the "text" type use crlf as the text line break when in canonical form. However, DCP allows the transport of text media with plain cr or lf alone representing a line break when used consistently within the entity body. DCP applications must accept crlf, bare cr, and bare lf as being representative of a line break in text media received via DCP.

In addition, if the text media is represented in a character set that does not use octets 13 and 10 for cr and lf respectively, as is the case for some multi-byte character sets, DCP allows the use of whatever octet sequences are defined by that character set to represent the equivalent of cr and lf for line breaks. This flexibility regarding line breaks applies only to text media in the entity body; a bare cr or lf should not be substituted for crlf within any of the DCP control structures (such as header fields and multipart boundaries).

The "charset" parameter is used with some media types to define the character set of the data. When the sender provides no explicit charset parameter, media subTypes of the "text" type are defined to have a default charset value of "ISO-8859-1" when received via DCP. Data in character sets other than "ISO-8859-1" or its subsets must be labeled with an appropriate charset value in order to be consistently interpreted by the recipient.

MULTIPART

MIME provides for a number of "multipart" types (encapsulations of several entities within a single message's entity body).  The multipart types registered by IANA do not have any special meaning for DCP, though resources may need to understand each type in order to correctly interpret the purpose of each body part. DCP resources should follow the same or similar behavior as a MIME user agent does upon receipt of a multipart type. DCP resources should not assume that other DCP resources are prepared to handle multipart types.

All multipart types share a common syntax and must include a boundary parameter as part of the mediaType value. The message body is itself a protocol element and must therefore use only crlf to represent line breaks between body parts. Multipart body parts may contain DCP header fields which are significant to the meaning of that part.


PRODUCT TOKENS

Product tokens are used to allow communicating resources to identify themselves via a simple product token, with an optional slash and version (or model) designator. Most fields using product tokens also allow sub-products which form a significant part of the application to be listed, separated by white space. By convention, the products are listed in order of their significance for identifying the resource.

Syntax
Examples

Application: DCP-Browser/1.1

Device: ADT-Security-2001/1.7

Product tokens should be short and to the point (use of them for advertising or other non-essential information is explicitly forbidden). Although any token character may appear in a productVersion, this token should only be used for a version identifier (i.e., successive versions of the same product should only differ in the productVersion portion of the product value).

FUNDAMENTALS OF DCP COMMUNICATION

MODES OF SERVICE

Like any application layer protocol or service, DCP resides on top of and depends on transport layer services for lower-level messaging.  Transport layer services may be categorized as either connectionless  or connection-oriented.  To provide flexibility and extensibility, DCP communication has been designed to take place over both connectionless and connection-oriented modes of service (MOS) on the transport layer.  

A connection-oriented MOS creates a virtual circuit, which gives the illusion of a physical communication path. It is a connection that appears to be point-to-point in nature.  A connection-oriented MOS is similar to a telephone conversation: the parties establish a connection, maintain the connection through the duration of their interaction and then terminate the connection.  For DCP, the virtual circuit remains intact through the duration of transactions and, optionally, through the lives of sessions.  Handshaking takes place within the transport layer to  guarantee the delivery of messages.  An advantage of connection-oriented MOS is the reliability provided by the transport layer in message delivery.  However, this is at the expense of greater associated overhead within the transport layer .  When guaranteed message deliver is desired, a connection-oriented MOS is preferred. 

A connectionless MOS provides communication in the form of a delivery service. It does not establish a point-to-point connection.  Since no form of connection is established between the parties, the transport layer services do not guarantee delivery.  A connectionless MOS can be compared to using a courier service:  the parties do not establish a connection, rather they communicate by sending each other messages via the service. Although there is no virtual circuit or guaranteed message delivery, DCP initiators and targets maintain state (or keep track of messages and of each other) through the use of session and transaction identifiers (similar to how couriers use tracking numbers).    Advantages of connectionless MOS include the ability to broadcast messages to the network at large and less associated transport layer overhead.  However, this sacrifices a transport that guarantees delivery.  Connectionless MOS is generally preferred when guaranteed message delivery is not required and light-weight or broadcast messaging is desired.  

Note: Although a connectionless MOS does not provide guaranteed delivery within the transport layer, DCP provides a set of robust facilities for tracking messages which allow a guaranteed delivery service to be implemented within the DCP application layer.

DCP employs UDP and TCP transport protocols for connectionless MOS and connection-oriented MOS respectively. The default port is 2500, but other ports may be used. This does not preclude DCP from being implemented on top of other protocols on the Internet, or on other networks. DCP only presumes transport layers that provide connection-oriented MOS and connectionless MOS. The mapping of the DCP message structures onto the transport data units of other protocols is outside the scope of this reference.

Note: The DCP URL dcpScheme for connection-oriented MOS includes "dcp" (indicates TCP transport) and "dcps" (indicates TCP secured by TLS).  The DCP URL dcpScheme for connectionless MOS is  "dcpu"  (indicates UDP transport).

SESSIONS

DCP communication follows a session / transaction paradigm.  A session is a conversation between two resources.  DCP sessions and transactions can be compared to a conversation between people.  A session is like an entire conversation and transactions are like statements (or questions and answers).  Just as many statements are made by both parties in a conversation, many transactions can be made by both participants in a single DCP session.   A DCP conversation behaves as follows:

  1. A DCP session with a target device is opened.

  2. Any number of DCP transactions are made within the session.

  3. The DCP session is closed.

The use of sessions provides numerous benefits.  These include:

  • Less header data, because data that is pertinent to a session only needs to be sent once (when the session is created) rather than with each transaction, resulting in greater speed and less traffic.  

  • Convenience of "pipelining" transactions through the session.  

  • Flexibility in implementation.  

  • A facility for hosting tethers and managing groups of transactions; when a session is closed, all pending transactions and tethers should be closed as well.

Sessions apply to both connection-oriented and connectionless modes of service and should not be considered the same as a transport layer connection.  Sessions are identified by the Session-ID header assigned by either resource when the DCP conversation is first started and may span multiple transport layer connections or datagrams.   All transactions that take place within the session must carry the session ID with them in the header data.  This provides a way of grouping transactions together and keeping track of them.  The DCP session provides implementation flexibility and allows the features of DCP to be supported in both connection-oriented and connectionless modes of service without degrading its capabilities. 

DCP makes use of special request header fields and response status codes for managing sessions.  Sessions may be managed explicitly and implicitly, friendly and unfriendly, and as an initiator or as a target.  The Session and Session-ID request message headers are used in conjunction with the  202 Keep-Alive and 203 Release response status codes to open and close sessions.  These message headers and response codes may be used within any transaction.  For DCP transactions that are initiated outside the scope of a session, the target must create a session and establish a Session ID before processing the transaction.

Detailed semantics for managing sessions are provided later in this reference.


TRANSACTIONS

A transaction is a piece of DCP communication that occurs within a session.  Many transactions can occur within a single session.  Transactions may be of an open-loop or closed-loop nature.  There are two general types of DCP transactions and each of these may occur in either direction (see figure below):

  1. open-loop

  2. closed-loop

 

session.jpg (9621 bytes)

 

Open-loop transactions are one-way communication scenarios that are initiated by one resource and processed by another. They do not include a response. This is similar to sending a check off in the mail and not receiving a receipt for it -- the sales loop is left open.  A closed-loop transaction is a two-way communication scenario that, in addition to the message that initiates the transaction, includes a response. This is similar to writing a check for something at the store -- you get a receipt and the sales loop is closed. Although both types of transactions may be implemented in either mode of service, connectionless modes of service allow transactions to be sent to the network at large. With the exception of discover requests, the default behavior for requests sent to the entire network is that they are open-loop transactions and should not be responded to.  Discover requests (which are always broadcast to a network) should always be treated as closed-loop transactions and should result in a response.  The default behavior for requests sent to specific hosts is that they are closed-loop transactions and should result in a response.  Through the use of the Transaction-Type request header, default behavior can be over-ridden.  Unlike the ubiquitous client/server model, the DCP model for communication results in resources that play more than one messaging role. DCP devices are likely to initiate and process both open-loop and closed-loop transactions.

Open-loop transactions should be used when a response is optional and it is unimportant to ensure that any specific resource processed the message.  One application for the open-loop transaction is to notify other devices when a minor device event occurs.  In a connectionless mode of service, these transactions may be sent to the whole network, notifying all DCP devices of an event.  If a response is needed or an acknowledgement of processing is desired, then the closed-loop transaction should be used.  Example applications for this type of transaction include querying or setting a device property, calling a device method, and sending critical event messages.

The basic building blocks of transactions are DCP messages.  They will be discussed later in the DCP Message section.

DCP MESSAGE FORMAT

DCP messages are the basic building blocks of DCP communication.  DCP messages build the transactions which make up DCP sessions.  In DCP, there are different types of messages and they are made up of request lines, status (or response) lines, headers and bodies.


MESSAGE TYPES

The DCP messages consist of requests from initiators to targets and responses from targets to initiators.

Syntax

MESSAGE HEADERS

DCP message headers are attribute and value pairs embedded within messages that are used to convey information about the message, initiators, targets and desired behavior.  DCP header fields follow the same generic format as that given in Section 3.1 of RFC 822. Each header field consists of a name followed immediately by a colon (":"), a single space (sp) character, and the field value. Field names are case-insensitive. Header fields can be extended over multiple lines by preceding each extra line with at least one sp or ht, though this is not recommended.

Syntax

The order in which header fields are received is not significant. However, it is "good practice" to send general header fields first, followed by DCP headers (request and response headers) and entity header fields.

Multiple DCP header fields with the same fieldName may be present in a message if and only if the entire fieldValue for that header field is defined as a comma separated list.  It must be possible to combine the multiple header fields into one "fieldName: fieldValue pair, without changing the semantics of the message, by appending each subsequent fieldValue to the first, each separated by a comma.


GENERAL HEADER FIELDS

There are a few header fields which have general applicability for both request and response messages, but which do not apply to the entity being transferred. These header fields apply only to the message being transmitted and they are referred to as general headers.

Syntax

 

 

REQUEST

DCP request messages are used to initiate transactions.   They are made up of a request line, followed by message headers and then an optional entity  body.  The structure of the request message follows:

Syntax

REQUEST LINE

The DCP request line is the first part of a request message.  It includes an optional method operator, request method, URI and DCP version.   The semantics for the request line follow.

Syntax

REQUEST METHOD OPERATOR

The request method operator is used to enhance the behavior of a request method.  The presence of an exclamation mark "!" in the first token of a request line indicates that the set of characters to the left of the exclamation mark forms a method operator.  This operator is applied against the request method that follows the exclamation mark and modifies the normal behavior of the request method.

Syntax

REQUEST METHOD

The DCP request method is used to indicate the purpose of a request.  It is applied to the resource referenced by the DCP request URI in the request line.

Syntax

REQUEST URI

The DCP request indicates the resource to which the request method in the request line are to be applied.  The DCP request URI is a Uniform Resource Identifier that has been extended to support devices modeled as objects.

Syntax

The two options for request URI are dependent on the nature of the request.

The dcpUrl form is only allowed when the request is being made to a proxy (or intermediary). The proxy is requested to forward the request and return the response. The proxy may forward the request on to another proxy or directly to the target specified by the dcpUrl. In order to avoid request loops, a proxy must be able to recognize all of its target names, including any aliases, local variations, and the numeric IP address. 

Example: Request Line with absolute DCP URL

GET DCP://x10.domain.com/X10(AC=1,HC=A).Power DCP/1.0

The most common form of the DCP request URI is that used to identify a resource on a target. In this case, only the absDcpPath of the URI is transmitted. 

Example: Request Line with absolute DCP Path

GET X10(AC=1,HC=A).Power DCP/1.0

Note: The absDcpPath cannot be empty; if none is present in the original URI, it must be given as "/" (the target root).

The DCP request URI is transmitted as an encoded string, where some characters may be escaped using the ' "%"  hex hex ' encoding defined by RFC 1738. The target must decode the DCP request URI to properly interpret the request.


REQUEST HEADER FIELDS

Request header fields allow the initiator to pass additional information about the request, and about the initiator itself, to the target. These fields act as request modifiers, with semantics equivalent to the parameters on a programming language method (procedure) invocation.

Request header field names can be extended reliably only in combination with a change in the protocol version. However, new or experimental header fields may be given the semantics of request header fields if all parties in the communication recognize them to be request header fields. Unrecognized header fields are treated as entity header fields.

Syntax

RESPONSE

After receiving and interpreting a request message for a closed-loop transaction, a target responds in the form of one or multiple DCP response messages.  The information sent in a response is dependent on the request method.

Syntax
Note: Targets should not respond to requests that are made as part of open-loop transactions.

STATUS LINE

The first line of a response message is the status line, consisting of the protocol version followed by a numeric status code and its associated textual phrase, with each element separated by sp characters. No cr or lf is allowed except in the final crlf sequence.

Syntax

STATUS CODE

The status code element of a reponse status line is a 3 digit integer result code of the attempt to understand and satisfy the request. The status code is intended for use by automata.  The first digit of the status code defines the class of response. The last two digits do not have any categorization role.

Reference: Status Code Response Classes
1xx: Informational
Not used, but reserved for future use.
2xx: Success
The action was successfully received, understood, and accepted.
3xx: Redirection
Further action must be taken in order to complete the request.
4xx: Initiator Error
The request contains bad syntax or cannot be fulfilled.
5xx: Target Error
The target failed to fulfill an apparently valid request.

The individual values of the numeric status codes defined for DCP and status code semantics are presented below. 

Syntax

DCP status codes are extensible. DCP applications are not required to understand the meaning of all registered status codes, though such understanding is obviously desirable. However, applications must understand the class of any status code, as indicated by the first digit, and treat any unrecognized response as being equivalent to the x00 status code of that class.  For example, if an unrecognized status code of 431 is received by the initiator, it can safely assume that there was something wrong with its request and treat the response as if it had received a 400 status code. In such cases, initiator agents should present to the user the entity returned with the response, since that entity is likely to include human-readable information which will explain the unusual status.

REASON PHRASE

The reason phrase of a response status line is intended to give a short textual description of the status code.  The initiator is not required to examine or display the reason phrase.  The semantics for the reason phrase follow.

Syntax
reasonPhrase = *<text, excluding cr and lf>

A set of recommended reason phrases is presented below.  

Reference: Recommended Reason Phrases
Status
Code
Reason
Phrase
200 = "OK"
201 = "OK, Pending"
202 = "OK, Keep Alive"
203 = "OK, Release"
300 = "Not Changed"
301 = "Session Redirected"
400 = "Bad Request"
401 = "Unauthorized"
402 = "Session Error"
403 = "Forbidden"
404 = "Not Found"
405 = "Method Not Allowed"
500 = "Internal Target Error"
501 = "Not Implemented"
503 = "Service Unavailable"
Note: Since the reason phrases listed here are only suggested,  they may be replaced by local equivalents without affecting the protocol.

RESPONSE HEADER FIELDS

Response header fields allow the target to pass additional information about the response which cannot be placed in the status line. These header fields give information about the target and about further access to the resource identified by the request URI.

Response header field names can be extended reliably only in combination with a change in the protocol version. However, new or experimental header fields may be given the semantics of response header fields if all parties in the communication recognize them to be response header fields. Unrecognized header fields are treated as entity header fields.

Syntax

ENTITIES

An entity is a particular representation or rendition of device data that may be enclosed within a request or response message.  An entity consists of meta-information in the form of entity headers and (usually) content in the form of an entity body.

ENTITY HEADER FIELDS

Entity header fields define optional meta-information about the entity body or, if no body is present, about the resource identified by the request.

Syntax

ENTITY BODY

The content (if any) of an entity takes the form of an entity body.  Bodies are sent with requests and responses in a format and encoding defined by entityHeader fields (see entity type and entity length).

Syntax

An entity body is included with a request message only when the request method calls for one. The presence of an entity body in a request is signaled by the inclusion of a contentLength header field in the request message headers. DCP requests containing an entity body must include a valid contentLength header field.

For response messages, whether or not an entity body is included with message is dependent on both the request method and the response code. All 1xx (informational) and 300 Not Changed responses must not include a body. All other responses must include an entity body or a contentLength header field defined with a value of zero (0).


TYPE

When an entity body is included with a message, the data type of that body is determined via the header fields contentType and contentEncoding. These define a two-layer, ordered encoding model.  The contentType header specifies the media type of the underlying data. A contentEncoding header may be used to indicate any additional content coding applied to the type (usually for the purpose of data compression).  The default for the content encoding is none (i.e., the identity function).

Any DCP message containing an entity body should include a contentType header field defining the media type of that body. If and only if the media type is not given by a contentType header, the recipient may attempt to guess the media type via inspection of its content and/or the name extension(s) of the URL used to identify the resource. If the media type remains unknown, the recipient should treat it as type "application/octet-stream".


LENGTH

When an entity body is included with a message, the length of that body may be determined in one of two ways for connection-oriented MOS. If a contentLength header field is present, its value in bytes represents the length of the entity body. Otherwise, the body length is determined by the closing of the connection by the target for connection-oriented MOS. Since connectionless MOS does not establish a connection, a contentLength header is required for connectionless MOS.

Closing a connection-oriented MOS connection cannot be used to indicate the end of a request body, since it leaves no possibility for the target to send back a response. Therefore, DCP requests containing an entity body must include a valid contentLength header field whether they are connection-oriented MOS or connectionless MOS. If a request contains an entity body and content length is not specified, and the target does not recognize or cannot calculate the length from other fields, then the target should send a 400 Bad Request response.

REQUEST METHODS

The set of common request methods and associated operators for DCP are defined in this section. Although this set can be extended, additional methods and operators cannot be assumed to share the same semantics for separately extended initiators and targets. The definitions that follow describe DCP messages for the transaction and session on both modes of service. When there are any differences in implementation, they will be described in detail.


METHOD OPERATORS

The request method operator is used to enhance the behavior of a request method.  The presence of an exclamation mark "!" in the first token of a request line indicates that the set of characters to the left of the exclamation mark forms a method operator.  This operator is applied against the request method that follows the exclamation mark.

Syntax

CANCEL

DCP has one pre-defined request method operator: cancel.  The cancel operator is used to cancel the processing of a pending or in-process request against the object to which the method is applied. It is at the discretion of the developer to define application behavior for terminating in-process requests. DCP only requires that this method operator cancel requests not yet in process and terminate any tether activity in the same session on the corresponding resource.

Syntax
cancel = "CANCEL"
Example: Canceling a CALL Request

CANCEL!CALL DCP://dcp.domain.com/Security.Reset() DCP/1.0

Example: Canceling a Tether

CANCEL!TETHER DCP://dcp.domain.com/Security.State DCP/1.0

Note: The termination of a tether should happen only within the session in which the cancel request method operator is initiated. This means that if two separate tethers to the same resource exist in separate sessions when a "cancel tether" request is made against the resource, only the tether that is in the same session as the cancel should be terminated.

REQUEST METHOD DEFINITIONS

The DCP request method is used to indicate the purpose of a request.  It is applied to the resource referenced by the DCP request URI in the request line.  This section defines each of the request methods.

Syntax

GET

The get method is used to retrieve a property of the object identified in the request URI. The get request should not contain a body, however the retrieved property for a get request is in the form of an entity body. The semantics for the get method follow:

Syntax
get = "GET"
Example: Get Request for the status of a security system

GET DCP://security.domain.com/Status DCP/1.0

The get method may also be applied to an object with no property specified in the request URI. One such application is to return a default property. It is at the discretion of the developer to implement the behavior for such a request.

DCP supports reserved objects. They are identified in the request URI by the "*" prefix followed by the name of the reserved object. The get method may be used to request reserved objects.

Example: Get Request for the UI reserved object  of a security system

GET DCP://security.domain.com/*UI DCP/1.0

The cancel request method operator may be used on the get method to cancel pending get requests. It is at the discretion of the developer to determine the behavior for requests already in process.


SET

The set method is used to modify a property value of the object identified in the request URI. The set request and response should not contain a body

Syntax
set = "SET"
Example: Set Request for setting the mode of a security system using the ssl (dcps)

GET DCPS://security.domain.com/mode=Vacation DCP/1.0

The cancel request method operator may be used on the set method to cancel pending set requests. It is at the discretion of the developer to determine the behavior for requests already in process.


CALL

The call method is used to invoke a procedure (or method) of the object identified in the request URI.  The call request should not contain a body, however an optional returned value for a call request is in the form of an entity body

Syntax
call = "CALL"
Example: Call Request of the clearAlarm method for a security system using ssl (dcps)

CALL DCPS://security.domain.com/clearAlarm(accessCode=password) DCP/1.0

The cancel request method operator may be used on the call method to cancel pending call requests. It is at the discretion of the developer to determine the behavior for requests already in process.


EVENT

The event method is used to send notification of an initiator object event to the target object identified in the request URI. The event request should contain the event data in the form of an entity body, however the response should not contain a body. 

Syntax
event = "EVENT"
Example: Event Request & Entity Body for a security system alarm event

EVENT DCP://target.domain.com DCP/1.0

    <?xml version="1.0" encoding="UTF-8"?> 
    <!DOCTYPE DCP SYSTEM "http://www.domain.com/dcp.dtd" >
    <DCP>
        <Data URL="DCP://security.domain.com">
            <dEvent Name="Alarm"/>
        </Data>
    </DCP>

Although the cancel request method operator may be used on the event method, it is meaningless. DCP only requires that a valid response be returned.


SUBSCRIBE

The subscribe method is used to subscribe to the object event identified in the request URI. By subscribing to an object event the initiator is requesting that occurrences of this event on the target object result in notification via an event request method from the target to the initiator. The subscribe request and response should not contain a body

Syntax
subscribe = "SUBSCRIBE"
Example: Subscribe Request of the Alarm event of a security system using ssl (dcps)

SUBSCRIBE DCPS://security.domain.com/Alarm DCP/1.0

The cancel request method operator may be used on the subscribe method to cancel a subscription to object events.


TETHER

The tether method provides a facility for establishing and terminating a continuous flow, rather than an event driven flow, of information from the target. This allows an initiator to tether to a property on a target, resulting in a continuous feed of property data at the expense of one transaction.  The tether request and response should not contain a body.

The semantics for the TETHER method follow:

Syntax
tether = "TETHER"
Example: Tether Request of the status of a security system

TETHER DCPS://security.domain.com/Status DCP/1.0

Tethering should persist until the tether is explicitly canceled by the cancel request method operator or the session is terminated.

Example: Canceling a tether on the status of a security system

CANCEL!TETHER DCPS://security.domain.com/Status DCP/1.0

Note: The termination of a tether should happen only within the session in which the cancel request method operator is initiated. This means that if two separate tethers to the same resource exist in separate sessions when a "cancel tether" request is made against the resource, only the tether that is in the same session as the cancel should be terminated.

ADMIN

The admin method provides a facility for managing sessions. This allows an initiator to explicitly establish, terminate, expire and keep alive sessions and any supporting connections. The admin request and response should not contain a body. The specific behavior in response to an admin request is dependent on the headers transmitted along with it.

Syntax
admin = "ADMIN"
Example: ADMIN Request on a security system using ssl (dcps)

ADMIN DCPS://security.domain.com DCP/1.0

Although the cancel request method operator may be used on the admin method, it is meaningless. DCP only requires that a valid response be returned.


DISCOVER

The discover method provides a mechanism for determining what other DCP-aware devices (if any) are on the network.  This is especially useful when a device is turned on for the first time and it is not known what other devices exist. Discover requests are always broadcast to the network or subnet (rather than applied against a specific host) and, hence, must take place on a connectionless mode of serviceTransactions broadcast to an entire network, which, by default, are open-loop transactions, must behave as closed-loop transactions for discover requests.   All DCP aware devices on a network should respond to discover requests except when there is reason to conceal the presence or identity of a device.  The response includes an entity body which specifies the product name, URI and optional device attributes.

Syntax
discover = "DISCOVER"
Example 1: DISCOVER broadcast request on a subnet

DISCOVER DCPU://192.168.100.255 DCP/1.0

Example 2: Response entity body returned from a subnet device in Example 1

    <?xml version="1.0" encoding="UTF-8"?> 
    <!DOCTYPE DCP SYSTEM "http://www.domain.com/dcp.dtd">
    <DCP>
        <ObjectModel Name="Acme_Security-ABC123"  
            URL="DCP://security.domain.com" Device="Y">
        </ObjectModel>
    </DCP>

The cancel request method operator may be used on the discover method to cancel any associated pending responses from devices on the network.

RESERVED OBJECTS

Reserved objects are predefined structures that facilitate and standardize the exposition and transfer of a core set of objects that apply to all devices.    An asterisk (*) in the request URI indicates that the token that follows is a DCP reserved object. The get method is used to request reserved objects.

Syntax
Example: Get Request for the object model (*OM) reserved object

GET DCP://security.domain.com/*OM DCP/1.0

In the example above, the target device would return it's object model in the entity body of the response.

Reserved objects essentially define a way to query any device (known or unknown) for basic information and data. 


OBJECT MODEL

The DCP Object Model is a reserved object which conforms to a hierarchical object-oriented structure that provides a facility for retrieving an object’s (or device's) child objects, methods, properties and events. It exposes everything necessary to carry on DCP communication with the device.  The object model is returned within the response's entity body with content negotiated prior to transfer.  Although an XML document type definition has been defined for the DCP reserved object model, use of the representation with DCP is not required.  The reserved object only facilitates the exposition and transfer of the object model.   

Syntax
objectModel = "*OM"
Example: Get Request for the object model (*OM) reserved object

GET DCP://security.domain.com/*OM DCP/1.0

The reserved object model essentially defines a way to query any device (known or unknown) for information regarding its objects, properites, methods and events.


USER INTERFACE

The DCP User Interface (UI) object  is a reserved object which provides the facility for embedding, exposing and delivering object-specific user interfaces within objects (or devices) themselves. The UI object is returned within the response's entity body with content negotiated prior to transfer.  The user interface object may be implemented with whatever technology the developer chooses and does not specify the behavior for user interfaces.  The DCP UI object only facilitates the exposition and transfer of the interface.

Syntax
userInterface = "*UI"
Example: Get Request for the user interface (*UI) reserved object

GET DCP://security.domain.com/*UI DCP/1.0


DOCUMENTATION

The Documentation object is a reserved object which provides the facility for embedding and delivering object-specific documentation within objects (or devices) themselves. The document object is returned within the response's entity body with content negotiated prior to transfer.

Syntax
documentation = "*DOC"
Example: Get Request for the documentation (*DOC) reserved object

GET DCP://security.domain.com/*DOC DCP/1.0


DRIVER

The Driver Object is a  reserved object which provides the facility for embedding, exposing and delivering software and hardware drivers within objects (or devices) themselves. The driver object is returned within the response's entity body with content negotiated prior to transfer. DCP does not specify the behavior for drivers; it only specifies the exposition and transfer. The driver object may be used to implement plug-and-play behavior. Since content is negotiated prior to transfer, more than one driver may be embedded in a single object allowing for multi-platform support.

Syntax
driver = "*DRV"
Example: Get Request for the driver (*DRV) reserved object

GET DCP://security.domain.com/*DRV DCP/1.0

STATUS CODE DEFINITIONS

The various status codes for DCP responses are defined in this section.  The status code element of the reponse status line is a 3 digit integer result code of the attempt to understand and satisfy the request. The status code is intended for use by automata.  The first digit of the status code defines the class of response. The last two digits do not have any categorization role.  Each status code is described in this section. The main classes for status codes are listed below.

Reference: Status Code Response Classes
1xx: Informational
Not used, but reserved for future use.
2xx: Success
The action was successfully received, understood, and accepted.
3xx: Redirection
Further action must be taken in order to complete the request.
4xx: Initiator Error
The request contains bad syntax or cannot be fulfilled.
5xx: Target Error
The target failed to fulfill an apparently valid request.

1XX: INFORMATIONAL

The 1xx: Informational class of status code indicates a provisional response, consisting only of the status line and optional headers, and is terminated by an empty line. DCP does not define any 1xx status codes and they are not a valid response to a DCP request.  However, they may be useful for experimental applications which are outside the scope of this specification.


2XX: SUCCESSFUL

This 2xx: Successful class of status code indicates that the initiators's request was successfully received, understood, and accepted.

Reference: 2xx: Successful status codes and recommended reason phrases
Status
Code
Reason
Phrase
200 = "OK"
201 = "OK, Pending"
202 = "OK, Keep Alive"
203 = "OK, Release"

200 OK

The 200 status code indicates that the request succeeded.  

Syntax
200 = "200"
Reference: Recommended Reason Phrase
Example: Status Line with a 200 Status Code

DCP/1.0 200 OK

The information returned with the response is dependent on the method used in the request.
Reference: Information returned with a 200 response
Method Response
get : A status line and header information along with an entity corresponding to the requested object property or reserved object are sent in the response.
set : The response only contains a status line and header information.  Entity bodies should not be sent in the response.
call : A status line and header information along with an entity containing the return data of the object method called are sent in the response.
event : A status line and header information along with an entity corresponding to the event are sent in the response.
subscribe : The response only contains a status line and header information.  Entity bodies should not be sent in the response.
tether : The response only contains a status line and header information.  Entity bodies should not be sent in the response.
admin : The response only contains a status line and header information.  Entity bodies should not be sent in the response.

201 OK, Pending

The 201 status code indicates that the request has been accepted and processing has begun, but has not completed. The purpose of the 201 response is to allow long-running processes to return data to the initiator over multiple responses (and multiple connections on connection-oriented modes of service), and to inform the initiator to expect more responses pertaining to the original request.  

Syntax
201 = "201"
Reference: Recommended Reason Phrase
reasonPhrase201 = "OK, Pending"
Example: Status Line with a 201 Status Code

DCP/1.0 201 OK, Pending


202 OK, Keep Alive

The 202 status code indicates that the request  has been accepted for processing and the session should be kept alive. This should be used in response to requests that contain headers that may indicate a session is terminating when keeping the session alive is desired.  The response information sent should conform to the same guidelines as 200 responses.

Syntax
202 = "202"
Reference: Recommended Reason Phrase
reasonPhrase202 = "OK, Keep Alive"
Example: Status Line with a 202 Status Code

DCP/1.0 202 OK, Keep Alive


203 OK, Release

The 203 status code indicates that the request  has been accepted for processing and the session should be released. This should be used in response to requests that contain headers that may indicate a session is terminating when keeping the session alive is not desired.  The response information sent should conform to the same guidelines as 200 responses.

Syntax
203 = "203"
Reference: Recommended Reason Phrase
reasonPhrase203 = "OK, Release"
Example: Status Line with a 203 Status Code

DCP/1.0 203 OK, Release


3XX: REDIRECTION

The 3xx: Redirection class of status code indicates that further action needs to be taken by the initiator agent in order to fulfill the request. The action required may be carried out by the initiator agent without interaction with the user if and only if the method used in the subsequent request is GET or SUBSCRIBE. An initiator agent should never automatically redirect a request more than 5 times, since such redirections usually indicate an infinite loop.

Reference: 3xx: Successful status codes and recommended reason phrases
Status
Code
Reason
Phrase
300 = "Not Changed"
301 = "Session Redirected"

300 Not Changed

The 300 status code indicates that the initiator has performed a conditional get request (see If-Changed-Since) and access is allowed, but the property has not been modified since the date and time specified in the If-Changed-Since header field, the target must respond with this status code and not send an entity body to the initiator.

Syntax
300 = "300"
Reference: Recommended Reason Phrase
reasonPhrase300 = "Not Changed"
Example: Status Line with a 300 Status Code

DCP/1.0 300 Not Changed


301 Session Redirected

The 301 status code indicates that the target has specified an alternate location for the current session and that any further requests made within the session should be done using the alternate location.  This allows the target to specify another port or host for processing the remainder of the session.  The alternate location must be given by the location header field.

Initiators should automatically re-link references to the alternate location returned by the target.  For locations involving alternate hosts, initiator agents should be programmed to obtain confirmation prior to redirection from the initiator when there is a potential for the initiator to expose sensitive information.    

Syntax
301 = "301"
Reference: Recommended Reason Phrase
reasonPhrase301 = "Session Redirected"
Example: Status Line with a 301 Status Code

DCP/1.0 301 Session Redirected


4XX: INITIATOR ERROR

The 4xx: Initiator Error class of status code is intended for cases in which the initiator seems to have erred. If the initiator has not completed the request when a 4xx code is received, it should immediately cease sending data to the target. The target should include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method.

Note: If the initiator is sending data, target implementations on connection-oriented MOS (TCP specifically) should be careful to ensure that the initiator acknowledges receipt of the packet(s) containing the response prior to closing the input connection. If the initiator continues sending data to the target after the close, the target's controller will send a reset packet to the initiator, which may erase the initiator 's unacknowledged input buffers before they can be read and interpreted by the DCP application.

Reference: 4xx: Initiator Error status codes and recommended reason phrases
Status
Code
Reason
Phrase
400 = "Bad Request"
401 = "Unauthorized"
402 = "Session Error"
403 = "Forbidden"
404 = "Not Found"
405 = "Method Not Allowed"

400 BAD REQUEST

The 400 status code indicates that the request could not be understood by the target due to malformed syntax. The initiator should not repeat the request without modifications.

Syntax
400 = "400"
Reference: Recommended Reason Phrase
reasonPhrase400 = "Bad Request"
Example: Status Line with a 400 Status Code

DCP/1.0 400 Bad Request


401 UNAUTHORIZED

The 401 status code indicates that the request requires initiator access authentication. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource. The initiator may repeat the request with a suitable Authorization header field. If the request already included authorization credentials, then the 401 response indicates that authorization has been refused for those credentials. If the 401 response contains the same challenge as the prior response, and the initiator has already attempted authentication at least once, then the initiator should be presented the entity that was given in the response, since that entity may include relevant diagnostic information.

Syntax
401 = "401"
Reference: Recommended Reason Phrase
reasonPhrase401 = "Unauthorized"
Example: Status Line with a 401 Status Code

DCP/1.0 401 Unauthorized


402 SESSION ERROR

The 402 status code indicates that the request was understood by the target, but the target has refused to process it due to the session ID specified in the request (see the Session-ID header).  This may be used when an initiator tries to close a session that does not exist, open a session with an ID that is already in use, or when otherwise valid requests are denied due to the session ID specified.

Syntax
402 = "402"
Reference: Recommended Reason Phrase
reasonPhrase402 = "Session Error"
Example: Status Line with a 402 Status Code

DCP/1.0 402 Session Error


403 FORBIDDEN

The 403 status code indicates that the request was understood by the target, but the target is refusing to fulfill it. Authorization will not help and the request should not be repeated. If the target wishes to make public why the request has not been fulfilled, it should describe the reason for the refusal in the entity body. This status code is commonly used when the target does not wish to reveal exactly why the request has been refused, or when no other response is applicable.

Syntax
403 = "403"
Reference: Recommended Reason Phrase
reasonPhrase403 = "Forbidden"
Example: Status Line with a 403 Status Code

DCP/1.0 403 Forbidden


404 NOT FOUND

The 404 status code indicates that the target could not find anything matching the request URI.   If the target does not wish to make this information available to the initiator, the 403 status code can be used instead.

Syntax
404 = "404"
Reference: Recommended Reason Phrase
reasonPhrase404 = "Not Found"
Example: Status Line with a 404 Status Code

DCP/1.0 404 Not Found


405 METHOD NOT ALLOWED

The 405 status code indicates that the request method specified in the request line is not permitted for the resource identified by the request URI. The response must include an Allow header containing a list of valid methods for the requested resource.

Syntax
405 = "405"
Reference: Recommended Reason Phrase
reasonPhrase405 = "Method Not Allowed"
Example: Status Line with a 405 Status Code

DCP/1.0 405 Method Not Allowed


TARGET ERROR 5XX

The 5xx: Target Error class of status codes indicates cases in which the target is aware that it has erred or is incapable of performing the request. If the initiator has not completed the request when a 5xx code is received, it should immediately cease sending data to the target. The target should include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method and there are no required header fields.

Reference: 5xx: Target Error status codes and recommended reason phrases
Status
Code
Reason
Phrase
500 = "Internal Target Error"
501 = "Not Implemented"
503 = "Service Unavailable"

500 INTERNAL TARGET ERROR

The 500 status code indicates that the target encountered an unexpected condition which prevented it from fulfilling the request.

Syntax
500 = "500"
Reference: Recommended Reason Phrase
reasonPhrase500 = "Internal Target Error"
Example: Status Line with a 500 Status Code

DCP/1.0 500 Internal Target Error


501 NOT IMPLEMENTED

The 501 status code indicates the target does not support the functionality required to fulfill the request. This is the appropriate response when the target does not recognize the request method and is not capable of supporting it for any resource.

Syntax
501 = "501"
Reference: Recommended Reason Phrase
reasonPhrase501 = "Not Implemented"
Example: Status Line with a 501 Status Code

DCP/1.0 501 Not Implemented


503 SERVICE UNAVAILABLE

The 503 status code indicates that the target is currently unable to handle the request due to a temporary overloading or maintenance of the target. The implication is that this is a temporary condition which will be alleviated after some delay.

Note: The existence of the 503 status code does not imply that a target must use it when becoming overloaded. Some targets may wish to simply refuse the connection.

Syntax
503 = "503"
Reference: Recommended Reason Phrase
reasonPhrase503 = "Service Unavailable"
Example: Status Line with a 503 Status Code

DCP/1.0 503 Service Unavailable

HEADER FIELD DEFINITIONS

This section defines the syntax and semantics of all standard DCP header fields. For entity header fields, both sender and recipient refer to either the initiator or the target, depending on who sends and who receives the entity

Reference: DCP Header Fields

DCP Header
DCP Header Type
General Request Response Entity
accept   X    
acceptCharSet   X    
acceptEncoding   X    
acceptObjectModel   X    
allow       X
authorization   X    
connection X      
contentBase       X
contentEncoding       X
contentLength       X
contentLocation       X
contentType       X
date X      
eventSubscription   X    
ifChangedSince   X    
initiatorAgent   X    
lastChanged       X
location     X  
retryAfter     X  
session X      
sessionId X      
subscriptionPort   X    
target     X  
transactionId X      
transactionType   X    
wwwAuthenticate     X  

ACCEPT

The Accept request header field can be used to specify certain media types which are acceptable for the response. Accept headers can be used to indicate that the request is specifically limited to a small set of desired types.

Syntax
accept = "Accept" ":" #( mediaRange [ acceptParams ] )
mediaRange = ( "*/*"  | ( mainType "/" "*" ) | ( mainType "/" subType ) ) *( ";" parameter )
acceptParams = ";" "q" "=" qValue *( acceptExtension )
qValue = "0" | "0.1" | "0.2" | "0.3" | "0.4" | "0.5" | "0.6" | "0.7" | "0.8" | "0.9" | "1"
acceptExtension = ";" token [ "=" ( token | quotedString ) ]

The asterisk "*" character is used to group media types into ranges, with "*/*" indicating all media types and "type/*" indicating all subtypes of that type. The media range may include media type parameters that are applicable to that range.

Each media range may be followed by one or more acceptParams, beginning with the "q" parameter for indicating a relative quality factor. The first "q" parameter (if any) separates the mediaRange parameter(s) from the acceptParams. Quality factors allow the initiator to indicate the relative degree of preference for that mediaRange, using the qValue scale from 0 to 1. The default value is "q=1".

Example 1

Accept: audio/*; q=0.2, audio/basic 

Example1 should be interpreted as "I prefer audio/basic, but send me any audio type if it is the best available after an 80% mark-down in quality."

If no Accept header field is present, then it is assumed that the initiator accepts all media types. If an Accept header field is present, and if the target cannot send a response which is acceptable according to the combined Accept field value, then the target should send a 403 Forbidden response, though sending an unacceptable response is also allowed.

Example 2

Accept: text/plain; q=0.5, text/html, text/x-dvi; q=0.8, text/x-c

Verbally, example 2 would be interpreted as "text/html and text/x-c are the preferred media types, but if they do not exist, then send the text/x-dvi entity, and if that does not exist, send the text/plain entity."

Example 3

Accept: text/*, text/html, text/html;level=1, */* 

Media ranges can be overridden by more specific media ranges or specific media types. If more than one media range applies to a given type, the most specific reference has precedence. Example 3 would indicate the following precedence:

  1. text/html;level=1
  2. text/html
  3. text/*
  4. */*
Example 4

Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1, text/html;level=2;q=0.4, */*;q=0.5

The media type quality factor associated with a given type is determined by finding the media range with the highest precedence which matches that type.  Example 4 would cause the following values to be associated:

  • text/html;level=1 = 1
  • text/html = 0.7
  • text/plain = 0.3
  • image/jpeg = 0.5
  • text/html;level=2 = 0.4
  • text/html;level=3 = 0.7

Note: An initiator may be provided with a default set of quality values for certain media ranges. However, unless the initiator agent is a closed system which cannot interact with other rendering agents, this default set should be configurable by the user.


ACCEPT-CHARSET

The Accept-Charset request header field can be used to indicate what character sets are acceptable for the response. This field allows initiators capable of understanding more comprehensive or special- purpose character sets to signal that capability to a target which is capable of representing object data in those character sets. The ISO- 8859-1 character set can be assumed to be acceptable to all user agents.

Syntax
acceptCharSet = "Accept-Charset" ":" 1#( charSet [ ";" "q" "=" qValue ] )

Each charSet may be given an associated quality value which represents the user's preference for that charset. The default value is q=1. 

Example 

Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 

If no Accept-Charset header is present, the default is that any character set is acceptable. If an Accept-Charset header is present, and if the target cannot send a response which is acceptable according to the Accept-Charset header, then the target should send an error response with the 403 Forbidden status code, though the sending of an unacceptable response is also allowed.


ACCEPT-ENCODING

The Accept-Encoding request header field is similar to the Accept header, but restricts the content coding values which are acceptable in the response.

Syntax
acceptEncoding = "Accept-Encoding" ":" #( contentCoding )
Example 

Accept-Encoding: compress, gzip 

If no Accept-Encoding header is present in a request, the target may assume that the initiator will accept any content coding. If an Accept- Encoding header is present, and if the target cannot send a response which is acceptable according to the Accept-Encoding header, then the target should send an error response with the 403 Forbidden status code. An empty Accept-Encoding value indicates none are acceptable.


ACCEPT-OBJECT-MODEL

The Accept-Object-Model request header field is used by an initiator while requesting the object model reserved object from a target. This provides content negotiation for the object model object. The field can contain multiple product tokens and comments identifying the object model type.  The product tokens are listed in order of their preference.

Syntax
acceptObjectModel = " Accept-Object-Model" ":" 1*( product | comment )

Note: The Accept header field is used to negotiate the media type of the object model and the Accept-Object-Model header field is used for negotiating the object model representation.  DCP defines an object model representation, but this does not preclude other representations from being used.  The Accept-Object-Model header is used to indicate the representations that the initiator supports.

Example 

Accept-Object-Model: DCP/1.0

If no Accept-Object-Model header is present, the default is that any representation type of the object model is acceptable with the DCP object model representation being preferred. If an Accept-Object-Model header is present, and if the target cannot send a response which is acceptable according to the Accept-Object-Model header, then the target should send an error response with the 403 Forbidden status code, though the sending of an unacceptable response is also allowed.


ALLOW

The Allow entity header field lists the set of methods supported by the resource identified by the request URI. The purpose of this field is strictly to inform the recipient of valid methods associated with the resource. An Allow header field must be present in a 405 Method Not Allowed response.

Syntax
allow = "Allow" ":" 1#requestMethod
Example 

Allow: GET, SET, SUBSCRIBE

This field cannot prevent an initiator from trying other methods. However, the indications given by the Allow header field value should be followed. The actual set of allowed methods is defined by the target at the time of each request.


AUTHORIZATION

An initiator that wishes to authenticate itself with a target (usually, but not necessarily, after receiving a 401 Unauthorized response) may do so by including an Authorization request header field with the request. The Authorization field value consists of credentials containing the authentication information of the initiator for the realm of the resource being requested.

Syntax
authorization = "Authorization" ":" credentials
Example 

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

If a request is authenticated and a realm specified, the same credentials should be valid for all other requests within this realm.

Responses to requests containing an Authorization field must not be cached.


CONNECTION

The Connection general header field allows the initiator or target to specify options that are desired for the current transport layer connection.  DCP defines the "close" connection token for the sender to signal that the transport layer connection will be closed after the completion of the transaction.  

Syntax
connection = "Connection" ":" 1#(connectionToken)
connectionToken = token
Example 

Connection: Close

DCP devices that do not support persistent transport layer connections must include the "close" connection option in every message that takes place within a connection-oriented mode of service

Note: The Connection header refers to the transport layer connection and should not be confused with a DCP session.  Connections and sessions may be closed or terminated independently of each other.


CONTENT-BASE

The Content-Base entity header field may be used to specify the base URI for resolving relative URLs within the entity

Syntax
contentBase = "Content-Base" ":" absoluteUri
Example 

Content-Base: DCP://security.domain.com

If no Content-Base field is present, the base URI of an entity is defined either by its Content-Location (if that Content-Location URI is an absolute URI) or the URI used to initiate the request, in that order of precedence. 

Note: However, the base URI of the contents within the entity body may be redefined within that entity body.


CONTENT-ENCODING

The Content-Encoding entity header field is used as a modifier to the media type. When present, its value indicates what additional content codings have been applied to the entity body, and thus what decoding mechanisms must be applied in order to obtain the media type referenced by the Content-Type header field. Content-Encoding is primarily used to allow content to be compressed without losing the identity of its underlying media type.

Syntax
contentEncoding = "Content-Encoding" ":" 1#contentCoding
Example 

Content-Encoding: x-gzip

The Content-Encoding is a characteristic of the entity identified by the request URI. Typically, the entity body is stored with this encoding and is only decoded before rendering or analogous usage.

If multiple encodings have been applied to an entity, the content codings must be listed in the order in which they were applied.


CONTENT-LENGTH

The Content-Length entity header field indicates the size of the message body, in decimal number of octets, sent to the recipient.

Syntax
contentLength = "Content-Length" ":" 1*digit
Example 

Content-Length: 3495

Devices should use this field to indicate the size of the message body to be transferred, regardless of the media type of the entity. It must be possible for the recipient to reliably determine the end of DCP requests containing an entity body..

Any Content-Length greater than or equal to zero is a valid value.

Note: The meaning of this field is significantly different from the corresponding definition in MIME, where it is an optional field used within the "message/external-body" content type. In DCP, it should be sent whenever the message's length can be determined prior to being transferred.

When a message body is included with a message, the length of that body is determined by one of the following (in order of precedence):

  1. Any response message which must not include a message body is always terminated by the first empty line after the header fields, regardless of the entity header fields present in the message. 
  2. If the message uses the media type "multipart/byteranges", which is self-delimiting, then that defines the length. This media type must not be used unless the sender knows that the recipient can parse it; the presence in a request of a Range header with multiple byte-range specifiers implies that the recipient can parse multipart/byteranges responses.
  3. By the target closing the transport layer connection on a connection-oriented modes of service. (Closing the connection cannot be used to indicate the end of a request body, since that would leave no possibility for the target to send back a response.)

CONTENT-LOCATION

The Content-Location entity header field may be used to supply the resource location for the entity enclosed in the message. In the case where a resource has multiple entities associated with it, and those entities actually have separate locations by which they might be individually accessed, the target should provide a Content-Location for the particular variant which is returned. In addition, a target should provide a Content-Location for the resource corresponding to the response entity.

Syntax
contentLocation = "Content-Location" ":" ( absoluteUri | relativeUri )
Example 

Content-Location: DCP://security.domain.com/*OM

If no Content-Base header field is present, the value of Content-Location field also defines the base URL for the entity.

The Content-Location value is not a replacement for the original requested URI; it is only a statement of the location of the resource corresponding to this particular entity at the time of the request. Future requests may use the Content-Location URI if the desire is to identify the source of that particular entity.

If the Content-Location is a relative URI, the URI is interpreted relative to any Content-Base URI provided in the response. If no Content-Base is provided, the relative URI is interpreted relative to the request URI.


CONTENT-TYPE

The Content-Type entity header field indicates the media type of the entity body sent to the recipient.

Syntax
contentType = "Content-Type" ":" mediaType
Example 

Content-Type: text/xml; charset=ISO-8859-4


DATE

The Date general header field represents the date and time at which the message was originated having the semantics of dcpDate.

Syntax
date = "Date" ":" dcpDate
Example 

Date: Tue, 15 Nov 1994 08:12:31 GMT

If a message is received via direct connection with the initiator (in the case of requests) or the target (in the case of responses), then the date can be assumed to be the current date at the receiving end. Targets must include a Date header field in all responses. Initiators should only send a Date header field in messages that include an entity body, as in the case of the event request, and even then it is optional. A received message which does not have a Date header field should be assigned one by the recipient if the message.

In theory, the date should represent the moment just before the entity is generated. In practice, the date can be generated at any time during the message origination without affecting its semantic value.

The format of the Date is an absolute date and time as defined by dcpDate.


EVENT-SUBSCRIPTION

The Event-Subscription request header field must be included in event requests. It provides information regarding the subscription to the event.

Syntax
eventSubscription = "Event-Subscription" ":" subscriptionSegment
subscriptionSegment = "Fired" | "Expiring" | "Expired"
Example 

Event-Subscription: Fired

When the purpose of the request is to indicate that the associated event was fired, the "FIRED" subscription segment must be used.  When a subscription is timing out, the publisher may notify the subscriber with an event request and include the Event-Subscription header with the "EXPIRING" subscription segment. The subscriber may respond with a 202 (Keep-Alive) or 203 (Release) response to direct the publisher on how to handle the aging subscription. If the subscription has already expired, the publisher should use the "EXPIRED" subscription segment.


IF-CHANGED-SINCE

The If-Changed-Since request header field is used with a get method to make it conditional: if the requested variant has not been changed since the time specified in this field, an entity will not be returned from the target; instead, a 300 (Not Changed) response will be returned without any message body.

Syntax
ifChangedSince = "If-Changed-Since" ":" dcpDate
Example 

If-Changed-Since: Sat, 29 Oct 1994 19:43:31 GMT

A get method with an If-Changed-Since header requests that the identified entity be transferred only if it has been changed since the date given by the If-Changed-Since header. The algorithm for determining this includes the following cases:

  1. If the request would normally result in anything other than a 200 (OK) response, or if the passed If-Changed-Since date is invalid, the response is exactly the same as for a normal GET. A date which is later than the target's current time is invalid.
  2. If the variant has been changed since the If-Changed-Since date, the response is exactly the same as for a normal GET.
  3. If the variant has not been changed since a valid If-Changed-Since date, the target must return a 300 (Not Changed) response.

Note that If-Changed-Since times are interpreted by the target, whose clock may not be synchronized with the initiator.

Note that if an initiator uses an arbitrary date in the If-Changed-Since header instead of a date taken from the Last-Changed header for the same request, the initiator should be aware of the fact that this date is interpreted in the target's understanding of time. The initiator should consider unsynchronized clocks and rounding problems due to the different encodings of time between the initiator and target. This includes the possibility of race conditions if the resource has changed between the time it was first requested and the If-Changed-Since date of a subsequent request, and the possibility of clock-skew-related problems if the If-Changed-Since date is derived from the initiator 's clock without correction to the target's clock. Corrections for different time bases between initiator and target are at best approximate due to network latency.


INITIATOR-AGENT

The Initiator-Agent request header field contains information about the initiator agent originating the request. This is for statistical purposes, the tracing of protocol violations, and automated recognition of initiator agents for the sake of tailoring responses to avoid particular intiator agent limitations. Although it is not required, initiator agents should include this field with requests. The field can contain multiple product tokens and comments identifying the agent and any subproducts which form a significant part of the initiator agent. By convention, the product tokens are listed in order of their significance for identifying the application.

Syntax
initiatorAgent = "Initiator-Agent" ":" 1*( product | comment )
Example 

Initiator-Agent: CERN-LineMode/2.15 libwww/2.17b3


LAST-CHANGED

The Last-Changed entity-header field indicates the date and time at which the origin target believes the variant was last changed.

Syntax
lastChanged = "Last-Changed" ":" dcpDate
Example

Last-Changed: Tue, 15 Nov 1994 12:45:26 GMT

The exact meaning of this header field depends on the implementation of the origin target and the nature of the original resource. For documentation, it may be just the last time the document was changed. For object properties, it may be the last time the property was set or changed. For virtual objects, it may be the last time the internal state changed.

An origin target must not send a Last-Changed date which is later than the target's time of message origination. In such cases, where the resource's last change would indicate some time in the future, the target must replace that date with the message origination date.

An origin target should obtain the Last-Changed value of the entity as close as possible to the time that it generates the Date value of its response. This allows a recipient to make an accurate assessment of the entity's change time, especially if the entity changes near the time that the response is generated.

DCP targets should send Last-Changed whenever feasible.


LOCATION

The Location response header field is used to redirect the recipient to a location other than the request URI for completion of the request or identification of a new resource. The Location header is used with 301 (Session Redirected) responses to specify an alternate location for the current session and that any further requests made within the session should be done using the alternate location.  This allows the target to specify another port or host for processing the remainder of the session.  The alternate location must be given by the Location response header field.

Syntax
location = "Location" ":" absoluteUri
Example 

Location: DCP://security.domain.com/Status


RETRY-AFTER

The Retry-After response header field can be used with a 503 (Service Unavailable) response to indicate how long the service is expected to be unavailable to the initiator. The value of this field can be either a dcpDate or an integer number of seconds (in decimal) after the time of the response.

Syntax
retryAfter = "Retry-After" ":" ( dcpDate | deltaSeconds )
deltaSeconds = integer number of seconds (in decimal) after the time of the response
Examples

Retry-After: Fri, 31 Dec 1999 23:59:59 GMT


Retry-After: 120

In the latter example, the delay is 2 minutes.


SESSION

The Session general header field must be included in all requests. It provides information regarding the session in which the request will take place.  This Session header field may also be used in the response to indicate what will happen to the session after the transaction. If the "closing" session segment is used in the response, then closing of the session is mandatory and may not be negotiated.

Syntax
session = "Session" ":" sessionSegment
sessionSegment = "Closed" | "Closing" | "Open"
Example 

Session: Closed

When a session is timing out, the target may notify the initiator with any valid request by including the Session header with the "Closing" session segment. The initiator may respond with a 202 (OK, Keep-Alive) or 203 (OK, Release) to direct the target on how to handle the aging session. If the session has already timed out, the target should use the "Closed" session segment.


SESSION-ID

The Session-ID general header field must be included in all requests.  If a Session-ID header is not present in a request, the target should assign the request a sessionId. The Session-ID header must be included in all responses as well. 

Sessions apply to both connection-oriented and connectionless modes of service and should not be considered the same as a connection.  Sessions are identified by the session ID.   All transactions that take place within the session must carry the session ID with them via the Session-ID header.  This provides a way of grouping transactions together and keeping track of them.  

Syntax
sessionId = "Session-ID" ":" uniqueId
uniqueId = 1-32*(xchar)
xchar = alpha | digit
Example 

Session-ID: XjG8982G444DFD


SUBSCRIPTION-PORT

The Subscription-Port request header field must be included in subscribe requests when the desired port for the receipt of the corresponding event message differs from the default port number.

Syntax
subscriptionPort = "Subscription-Port" ":" port
Example 

Subscription-Port: 3000


TARGET

The Target response header field contains information about the software used by the origin target to handle the request. The field can contain multiple product tokens and comments identifying the target and any significant subproducts. The product tokens are listed in order of their significance for identifying the application.

Syntax
target = "Target" ":" 1*( product | comment )
Example 

Target: Sec8210/Model8210 Firmware Rev 2.18

Note: Revealing the specific software version of the target may allow the target to become more vulnerable to attacks against software that is known to contain security holes. Target implementers are encouraged to make this field a configurable option.


TRANSACTION-ID

The Transaction-ID general header field may be included in any request to give a unique identifier to each request. If the target supports transaction ID’s, it should include the identical header and ID in any response pertaining to the request. This will allow the initiator to link up responses with corresponding requests. This is especially useful in a connectionless modes of service. It is also useful in connection-oriented modes of service when responses are broken up into multiple responses and when requests are pipelined to the target.

Syntax
transactionId = "Transaction-ID" ":" uniqueId
Example 

Transaction-ID: XjG8982G444DFD


TRANSACTION-TYPE

The Transaction-Type request header field may be included in a request when the default transaction type is not desired.  A response message may be explicitly prevented by including the Transaction-Type request header with "Open-Loop" as its value. By including the Transaction-Type request header with "Closed-Loop" as its value, the initiator is explicitly requesting that a response be returned.

Syntax
transactionType = "Transaction-ID" ":" type
type = "Open-Loop" | "Closed-Loop"
Example 

Transaction-Type: Open-Loop


WWW-AUTHENTICATE

The WWW-Authenticate response header field must be included in 401 (Unauthorized) response messages. The field value consists of at least one challenge that indicates the access authentication scheme(s) and parameters applicable to the request URI.

Syntax
wwwAuthenticate = "WWW-Authenticate" ":" 1#challenge
Example 

WWW-Authenticate: Basic realm = "DcpWorld"

Initiator agents must take special care in parsing the WWW-Authenticate field value if it contains more than one challenge, or if more than one WWW-Authenticate header field is provided, since the contents of a challenge may itself contain a comma-separated list of authentication parameters.

SESSION MANAGEMENT

DCP makes use of special request header fields and response status codes for managing sessions.  Sessions may be managed explicitly and implicitly, friendly and unfriendly, and as an initiator or as a target.  The semantics for the various methods of opening and closing sessions follow.

Opening Sessions

Explicit Open:

  1. Either party makes a  request against the other.  The request must carry the Session message header with a value of  "Open" and, optionally, the Session-ID message header with a valid uniqueId

  2. The target responds with a 200 OK or 201 OK, Pending status code followed by the Session-ID message header.  

    • If the request had a valid uniqueId, then the target must assign the same uniqueId to the Session-ID message header and process the transaction. 

    • If there was not a valid uniqueId present, then the Target must assign one and process the transaction. The target may associate the transaction with an already active session. 

    • If the request had a valid uniqueId that corresponds to an active session between the two resources then the target must associate the request with the session (rather than opening a new session) and process the transaction.  

Note: If for any reason the target wishes to refrain from processing the transaction because of the uniqueId identified by the Session-ID message header in the request or due to an inability to open a session, the 402 Session Error response status code should be used.

Implicit Open:

  1. Either party initiates a request against the other which does not include Session message header.

  2. The target responds with a 200 OK or 201 OK, Pending status code followed by the Session-ID message header

    • If the request did not include a valid uniqueId, then the target must create a session, assign a uniqueId to the Session-ID message header and processes the transaction.  The target may associate the transaction with an already active session.

    • If the request included a valid uniqueId that does not correspond to an active session, then the target must create a session, assign the unrecognized uniqueId to the Session-ID message header and process the transaction.

    • If the request included a valid uniqueId that corresponds to an active session, then the target must associate the request with the session (rather than opening a new session) and process the transaction. 

Note: If for any reason the target wishes to refrain from processing the transaction because of the uniqueId identified by the Session-ID message header in the request or due to an inability to open a session, the 402 Session Error response status code should be used.

 
Closing Sessions

Friendly Close as an Initiator:

  1. Either party makes a request against the other followed by the Session message header with a value of  "Closing" and the Session-ID message header with corresponding uniqueId.

  2. The target responds as follows:

Friendly Close as a Target:

Note: There is not a friendly method for closing a session as a target.  However, after the target completes a transaction, it may generate a request against the other party and close the session in a friendly manner as an initiator.  

Unfriendly Close as an Initiator:

  1. Either party makes a request against the other followed by the Session message header with a value of  "Closed" and the Session-ID message header with corresponding uniqueId.

  2. The target processes a transaction and responds with a 200 OK201 OK, Pending or 203 Release status code followed by the Session-ID message header with corresponding uniqueId

Unfriendly Close as a Target:

  1. The target processes a transaction and responds to a request with the 203 Release status code followed by the Session-ID message header with corresponding uniqueId.

    Note: The target may assume that unfriendly closes are acceptable etiquette in the following situations:

  2. The initiator should consider that the session is closed after the transaction is complete.

 

Session Etiquette

Initiator Guidelines (these are not requirements):

  1. For saving target resources: 

    • When an initiator does not wish to keep a session open after a transaction, the request should contain the Session message header with a value of "Closing".

  2.  For cooperating with the target:

    • When a response includes a 203 Release status code, the initiator should treat the session as closed.

    • When a response includes a 202 Keep-Alive status code as a result of a friendly initiator close, the initiator should keep the session open. 

  3. For being friendly:

    • When an initiator "times-out" an idle session, it should perform a friendly initiator close.

  4. For being straight-forward:

Target Guidelines (these are not requirements):

  1. For saving initiator resources:  

  2. For cooperating with the  initiator:

    • When requests include the Session message header with a value of "Open", the target should assume that the initiator wishes to keep the session open after the transaction.

    • When requests include the Session message header with a value of "Close" or "Closing", the target should assume that the initiator wishes to close  the session after the transaction.

  3.  For being friendly:

  4. For being straight-forward:

    • Targets should use the appropriate response status code to appropriately represent their needs in conjunction with the Session-ID message header with corresponding uniqueId.

ACCESS AUTHENTICATION

DCP provides a simple challenge-response authentication mechanism which may be used by a target to challenge a initiator request and by a initiator to provide authentication information. It uses an extensible, case-insensitive token to identify the authentication scheme, followed by a comma-separated list of attribute-value pairs which carry the parameters necessary for achieving authentication via that scheme.

Syntax

The 401 (unauthorized) response message is used by an origin target to challenge the authorization of a user agent. This response must include a DCP-Authenticate header field containing at least one challenge applicable to the requested resource.

Syntax

The realm attribute (case-insensitive) is required for all authentication schemes which issue a challenge. The realm value (case-sensitive), in combination with the canonical root URL of the target being accessed, defines the protection space. These realms allow the protected resources on a target to be partitioned into a set of protection spaces, each with its own authentication scheme and/or authorization database. The realm value is a string, generally assigned by the origin target, which may have additional semantics specific to the authentication scheme.

A user agent that wishes to authenticate itself with a target-- usually, but not necessarily, after receiving a 401 response--may do so by including an Authorization header field with the request. The Authorization field value consists of credentials containing the authentication information of the user agent for the realm of the resource being requested.

Syntax

The domain over which credentials can be automatically applied by a user agent is determined by the protection space.

If a prior request has been authorized, the same credentials may be reused for all other requests within that protection space for a period of time determined by the authentication scheme, parameters, and/or user preference. Unless otherwise defined by the authentication scheme, a single protection space cannot extend outside the scope of its target. If the target does not wish to accept the credentials sent with a request, it should return a 403 (forbidden) response.

The DCP protocol does not restrict applications to this simple challenge-response mechanism for access authentication. Additional mechanisms may be used, such as encryption at the transport level or via message encapsulation, and with additional header fields specifying authentication information. However, these additional mechanisms are not defined by this specification.

Proxies must be completely transparent regarding user agent authentication. That is, they must forward the WWW-Authenticate and Authorization headers untouched, and must not cache the response to a request containing Authorization. DCP does not provide a means for a client to be authenticated with a proxy.

A widely used authentication scheme is the Basic Authentication Scheme.


BASIC AUTHENTICATION SCHEME

The "basic" authentication scheme is a form of access authentication that is based on the model that the user agent must authenticate itself with a user-ID and a password for each realm. The realm value should be considered an opaque string which can only be compared for equality with other realms on that target. The target will authorize the request only if it can validate the user-ID and password for the protection space of the request URI. There are no optional authentication parameters.

Upon receipt of an unauthorized request for a URI within the protection space, the target should respond with a challenge like the following:

Example 

WWW-Authenticate: Basic realm = "DcpWorld"

where "DcpWorld" is the string assigned by the target to identify the protection space of the request URI.

To receive authorization, the initiator sends the user-ID and password, separated by a single colon (":") character, within a base64 [5] encoded string in the credentials.

Syntax
basicCredentials = "Basic" sp basicCookie
basicCookie = base64 encoding of userIdPassword, except not limited to 76 char/line
userIdPassword = [ token ] ":" *text

If the user agent wishes to send the user-ID "Aladdin" and password "open sesame", it would use the following header field:

Example 

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

The basic authentication scheme is a non-secure method of filtering unauthorized access to resources on an DCP target. It is based on the assumption that the connection between the initiator and the target can be regarded as a trusted carrier. As this is not generally true on an open network, the basic authentication scheme should be used accordingly. In spite of this, initiators should implement the scheme in order to communicate with targets that use it.

SECURITY CONSIDERATIONS

This section is meant to inform application developers, information providers, and users of the security limitations in DCP as described by this document. The discussion does not include definitive solutions to the problems revealed, though it does make some suggestions for reducing security risks.


AUTHENTICATION OF CLIENTS

As mentioned, the Basic authentication scheme is not a secure method of user authentication, nor does it prevent the entity body from being transmitted in clear text across the physical network used as the carrier. DCP does not prevent additional authentication schemes and encryption mechanisms from being employed to increase security.


SAFE METHODS

The writers of initiator software should be aware that the software represents the user in their interactions over the Internet, and should be careful to allow the user to be aware of any actions they may take which may have an unexpected significance to themselves or others.

In particular, the convention has been established that the get and subscribe methods should never have the significance of taking an action other than retrieving information. These methods should be considered "safe." This allows user agents to represent other methods, such as set, event, tether and call, in a special way, so that the user is made aware of the fact that a possibly unsafe action is being requested. Naturally, it is not possible to ensure that the target does not generate side-effects as a result of performing a get request; in fact, some dynamic resources consider that a feature. The important distinction here is that the user did not request the side effects, so therefore cannot be held accountable for them.


ABUSE OF LOG INFORMATION

A target is in the position to save personal data about a user's requests that may identify their patterns of DCP usage. This information is clearly confidential in nature and its handling may be constrained by law in certain countries. People using the DCP protocol to provide data are responsible for ensuring that such material is not distributed without the permission of any individuals that are identifiable by the published results.


TRANSFER OF SENSITIVE INFORMATION

Like any generic data transfer protocol, DCP cannot regulate the content of the data that is transferred, nor is there any a prior method of determining the sensitivity of any particular piece of information within the context of any given request. Therefore, applications should supply as much control over this information as possible to the provider of that information. Two header fields are worth special mention in this context: Target and Initiator-Agent.

Revealing the specific software version of the Target may allow the Target object to become more vulnerable to attacks against software that is known to contain security holes. Implementers should make the Target header field a configurable option.

The information sent in the Initiator-Agent field might conflict with the user's privacy interests or their site's security policy, and hence it should not be transmitted without the user being able to disable, enable, and modify the contents of the field. The user must be able to set the contents of this field within a user preference or application defaults configuration.


ATTACKS BASED ON OBJECT AND PATH NAME

Implementations of DCP origin targets should be careful to restrict the data returned by DCP requests to be only that that was intended by the target administrators. If an DCP target translates DCP URIs directly into object calls, the target must take special care not to serve deliver that was not intended to be delivered to DCP initiators. For example, Unix, Microsoft Windows, and other operating systems use ".." as a path component to indicate a directory level above the current one. On such a system, an DCP target must disallow any such construct in the request URI if it would otherwise allow access to a resource outside those intended to be accessible via the DCP target. Similarly, data intended for reference only internally to the target (such as access control data, configuration data) must be protected from inappropriate retrieval, since they might contain sensitive information.

XML DTD for DCP

Welcome to the DCP XML Document Type Definition. XML is a data format for structured document interchange on the Web. It is called the "extensible markup language" because it is not a fixed format like HTML. XML is designed to enable the use of SGML on the World Wide Web. XML is not a single markup language: it is a metalanguage that allows an author to design a markup language. A regular markup language defines a way to describe information in a certain class of documents (for example, HTML). With XML, authors can define their own customized markup language for many classes of documents.  These customized languages are defined by a Document Type Definition file or DTD.

The DCP Specification includes an XML Document Type Definition for DCP.  It can be used to describe device information such as properties, events and object models.  Please note that the architecture of DCP exhibits the abstraction of device data from the protocol itself.  As such, use of this DTD with DCP is not required. All that is required is that the recipient of the representation be able to understand and process it. For your reference, the XML DTD follows should you wish to use it.


DCP XML DTD

The extensible markup language (XML) document type definition (DTD) for DCP follows:

 
<!ELEMENT DCP (ObjectModel|Data)*>
<!ATTLIST DCP
Version NMTOKEN "1.0">

<!ELEMENT ObjectModel (Label?,Description?,Map?,Instances?)?>
<!ATTLIST ObjectModel
URL CDATA #IMPLIED>

<!ELEMENT Data (dObject|dProperty|dMethod|dEvent)*>
<!ATTLIST Data
URL CDATA #IMPLIED>

<!ELEMENT dObject (ParamValue*,(dObject|dProperty|dMethod|dEvent)*)?>
<!ATTLIST dObject
Value CDATA #IMPLIED
Href CDATA #IMPLIED
Name NMTOKEN #REQUIRED
SessionID NMTOKEN #IMPLIED
TransactionID NMTOKEN #IMPLIED>

<!ELEMENT ParamValue EMPTY>
<!ATTLIST ParamValue
Name NMTOKEN #REQUIRED
Value CDATA #REQUIRED>

<!ELEMENT dProperty EMPTY>
<!ATTLIST dProperty
Name NMTOKEN #REQUIRED
Value CDATA #IMPLIED
Href CDATA #IMPLIED
SessionID NMTOKEN #IMPLIED
TransactionID NMTOKEN #IMPLIED>

<!ELEMENT dMethod (dArg|dReturnValue)*>
<!ATTLIST dMethod
Name NMTOKEN #REQUIRED
SessionID NMTOKEN #IMPLIED
TransactionID NMTOKEN #IMPLIED>

<!ELEMENT dArg EMPTY>
<!ATTLIST dArg
Name NMTOKEN #REQUIRED
Value CDATA #IMPLIED
Href CDATA #IMPLIED>

<!ELEMENT dReturnValue EMPTY>
<!ATTLIST dReturnValue
Name NMTOKEN #REQUIRED
Value CDATA #IMPLIED
Href CDATA #IMPLIED>

<!ELEMENT dEvent (dEventParameter)*>
<!ATTLIST dEvent
Name NMTOKEN #REQUIRED
SessionID NMTOKEN #IMPLIED
TransactionID NMTOKEN #IMPLIED>

<!ELEMENT dEventParameter EMPTY>
<!ATTLIST dEventParameter
Name NMTOKEN #REQUIRED
Value CDATA #IMPLIED
Href CDATA #IMPLIED>

<!ELEMENT Argument (Label?,Description?,Rules*)?>
<!ATTLIST Argument
Name NMTOKEN #REQUIRED
Type (STRING|INT|FLOAT|BLOB|DATE|CHAR|MIME) #REQUIRED
MimeType NMTOKEN #IMPLIED
Size NMTOKEN #IMPLIED>

<!ELEMENT Label (#PCDATA)*>

<!ELEMENT Description (#PCDATA)*>

<!ELEMENT Rules (Item|Range)+>

<!ELEMENT Item (Label?,Description?)?>
<!ATTLIST Item
Include (Y|N) "Y"
Value CDATA #REQUIRED>

<!ELEMENT Range (Label?,Description?)?>
<!ATTLIST Range
Min CDATA #REQUIRED
Max CDATA #REQUIRED
Include (Y|N) "Y">

<!ELEMENT Property (Label?,Description?,Rules*)?>
<!ATTLIST Property
Name NMTOKEN #REQUIRED
Permissions (G|S|GS) "G"
Type (STRING|INT|FLOAT|BLOB|DATE|CHAR|MIME) #REQUIRED
MimeType NMTOKEN #IMPLIED
Size NMTOKEN #IMPLIED>

<!ELEMENT ReturnValue (Label?,Description?,Rules*)?>
<!ATTLIST ReturnValue
Name NMTOKEN #REQUIRED
Type (STRING|INT|FLOAT|BLOB|DATE|CHAR|MIME) #REQUIRED
MimeType NMTOKEN #IMPLIED
Size NMTOKEN #IMPLIED>

<!ELEMENT Attribute (Label?,Description?)?>
<!ATTLIST Attribute
Name NMTOKEN #REQUIRED
Value CDATA #IMPLIED>

<!ELEMENT Map (Object|Property|Method|Event|Attribute)*>

<!ELEMENT Object (Label?,Description?,InstanceParameter*,(Object|Property|Method|Event|Attribute)*)?>
<!ATTLIST Object
Name NMTOKEN #REQUIRED
DeviceHost (Y|N) "N"
Device (Y|N) "N">

<!ELEMENT InstanceParameter (Label?,Description?,Rules*)?>
<!ATTLIST InstanceParameter
Name NMTOKEN #REQUIRED
Type (STRING|INT|FLOAT|BLOB|DATE|CHAR|MIME) #REQUIRED
MimeType NMTOKEN #IMPLIED
Size NMTOKEN #IMPLIED>

<!ELEMENT Method (Label?,Description?,(Argument|ReturnValue)*)?>
<!ATTLIST Method
Name NMTOKEN #REQUIRED>

<!ELEMENT Event (Label?,Description?,EventParameter*)?>
<!ATTLIST Event
Name NMTOKEN #REQUIRED>

<!ELEMENT EventParameter (Label?,Description?,Rules*)?>
<!ATTLIST EventParameter
Name NMTOKEN #REQUIRED
Type (STRING|INT|FLOAT|BLOB|DATE|CHAR|MIME) #REQUIRED
MimeType NMTOKEN #IMPLIED
Size NMTOKEN #IMPLIED>

<!ELEMENT Instances (iObject)*>

<!ELEMENT iObject (ParamValue*,iObject*)?>
<!ATTLIST iObject
Name NMTOKEN #REQUIRED>