|
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.
|
|
|
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
|
|
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
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.
|
|
|
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
|
|
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
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.
|
|
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
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.
|
|
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
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.
|
|
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
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.
|
|
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
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.
|
|
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
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.
|
|
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
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.
|
|
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 service. Transactions 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
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.
|