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: Cisco Systems
170 West Tasman Drive Mailstop SJC-21/2 San Jose CA 95134 USA
So, changing the fullname attribute of the 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]