CONTENTS
[ Back ] [ Next ]
Click Here to visit the home page belonging to
the creator of DCP and get access to other downloads, including a
white paper on forward compatible
design for the Internet.
| |
|
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
|
|
|
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
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:
- 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. |
|
|
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
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.
|
|
|
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
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.
|
|
|
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
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.
|
|
|
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
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.
|
|
|
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
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.
|
|
|
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
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.
|
|
|
The Content-Base entity header field may be used to specify
the base URI for resolving relative URLs within the entity.
Syntax
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.
|
|
|
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
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.
|
|
|
The Content-Length entity header field indicates the size of
the message body, in decimal number of octets, sent to the recipient.
Syntax
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):
- 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.
- 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.
- 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.)
|
|
|
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
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.
|
|
|
The Content-Type entity header field indicates the media type of the entity body sent to
the recipient.
Syntax
Example
Content-Type: text/xml; charset=ISO-8859-4
|
|
|
The Date general header field represents the date and time
at which the message was originated having the semantics of dcpDate.
Syntax
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.
|
|
|
The Event-Subscription request header field must be included
in event requests. It provides information regarding the subscription to the event.
Syntax
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.
|
|
|
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
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:
- 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.
- If the variant has been changed since the If-Changed-Since date, the response is exactly
the same as for a normal GET.
- 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.
|
|
|
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
Example
Initiator-Agent: CERN-LineMode/2.15 libwww/2.17b3
|
|
|
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.
|
|
|
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
Example
Location: DCP://security.domain.com/Status
|
|
|
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.
|
|
|
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
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.
|
|
|
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
Example
Session-ID: XjG8982G444DFD
|
|
|
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
Example
Subscription-Port: 3000
|
|
|
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
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.
|
|
|
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
Example
Transaction-ID: XjG8982G444DFD
|
|
|
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
Example
Transaction-Type: Open-Loop
|
|
|
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
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.
|
|