New: 6.2.4.3 "modify" Command

[Doug Royer <Doug@xxxxxxxxx>]

6.2.4.3 "modify" Command
   
   Attributes:
   
         "id" (see Section 6.2.2.1).

         "target" (see xxx)

         "latency" and "action" (Optional - see xxx)

         One of the following "request-status" codes MUST be returned:

               2.0 - successfully modified the component or calendar

               6.1 - Container not found

               6.3 - Bad args

   The "modify" command is used to modify existing components.  The
   "target" attribute specifies the calendars were the components
   exist that are going to be modified.

   The format of the request is three containers inside of VCALENDAR 
   container object:

	BEGIN:VCALEDNAR
	<VQUERY>
	<OLD-VALUES>
	<NEW-VALUES>
	END:CALENDAR

  The VQUERY selects the components that are to be modified.

  The OLD-VALUES is a component and the contents of that component
  are going to change and may contain information that helps uniquely
  identify the original component (SEQUENCE in the example below).
  If the CS can not find a component that matches the QUERY and does
  not have at least all of the OLD-VALUES, then a 6.1 error is returned.

  The NEW-VALUES is a component of the same type as OLD-VALUES and
  NEW-VALUES contains the new data for each selected component. Any
  data that is in OLD-VALUES and not in NEW-VALUES is deleted from
  the selected component.
 
  In this example the VEVENT with UID:unique-58 has; the LOCATION and
  LAST-MODIFIED  changed, the VALARM with SEQUENCE:3 has its
  TRIGGER disabled, and the X-LOCAL property is removed from the VEVENT.
  Because SEQUENCE is used to locate the VALARM in this example,
  both the OLD-VALUES and the NEW-VALUES contains SEQUENCE:3 and
  if SEQUENCE was left out of NEW-VALUES - it would have been deleted.

  Example:

  C: MSG 2 4 , 0 543
  C: Content-Type: application/cap+xml
  C:
  C: <modify target='my-cal'>
  C: <![CDATA[
  C: BEGIN:VCALENDAR
  C: VERSION:2.0
  C: TARGET:my-cal
  C: METHOD:MODIFY
  C: BEGIN:VQUERY
  C: QUERY:SELECT * FROM VEVENT WHERE UID = 'unique-58'
  C: END:VQUERY
  C: BEGIN:VEVENT
  C: LOCATION:building 3
  C: LAST-MODIFIED:20020101T123456Z
  C: X-LOCAL:some private stuff
  C: BEGIN:VALARM
  C: SEQUENCE:3
  C: TRIGGER;RELATED=END:PT5M
  C: END:VALARM
  C: END:VEVENT
  C: BEGIN:VEVENT
  C: LOCATION:building 4
  C: LAST-MODIFIED:20020202T010203Z
  C: BEGIN:VALARM
  C: SEQUENCE:3
  C: TRIGGER;ENABLE=FALSE:RELATED=END:PT5M
  C: END:VALARM
  C: END:VEVENT
  C: />]]>
  C: </modify>
  C: END

  X-LOCAL was not supplied in the NEW-VALUES, so it was deleted.
  LOCATION was altered, as was LAST-MODIFIED. The VALARM with
  SEQUENCE:3 had its TRIGGER disabled, and SEQUENCE did not
  change so it was not effected.


  When it comes to inline ATTACHMENTs, the CUA only needs to uniquely
  identify them in the OLD-VALUES to delete them. When the CS compares
  the attachment data it is compared in it binary form. The ATTACHMENT
  value supplied by the CUA MUST BE valid encoded information.

  For example, to delete a huge inline attachment from every
  VEVENT in 'my-cal' that has an ATTACH with the OLD-VALUES:

	BEGIN:VCALENDAR
	VERSION:2.0
	TARGET:my-cal
	METHOD:MODIFY
	BEGIN:VQUERY
	QUERY:SELECT ATTACH FROM VEVENT
	END:VQUERY
	BEGIN:VEVENT
      	ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY:
	 MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U
	 EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE
	 ...<remander of attachment data NOT supplied> ....
	END:VEVENT
	BEGIN:VEVENT
	END:VEVENT
	END:VCALENDAR

   Above the NEW-VALUES is empty, so everything in the OLD-VALUES
   is deleted.

   Furthermore, the following additional restrictions apply:

         One can not change the "UID" property of a component.
 
         If a contained component is changed inside of a selected
         component, and that contained component has multiple
         instances, then OLD-VALUES MUST contain information that
         uniquely identifies the instance or instances that are
changing.
         As all contained components that matching OLD-VALUES will be
         modified. In the first modify example above, if SEQUENCE were
         to be deleted from both the OLD-VALUES and NEW-VALUES, then all
         TRIGGERs that matched the OLD-VALUES in all VALARM in the
         selected VEVENTs would be disabled.

         The result of the modify MUST BE a valid iCalendar object.

   If the REQUEST-STATUS is 2.0, then the entire modification was
   successful.

   If any error occurred:

	No component will not be changed at all. That is, it will
        appear just as it was prior to the modify and the CAP server
        SHOULD return a REQUEST-STATUS for each error that occurred.

	There MUST BE at least one error reported.

   If multiple components are selected, then the UID for each selected
   component MUST BE returned:

   S: RPY 1 7 . 3752 156
   S: Content-Type: application/cap+xml
   S:
   S: <reply>
   S: <request-status code="2.0">
   S: UID:1
   S: </request-status>
   S: <request-status code="2.0">
   S: UID:2
   S: </request-status>
   S: </reply>
   S: END

begin:vcard 
n:Royer;Doug
tel;pager:pager@xxxxxxxxx
tel;cell:208-520-4044
tel;fax:866-594-8574
tel;work:866-594-8574
x-mozilla-html:FALSE
url:http://Royer.com/People/Doug
org:INET-Consulting LLC <http://INET-Consulting.com
adr:;;;;;;
version:2.1
email;internet:Doug@xxxxxxxxx
title:Chief Executive Manager
x-mozilla-cpt:;64
fn:Doug Royer
end:vcard