XCON WG C. Jennings
Internet-Draft Cisco Systems
Expires: August 12, 2005 A. B. Roach
Estacado Systems
February 11, 2005
Conference State Change Protocol (CSCP)
draft-jennings-xcon-cscp-00
Status of this Memo
This document is an Internet-Draft and is subject to all provisions
of section 3 of RFC 3667. By submitting this Internet-Draft, each
author represents that any applicable patent or other IPR claims of
which he or she is aware have been or will be disclosed, and any of
which he or she become aware will be disclosed, in accordance with
RFC 3668.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 12, 2005.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
Conference State Control Protocol (CSCP) is a means to modify the
state in a conference service. It extends the Binary Floor Control
Protocol and adds commands to get, set, add, and delete fields in the
conference state.
Jennings & Roach Expires August 12, 2005 [Page 1]
Internet-Draft Conference State Change Protocol February 2005
Table of Contents
1. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. New Primitives . . . . . . . . . . . . . . . . . . . . . . . . 3
4. New Attributes . . . . . . . . . . . . . . . . . . . . . . . . 4
4.1 ELEMENT-ID . . . . . . . . . . . . . . . . . . . . . . . . 4
4.2 NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4.3 VALUE . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5. Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5.1 Retrieving Attribute Values . . . . . . . . . . . . . . . 5
5.2 Setting Attribute Values . . . . . . . . . . . . . . . . . 6
5.3 Adding Elements . . . . . . . . . . . . . . . . . . . . . 7
5.4 Deleting an Element . . . . . . . . . . . . . . . . . . . 8
5.5 Deleting an Attribute . . . . . . . . . . . . . . . . . . 8
5.6 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 9
7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
9. Security Considerations . . . . . . . . . . . . . . . . . . . 10
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 10
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
11.1 Normative References . . . . . . . . . . . . . . . . . . . . 10
11.2 Informative References . . . . . . . . . . . . . . . . . . . 11
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 11
Intellectual Property and Copyright Statements . . . . . . . . 12
Jennings & Roach Expires August 12, 2005 [Page 2]
Internet-Draft Conference State Change Protocol February 2005
1. Conventions
This document extends the Binary Floor Control Protocol (BFCP) [2]
and makes no sense if you have not read that document. This document
uses the terminology from the conference framework. [TODO Reference]
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC-2119 [1].
2. Overview
CSCP is a client server protocol used to change the state of a
conference object. A client sends the server a request representing
a sequence of commands. Each command can set, get, add, or delete a
single field in the conference object. Changes to the conference
object are performed on a hierarchal set of elements and unique
attributes within those elements. A series of changes can be
pipelined in a single BFCP message. The server executes each action
in series. If one of them fails, the server returns an error for the
action that failed and does not execute any of the actions after
that. Each individual action is atomic but the pipelined series is
not.
The item that a command applies to is specified by a unique ID and,
where appropriate, attribute name. The ID is an unsigned 32 bit
integer called the Element ID. How the server discovers the element
ID of a given element is outside of CSCP. Typically this is done by
using the conferencing framework notification service. Each field in
the data received in the notification contains a unique field ID
attribute that can be used in BFCP requests.
The values for fields are transferred as UTF-8 encoded strings.
3. New Primitives
This documents updates Table 1 in BFCP with the following primitives:
11 GetRequest
12 GetInfo
13 SetRequest
14 SetAck
15 AddElementRequest
16 AddElementInfo
17 DelElementRequest
18 DelElementAck
19 DelAttributeRequest
Jennings & Roach Expires August 12, 2005 [Page 3]
Internet-Draft Conference State Change Protocol February 2005
20 DelAttributeAck
4. New Attributes
This document updates Table 2 in BFCP with the following new
attributes:
14 ELEMENT-ID
15 NAME
16 VALUE
4.1 ELEMENT-ID
The following is the format of a ELEMENT-ID attribute:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|0 0 0 0 1 1 0|M|0 0 0 1 1 0 0 0| Reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The reserved field MUST be set to 0 by the sender, and MUST be
ignored by the receiver.
Bytes within the "ID" field are transmitted in order of decreasing
significance. The ID values 0 and 0xFFFFFFFF are reserved and MUST
NOT be used.
4.2 NAME
The following is the format of a NAME attribute:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|0 0 0 0 1 0 1|M| Length | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| |
/ UTF-8 Text /
/ +-+-+-+-+-+-+-+-+
| | Padding |
Jennings & Roach Expires August 12, 2005 [Page 4]
Internet-Draft Conference State Change Protocol February 2005
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Text: this field contains UTF-8 [5] encoded text.
Padding: one, two, or three bytes of padding added so that the size
of the VALUE TLV is 32-bit aligned. The Padding bits SHOULD be set
to zero by the sender and MUST be ignored by the receiver. If the
TLV is already 32-bit aligned, no padding is included.
4.3 VALUE
The following is the format of a VALUE attribute:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|0 0 0 0 1 0 1|M| Length | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| |
/ UTF-8 Text /
/ +-+-+-+-+-+-+-+-+
| | Padding |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Text: this field contains UTF-8 [5] encoded text.
Padding: one, two, or three bytes of padding added so that the size
of the VALUE TLV is 32-bit aligned. The Padding bits SHOULD be set
to zero by the sender and MUST be ignored by the receiver. If the
TLV is already 32-bit aligned, no padding is included.
5. Behavior
5.1 Retrieving Attribute Values
Clients request the values of various fields by sending the
GetRequest message to the server. The following is the format of the
this message. A single GetRequest MUST not contain the same
{ELEMENT-ID,NAME} combination more than once; otherwise, it is not
possible to tell which of the multiple operations has caused an
error.
If the NAME field is omitted for a given ELEMENT-ID, then the request
applies to the CDATA associated with the indicated element.
Jennings & Roach Expires August 12, 2005 [Page 5]
Internet-Draft Conference State Change Protocol February 2005
GetRequest = (FIXED-HEADER)
(TRANSACTION-ID)
(USER-ID)
1*( (ELEMENT-ID)
[NAME] )
[NONCE]
[DIGEST]
The request contains all the ELEMENT-ID and NAME elements for the
fields the client wishes to retrieve. The values of the requested
fields are returned in a GetInfo message.
GetInfo = (FIXED-HEADER)
(TRANSACTION-ID)
(USER-ID)
1*( (ELEMENT-ID)
[NAME]
(VALUE) )
[NONCE]
Value is string encoding of the value. For fields that are an
integer, this is a base 10 encoded ASCII integer. For binary values
it is sent as the ASCII characters 0 and 1. (Open Issue: is this
totally goofy? should it be a binary type ?)
Open Issue: Is attribute retrieval actually necessary or even useful?
This protocol is predicated on the client having access to the
conference state via some other mechanism and is intended primarily
for manipulation of such state.
5.2 Setting Attribute Values
The SetRequest asks for the values of one or more fields to be
changed. A single SetRequest MUST not contain the same combination
of {ELEMENT-ID,NAME} more than once.
If the NAME field is omitted for a given ELEMENT-ID, then the request
applies to the CDATA associated with the indicated element.
If the SetRequest refers to an attribute which does not yet exist in
the indicated element, then that attribute is added and set to the
indicated value.
Jennings & Roach Expires August 12, 2005 [Page 6]
Internet-Draft Conference State Change Protocol February 2005
SetRequest = (FIXED-HEADER)
(TRANSACTION-ID)
(USER-ID)
1*( (ELEMENT-ID)
[NAME]
(VALUE) )
[NONCE]
[DIGEST]
If a SetRequest is successful, the server responds with a SetAck.
This SetAck contains the field ID and name for all fields which were
successfully set. If any of the fields are not successfully set, an
Error returns the value of the first field-id that failed.
SetAck = (FIXED-HEADER)
(TRANSACTION-ID)
(USER-ID)
*( (ELEMENT-ID)
[NAME] )
[NONCE]
5.3 Adding Elements
AddElementRequest = (FIXED-HEADER)
(TRANSACTION-ID)
(USER-ID)
(ELEMENT-ID)
(NAME)
[NONCE]
[DIGEST]
The AddElementRequest message contains a pairs of ELEMENT-ID/NAME
TLVs. The element id refers to an existing element; the new element
will be created as a child to the indicated element. The NAME field
indicates the name of the element that is to be added. If there is
an error in creating the field, an Error is returned; otherwise the
server sends an AddElementInfo containing the newly created
ELEMENT-ID. It is not possible to add multiple elements of the same
name in a single request because there is no way to correlate errors
with the addition that caused the error.
AddElementInfo = (FIXED-HEADER)
(TRANSACTION-ID)
Jennings & Roach Expires August 12, 2005 [Page 7]
Internet-Draft Conference State Change Protocol February 2005
(USER-ID)
(ELEMENT-ID)
[NONCE]
AddElementInfo returns the new Element ID for any elements that were
created.
5.4 Deleting an Element
DelElementRequest = (FIXED-HEADER)
(TRANSACTION-ID)
(USER-ID)
*(ELEMENT-ID)
[NONCE]
[DIGEST]
DelElementRequest requests that the server delete the specified
element and all of its attributes and children. If the
DelElementRequest is successful, the server responds with a
DelElementAck, which includes the list of deleted elements. If there
is an error, an error message with the ELEMENT-ID of the first field
that could not be deleted is returned.
DelElementAck = (FIXED-HEADER)
(TRANSACTION-ID)
(USER-ID)
*(ELEMENT-ID)
[NONCE]
[DIGEST]
5.5 Deleting an Attribute
DelAttributeRequest = (FIXED-HEADER)
(TRANSACTION-ID)
(USER-ID)
1*( (ELEMENT-ID)
[NAME] )
[NONCE]
[DIGEST]
DelAttributeRequest requests that the server delete the specified
attribute. Upon success, the server responds with a DelAttributeAck
with the list of deleted fields. If there is an error, an error
message with the ELEMENT-ID and NAME of the first field that could
Jennings & Roach Expires August 12, 2005 [Page 8]
Internet-Draft Conference State Change Protocol February 2005
not be deleted is returned.
If the NAME field is omitted for a given ELEMENT-ID, then the request
applies to the CDATA associated with the indicated element.
DelAttributeAck = (FIXED-HEADER)
(TRANSACTION-ID)
(USER-ID)
*( (ELEMENT-ID
[NAME] )
[NONCE]
[DIGEST]
5.6 Errors
The format of the Error messages is also modified to have optional
ELEMENT-ID and NAME TLVs. When these TLVs are present in an Error,
it indicates the element (and, where appropriate, attribute) in the
request that caused the error.
TO DO: This section needs more specification around the semantics of
error handling.
Error = (FIXED-HEADER)
(TRANSACTION-ID)
(USER-ID)
(ERROR-CODE)
[NONCE]
[HUMAN-READABLE-INFO]
[ELEMENT-ID]
[NAME]
6. Open Issues
Significant work remains on analyzing what error conditions can arise
from the operations defined in this document.
7. Examples
The document really needs an examples section. Much more work TODO
here. The basic idea that we need to convey is that one mechanism of
learning element IDs is having them included as part of an XML
document.
Jennings & Roach Expires August 12, 2005 [Page 9]
Internet-Draft Conference State Change Protocol February 2005
This XML would be discovered by using some other protocol such as a
SIP event package. The XML representations of state which this
protocol is intended to change could look something like:
<author id="1" initials="C." surname="Jennings"
fullname="Cullen Jennings">
<organization id="2">Cisco Systems</organization>
<address id="3">
<postal id="4">
<street id="5">170 West Tasman Drive</street>
<street id="6">Mailstop SJC-21/2</street>
<city id="7">San Jose</city>
<region id="8">CA</region>
<code id="9">95134</code>
<country id="10">USA</country>
</postal>
</address>
</author>
So, changing the fullname attribute of the <author> element to
"Cullen Fluffy Jennings" would be requested by sending a SetRequest
with ELEMENT-ID = 1, NAME = "fullname", and VALUE = "Cullen Fluffy
Jennings".
8. IANA Considerations
TBD
9. Security Considerations
TBD
10. Acknowledgments
This spot is reserved for your name. Send text now.
11. References
11.1 Normative References
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[2] Camarillo, G., "The Binary Floor Control Protocol (BFCP)",
draft-ietf-xcon-bfcp-03 (work in progress), January 2005.
Jennings & Roach Expires August 12, 2005 [Page 10]
Internet-Draft Conference State Change Protocol February 2005
11.2 Informative References
Authors' Addresses
Cullen Jennings
Cisco Systems
170 West Tasman Drive
Mailstop SJC-21/2
San Jose, CA 95134
USA
Phone: +1 408 421 9990
EMail: fluffy@cisco.com
Adam Roach
Estacado Systems
Dallas, TX
US
EMail: adam@estacado.net
Jennings & Roach Expires August 12, 2005 [Page 11]
Internet-Draft Conference State Change Protocol February 2005
Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Disclaimer of Validity
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Copyright Statement
Copyright (C) The Internet Society (2005). This document is subject
to the rights, licenses and restrictions contained in BCP 78, and
except as set forth therein, the authors retain all their rights.
Acknowledgment
Funding for the RFC Editor function is currently provided by the
Internet Society.
Jennings & Roach Expires August 12, 2005 [Page 12]