XCON O. Novo Internet-Draft Ericsson Expires: June 12, 2006 C. Jennings Cisco Systems A. Roach Estacado Systems G. Camarillo Ericsson December 9, 2005 Conference State Change Protocol (CSCP) draft-jennings-xcon-cscp-02.txt Status of this Memo 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 becomes aware will be disclosed, in accordance with Section 6 of BCP 79. 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 June 12, 2006. 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 Novo, et al. Expires June 12, 2006 [Page 1] Internet-Draft Conference State Change Protocol December 2005 conference state. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4.3. VALUE . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5. Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 5.1. Retrieving Attribute Values . . . . . . . . . . . . . . . 6 5.2. Setting Attribute Values . . . . . . . . . . . . . . . . . 7 5.3. Adding Elements . . . . . . . . . . . . . . . . . . . . . 8 5.4. Deleting an Element . . . . . . . . . . . . . . . . . . . 9 5.5. Deleting an Attribute . . . . . . . . . . . . . . . . . . 9 5.6. Errors . . . . . . . . . . . . . . . . . . . . . . . . . . 10 6. Server Behaviour . . . . . . . . . . . . . . . . . . . . . . . 11 7. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 8. To Do Items . . . . . . . . . . . . . . . . . . . . . . . . . 13 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 9.1. Attribute Registration . . . . . . . . . . . . . . . . . . 13 9.2. Primitive Registration . . . . . . . . . . . . . . . . . . 13 9.3. Error Code Registration . . . . . . . . . . . . . . . . . 14 10. Security Considerations . . . . . . . . . . . . . . . . . . . 14 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 12.1. Normative References . . . . . . . . . . . . . . . . . . . 15 12.2. Informative References . . . . . . . . . . . . . . . . . . 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 Intellectual Property and Copyright Statements . . . . . . . . . . 17 Novo, et al. Expires June 12, 2006 [Page 2] Internet-Draft Conference State Change Protocol December 2005 1. Conventions This document extends the Binary Floor Control Protocol (BFCP) [1] and makes no sense if you have not read that document. This document uses the terminology from the conference framework[4]. 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 [2]. 2. Overview CSCP is a client server protocol used to change the state of a conference object. Note that the CSCP is just a protocol to manipulate the conference object. It is not a general XML protocol manipulation mechanism. 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 [1]. 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 [5]. 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 [3] encoded strings. 3. New Primitives This document updates Table 1 in BFCP [1] with the following primitives: Novo, et al. Expires June 12, 2006 [Page 3] Internet-Draft Conference State Change Protocol December 2005 +-------+--------------------+------------------+ | Value | Primitive | Direction | +-------+--------------------+------------------+ | 14 | GetRequest | P -> S ; Ch -> S | | 15 | GetInfo | P <- S ; Ch <- S | | 16 | SetRequest | P -> S ; Ch -> S | | 17 | SetAck | P <- S ; Ch <- S | | 18 | AddElementRequest | P -> S ; Ch -> S | | 19 | AddElementInfo | P <- S ; Ch <- S | | 20 | DelElementRequest | P -> S ; Ch -> S | | 21 | DelElementAck | P <- S ; Ch <- S | | 22 | DelAttributeRequest| P -> S ; Ch -> S | | 23 | DelAttributeAck | P <- S ; Ch <- S | +-------+--------------------+------------------+ S: Floor Control Server P: Floor Participant Ch: Floor Chair Table 1: CSCP primitives 4. New Attributes This document updates Table 2 in BFCP [1] and Table 1 in [6] with the following new attributes: +------+-----------------+---------------+ | Type | Attribute | Format | +------+-----------------+---------------+ | 19 | ELEMENT-ID | Unsigned32 | | 20 | NAME | OctetString | | 21 | VALUE | OctetString | +------+-----------------+---------------+ Table 2: CSCP attributes 4.1. ELEMENT-ID The following is the format of a ELEMENT-ID attribute: Novo, et al. Expires June 12, 2006 [Page 4] Internet-Draft Conference State Change Protocol December 2005 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 1 0 0 1 1|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. ID: This field contains a 32-bit value that uniquely identifies an element within a conference. 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 1 0 1 0 0|M| Length | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | / Text / / +-+-+-+-+-+-+-+-+ | | Padding | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Text: this field contains UTF-8 [3] encoded text. Padding: one, two, or three bytes of padding added so that the size of the VALUE attribute is 32-bit aligned. The Padding bits SHOULD be set to zero by the sender and MUST be ignored by the receiver. If the attribute is already 32-bit aligned, no padding is included. 4.3. VALUE The following is the format of a VALUE attribute: Novo, et al. Expires June 12, 2006 [Page 5] Internet-Draft Conference State Change Protocol December 2005 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 1 0 1 0 1|M| Length | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | / Text / / +-+-+-+-+-+-+-+-+ | | Padding | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Text: this field contains the 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: 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.] Padding: one, two, or three bytes of padding added so that the size of the VALUE attribute is 32-bit aligned. The Padding bits SHOULD be set to zero by the sender and MUST be ignored by the receiver. If the attribute is already 32-bit aligned, no padding is included. 5. Behavior 5.1. Retrieving Attribute Values Clients request the values of various attribute fields by sending the GetRequest message to the server. 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 request is not well-formed, the server sends the Error message code 3 (Unknown Primitive), as described in [1]. If the client inserts more than one ELEMENT-ID, the server will treat the request as an atomic package. That is, it will either send all the attributes information the client wishes to retrieve or sends an error message. If the NAME field is omitted for a given ELEMENT-ID, then the request applies to the CDATA associated with the indicated element. The following is the format of the message. Novo, et al. Expires June 12, 2006 [Page 6] Internet-Draft Conference State Change Protocol December 2005 GetRequest = (COMMON-HEADER) 1*( (ELEMENT-ID) [NAME]) 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. If the client is not authorized to perform the operation being requested, the Error message code 5 (Unauthorized Operation), as described in [1] is sent. If the client requests some attributes unknown from the server, the server sends the Error message 16 (Attribute could not be deleted). GetInfo = (COMMON-HEADER) 1*( (ELEMENT-ID) (NAME) (VALUE)) 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 request is not well- formed, the server sends the Error message code 3 (Unknown Primitive), as described in [1]. 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 client inserts more than one ELEMENT-ID, the server will treat the request as an atomic package. That is, it will either send all the attributes information the client wishes to retrieve or sends an error message. 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. SetRequest = (COMMON-HEADER) 1*( (ELEMENT-ID) [NAME] (VALUE)) Novo, et al. Expires June 12, 2006 [Page 7] Internet-Draft Conference State Change Protocol December 2005 If a SetRequest is successful, the server responds with a SetAck. This SetAck contains the ELEMENT-ID and NAME fields for all fields which were successfully set. If any of the fields cannot be successfully set, an Error Code 13 (One or more attributes could not be succesfully set) returns the value of the first ELEMENT-ID that failed. If the client is not authorized to perform the operation being requested, the Error message code 5 (Unauthorized Operation), as described in [1] is sent. SetAck = (COMMON-HEADER) 1*( (ELEMENT-ID) (NAME)) 5.3. Adding Elements The AddElementRequest message contains a pair of ELEMENT-ID/NAME attributes. The ELEMENT-ID field 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 the client is not authorized to perform the operation being requested, the Error message code 5 (Unauthorized Operation), as described in [1] is sent. AddElementRequest = (COMMON-HEADER) (ELEMENT-ID) (NAME) 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 = (COMMON-HEADER) (ELEMENT-ID) AddElementInfo returns the new ELEMENT-ID for any elements that were created. Otherwise, if there is an error in creating the field, an Error message with code 13 (Element can not be created) is returned; Novo, et al. Expires June 12, 2006 [Page 8] Internet-Draft Conference State Change Protocol December 2005 5.4. Deleting an Element DelElementRequest requests that the server delete the specified element and all of its attributes and children. DelElementRequest = (COMMON-HEADER) 1*(ELEMENT-ID) If the DelElementRequest is successful, the server responds with a DelElementAck, which includes the list of deleted elements. If the client is not authorized to perform the operation being requested, the Error message code 5 (Unauthorized Operation), as described in [1] is sent. DelElementAck = (COMMON-HEADER) 1*(ELEMENT-ID) DelElementAck returns the ELEMENT-ID for any elements that were deleted. Otherwise, if there is an error deleting any fields, an Error message with code 15 (Element can not be deleted) with the ELEMENT-ID of the first field that could not be deleted is returned. The server will treat the request as an atomic package. That is, it will either sends all the attributes information the client wishes to retrieve or sends an error message. 5.5. Deleting an Attribute DelAttributeRequest requests that the server delete the specified attribute. Upon success, the server responds with a DelAttributeAck with the list of deleted fields. DelAttributeRequest = (COMMON-HEADER) 1*( (ELEMENT-ID) [NAME]) If the client is not authorized to perform the operation being requested, the Error message code 5 (Unauthorized Operation), as described in [1] is sent. If the NAME field is omitted for a given ELEMENT-ID, then the request applies to the CDATA associated with the indicated element. Novo, et al. Expires June 12, 2006 [Page 9] Internet-Draft Conference State Change Protocol December 2005 DelAttributeAck = (COMMON-HEADER) 1*( (ELEMENT-ID) (NAME)) DelAttributeAck returns the ELEMENT-ID for any elements that were deleted. Otherwise, if there is an error deleting any fields, an Error message with code 16 (Attribute can not be deleted) with the ELEMENT-ID and NAME of the first field that could not be deleted is returned. The server will treat the request as an atomic package. That is, it will either sends all the attributes information the client wishes to retrieve or sends an error message. 5.6. Errors The format of the Error messages defined in [1] is also modified to have optional ELEMENT-ID and NAME attributes. When these attributes are present in an Error, it indicates the element (and, where appropriate, attribute) in the request that caused the error. Note that we use new ELEMENT-ID and NAME attributes in the Error messages instead of defining a Error Specific Details for this error codes. Error = (COMMON-HEADER) (ERROR-CODE) [ERROR-INFO] [ELEMENT-ID] [NAME] *[EXTENSION-ATTRIBUTE] The following is the definition of Error code meaning: +-------+----------------------------------------------------+ | Value | Meaning | +-------+----------------------------------------------------+ | 13 | One or more attributes could not be succesfully set| | 14 | Element could not be created | | 15 | Element could not be deleted | | 16 | Attribute could not be deleted | | 17 | Unknown Attribute | +-------+----------------------------------------------------+ Table 3: Error Code meaning Novo, et al. Expires June 12, 2006 [Page 10] Internet-Draft Conference State Change Protocol December 2005 6. Server Behaviour A conference server sending a notification to a client using the SIP event package [5] MUST included the ELEMENT-ID in every element of the XML document. The ELEMENT-ID values 0 and 0xFFFFFFFF are reserved and MUST NOT be used. It is RECOMMENDED that once an ELEMENT-ID value is used in an element within a conference, the same ELEMENT-ID value is not used in the same conference again in a different element. 7. Example The following is an example of a partial conference information document extracted from the SIP event package [5]. Each element in this example has a new attribute "index" that contains the value to be used in the ELEMENT-ID attribute of a CSCP message acting on that element. Agenda: This month's goals http://sharepoint/salesgroup/ web-page 33 Novo, et al. Expires June 12, 2006 [Page 11] Internet-Draft Conference State Change Protocol December 2005 Bob Hoskins Bob's Laptop disconnected departed 2005-03-04T20:00:00Z bad voice quality sip:mike@example.com main audio audio 432424 sendrecv Alice connected dialed-out 2005-03-04T20:00:00Z sip:mike@example.com main audio audio 534232 Novo, et al. Expires June 12, 2006 [Page 12] Internet-Draft Conference State Change Protocol December 2005 sendrecv So, changing the entity attribute of the element from "sip:bob@pc33.example.com" to "Cullen.Fluffy@example.com" would be requested by sending a SetRequest with ELEMENT-ID = 13, NAME = "entity", and VALUE = "Cullen.Fluffy@example.com". 8. To Do Items This needs to be lined up so that it can be correlated with the "SIP Event Package for Conference State" [5]. 9. IANA Considerations The following sections instruct the IANA to perform a set of actions. 9.1. Attribute Registration The IANA is instructed to register the following new values under the Attribute subregistry under the BFCP Parameters registry. +------+-----------------+-------------+ | Type | Attribute | Reference | +------+-----------------+-------------+ | 19 | ELEMENT-ID | [RFC XXXX] | | 20 | NAME | [RFC XXXX] | | 21 | VALUE | [RFC XXXX] | +------+-----------------+-------------+ Table 4: New values of the BFCP Attribute subregistry 9.2. Primitive Registration The IANA is instructed to register the following new values under the Primitive subregistry under the BFCP Parameters registry. Novo, et al. Expires June 12, 2006 [Page 13] Internet-Draft Conference State Change Protocol December 2005 +-------+--------------------+------------+ | Value | Primitive | Reference | +-------+--------------------+------------+ | 14 | GetRequest | [RFC XXXX] | | 15 | GetInfo | [RFC XXXX] | | 16 | SetRequest | [RFC XXXX] | | 17 | SetAck | [RFC XXXX] | | 18 | AddElementRequest | [RFC XXXX] | | 19 | AddElementInfo | [RFC XXXX] | | 20 | DelElementRequest | [RFC XXXX] | | 21 | DelElementAck | [RFC XXXX] | | 22 | DelAttributeRequest| [RFC XXXX] | | 23 | DelAttributeAck | [RFC XXXX] | +-------+--------------------+------------+ Table 5: New values of the BFCP Primitives subregistry 9.3. Error Code Registration The IANA is instructed to register the following new values under the Error Code subregistry under the BFCP Parameters registry. +-------+----------------------------------------------------+-----------+ | Value | Meaning | Reference | +-------+----------------------------------------------------+-----------+ | 13 | One or more attributes could not be succesfully set|[RFC XXXX] | | 14 | Element could not be created |[RFC XXXX] | | 15 | Element could not be deleted |[RFC XXXX] | | 16 | Attribute could not be deleted |[RFC XXXX] | | 17 | Unknown Attribute |[RFC XXXX] | +-------+----------------------------------------------------+-----------+ Table 6: New Values of the Error Code subregistry 10. Security Considerations The security considerations of [1] and [6] apply. This memo does not introduce any known additional security risk. 11. Acknowledgments Novo, et al. Expires June 12, 2006 [Page 14] Internet-Draft Conference State Change Protocol December 2005 Thanks to Roni Even for his comments. 12. References 12.1. Normative References [1] Camarillo, G., "The Binary Floor Control Protocol (BFCP)", draft-ietf-xcon-bfcp-06 (work in progress), December 2005. [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [3] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. 12.2. Informative References [4] Barnes, M. and C. Boulton, "A Framework and Data Model for Centralized Conferencing", draft-barnes-xcon-framework-02 (work in progress), February 2005. [5] Rosenberg, J., "A Session Initiation Protocol (SIP) Event Package for Conference State", draft-ietf-sipping-conference-package-12 (work in progress), July 2005. [6] Camarillo, G., "Connection Establishment in the Binary Floor Control Protocol (BFCP)", draft-ietf-xcon-bfcp-connection-00 (work in progress). Novo, et al. Expires June 12, 2006 [Page 15] Internet-Draft Conference State Change Protocol December 2005 Authors' Addresses Oscar Novo Ericsson Hirsalantie 11 Jorvas 02420 Finland Email: Oscar.Novo@ericsson.com 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 Gonzalo Camarillo Ericsson Hirsalantie 11 Jorvas 02420 Finland Email: Gonzalo.Camarillo@ericsson.com Novo, et al. Expires June 12, 2006 [Page 16] Internet-Draft Conference State Change Protocol December 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. Novo, et al. Expires June 12, 2006 [Page 17]