//////////////////////////////////////////////////////////////////////
// DATETIME Elements are specified as follows:
//
//
// <s DATETIME> means:
//
// <s d="YYYYMMDD['T'HHMMSS[Z]]" [tz="timezone_identifier"]>
//
//    YYYY - 4 digit year
//    MM   - 2 digit month
//    DD   - 2 digit day
//  Optionally:
//    'T' the literal char "T" then
//    HH - 2 digit hour (00-23)
//    MM - 2 digit minute (00-59)
//    SS - 2 digit second (00-59)
//    ...and finally an optional "Z" meaning that the time is UTC,
//    otherwise the tz="TIMEZONE" param MUST be specified with the DATETIME
//
// e.g:
//     20050612  June 12, 2005
//     20050315T18302305Z  March 15, 2005 6:30:23.05 PM UTC
//
//
// tz="java timezone identifier" (see list at bottom of this file!)
//
//
// NOTE: if DATETIME has a time component (after the 'T') then it must either be specified
// in UTC (has a trailing 'Z') or else the tz= MUST be specified!!!
//

//////////////////////////////////////////////////////////////////////
// "DURATION" element  (specified-duration)
//
//  <dur [neg="1|0"] [w="weeks"] [d="days"] [h="hours"] [m="mins"] [s="secs"]>
//
// Special note: if WEEKS are specified, NO OTHER OFFSET MAY BE
// SPECIFIED (weeks must be alone, per RFC2445)
//


//////////////////////////////////////////////////////////////////////
//
// CREATEAPPOINTMENT
// -----------------
//    This is the API to create a new Appointment, optionally  sending out
//  meeting Invitations to other people.
//
<CreateAppointmentRequest
    [echo="1"]  // if specified, the created appointment is echoed back in the response as if a GetMsgRequest was made
    [max="{max-inlined-length}"] [html="*0|1"] [neuter="0|*1"]  // options for echoing
    [forcesend="0|1"] // if set to 1, ignore smtp 550 errors when sending the notification to attendees. The default is 1.
                      // if set to 0, throw the soapfaultexception with invalid addresses so that client can give forcesend option to enduser. 
>
  <m f="{flags}" l="{folder}">  // See soap.txt for complete list of attrs on <m>
     [<e .../>*]  // users to send request to
     <su>{subject}</su>

     <inv>
       [                            // Time zone components define the time zones referenced in the
                                    // rest of the <inv>, for start/end times and recurrence rules.
                                    // Time zones defined in the LDAP server don't need to be defined
                                    // here, but all custom time zones must be defined before being
                                    // referenced.
       <tz
           id="tzid"                // this name is referenced in various DATETIME data in the rest of <inv>
           stdoff="<minutes>"       // offset from UTC in standard time; local = UTC + offset
           [dayoff="<minutes>"]     // offset from UTC in daylight time; present only if DST is used
           [stdname="abbrev"]       // abbreviated name for standard time (e.g. PST)
           [dayname="abbrev"]       // abbreviated name for daylight time (e.g. PDT)
       >
           [                        // If daylight savings time is not used, <standard> and <daylight> must be
                                    // omitted.  If DST is used, both <standard> and <daylight> must be present.
           <standard                // time/rule for transitioning from daylight time to standard time
                                    // Either specify week/wkday combo, or mday.
               [
               week="<number>"        // week number; 1=first, 2=second, 3=third, 4=fourth, -1=last
               wkday="<number>"       // day of week; 1=Sunday, 2=Monday, etc.
               ]
               mon="<number>"         // month; 1=January, 2=February, etc.
               [mday="<number>"]      // day of month (1..31)
               hour="<number>"        // transition hour (0..23)
               min="<number>"         // transition minute (0..59)
               sec="<number>"         // transition second; 0..59, usually 0
           />
           <daylight                // time/rule for transitioning from standard time to daylight time
               [
               week="<number>"
               wkday="<number>"
               ]
               mon="<number>"
               [mday="<number>"]
               hour="<number>"
               min="<number>"
               sec="<number>"
           />
           ]?
       </tz>
       ]*  // always present in responses; optional in requests if all TZs used
           // in <inv> are defined in LDAP
       [
       <comp
            [uid="uid-for-create"]  // optional: client can request the UID to use
            [status="TENT|CONF|CANC|NEED|COMP|INPR|WAITING|DEFERRED"]
                            // TENTative, CONFirmed, CANCelled, COMPleted,
                            // INPRogress, WAITING, DEFERRED
                            // Waiting and Deferred are custom values not found
                            // in iCalendar spec.
            [fb="F|B|T|O"]  // free-busy status:
                               Free, Busy (default), busy-Tentative, OutOfOffice (busy-unavailable)
            fba="F|B|T|O" // the "actual" free-busy status of this invite (ie what the client should display) -- this is synthesized taking into account our Attendee's PartStat, the Opacity of the appointment, its Status, etc...
            [transp="O|T"]  // transparency: Opaque (default) or Transparent
            [class="PUB|PRI|CON"]  // class: PUBlic (default), PRIvate, CONfidential
            [allDay="1|0"]
            [name="NAME"]
            [loc="LOCATION"]
            [isOrg="0|1"]		// Am I the organizer?  (default = 0)
            [seq="num"]         // sequence number (default = 0)
            [priority="num"]    // priority (0 - 9; default = 0)
            [percentComplete="num (integer)"]  // percent complete for VTODO (0 - 100; default = 0)
            [completed="yyyyMMddThhmmssZ"]  // VTODO COMPLETED DATE-TIME
            [url="url"]         // URL
            [noBlob="1"]        // set if invite has no blob data, i.e. all data is in db metadata
            [changes="comma-separated list of changed data in an updated invite"]
                // Possible values are "subject", "location", "time" (start time, end time, or duration), and "recurrence".
            [draft="0|1"]       // set to 1 if invite has changes that haven't been sent to attendees; for organizer only
            [neverSent="0|1"]   // set to 1 if attendees have never been notified for this invite; for organizer only, used in SetAppointmentRequest only
        >

           <s DATETIME> // Start date-time (required)

           (
              <e DATETIME> // End date-time
              OR
              <dur DURATION>   //<dur [neg="1|0"] [w="weeks"] [d="days"] [h="hours"] [m="mins"] [s="secs"]>  
           )   // one is required

           [<desc>DESCRIPTION</desc>]               // present if noBlob=1 and invite has plain text description
           [<descHtml>HTML description</descHtml>]  // present if noBlob=1 and invite has html description

           // organizer
           <or a="address"         // email address (without "MAILTO:")
               d="friendly name"   // CN in iCalendar
               [sentBy="sent-by"]  // SENT-BY
               [dir="dir"]         // DIR
               [lang="language"]   // LANGUAGE (e.g. "en-US")
               [<xparam name="x-name" [value="text"]/>]*  // non-standard parameters
           />
           // attendee(s)
           <at a="address"                  // email address (without "MAILTO:")
               d="friendly name"            // CN in iCalendar
               [sentBy="sent-by"]           // SENT-BY
               [dir="dir"]                  // DIR
               [lang="language"]            // LANGUAGE (e.g. "en-US")
               role="ROLE"                  // ROLE
               ptst="participation status"  // PARTSTAT
               [rsvp="0|1"]                 // RSVP
               [cutype="CUTYPE"]            // CUTYPE
               [member="MEMBER"]            // MEMBER
               [delTo="delegated to"]       // DELEGATED-FROM
               [delFrom="delegated from"]   // DELEGATED-TO
               [<xparam name="x-name" [value="text"]/>]*  // non-standard parameters
           />*
             // role = CHAir, REQuired, OPTional, NON-participant (ie informational)
             // ptst (ParTSTat - participation status) = "NE"eds-action, "TE"ntative, "AC"cept, "DE"clined,
             // "DG" (delegated), "CO"mpleted (todo), "IN"-process (todo),
             // "WA"iting (custom value only for todo), "DF" (deferred; custom value only for todo)
             // cutype (calendar user type) = INDividual, GROup, RESource, ROOm, UNKnown
             // sentBy, member, delTo and delFrom values are email addresses

           // CATEGORIES
           [<category>CATEGORY</category>]*
           // COMMENTs
           [<comment>COMMENT</comment>]*
           // CONTACTs
           [<contact>CONTACT</contact>]*
           // GEO
           [<geo lat="LATITUDE (float value)" lon="LONGITUDE (float value)"/]

           [
             <recur>  // see below
                [ <add|exclude>
                    [ <rule freq="FREQ"
                         // FREQ: SEC,MIN,HOU,DAI,WEE,MON,YEA

                      [
                        <until d="YYYYMMDD[ThhmmssZ]/> // UNTIL *MUST* be Date value or DateTime in UTC w/ trailing 'Z' 
                               OR
                        <count num="COUNT"/> // count of instances to generate
                      ]? // optional UNTIL or COUNT param

                      
                      [  // each of the following can occur at most once
                        <interval ival="COUNT"/>                  // COUNT: positive integer
                        <bysecond seclist="second[,second...]"/>  // second: 0 to 59
                        <byminute minlist="minute[,minute...]"/>  // minute: 0 to 59
                        <byhour hrlist="hour[,hour...]"/>         // hour: 0 to 23
                        <byday>
                          <wkday [ordwk="[[+]|-]num"] day="WEEKDAY"/>  // num: 1 to 53, WEEKDAY: SU,MO,TU,WE,TH,FR,SA
                          [<wkday>...]
                        </byday>
                            // e.g. <byday>
                            //        <wkday day="MO"/>
                            //        <wkday ordwk="3" day="TU"/>
                            //        <wkday ordwk="+4" day="WE"/>
                            //        <wkday ordwk="-1" day="SU"/>
                            //      </byday>
                            //
                            // means every Monday of the year,
                            // plus Tuesday of 3rd week of the year,
                            // plus Wednesday of 4th week,
                            // plus Sunday of last week of the year.
                        <bymonthday modaylist="[[+]|-]num[,...]"/>   // num: 1 to 31
                            // e.g. <bymonthday modaylist="1,+2,-7"/>
                            // means first day of the month, plus the 2nd day of the month,
                            // plus the 7th from last day of the month.
                        <byyearday yrdaylist="[[+]|-]num[,...]"/>    // num: 1 to 366
                            // e.g. <byyearday yrdaylist="1,+2,-1"/>
                            // means January 1st, January 2nd, and December 31st.
                        <byweekno wklist="[[+]|-]num[,...]"/>   // num: 1 to 53
                            // e.g. <byweekno wklist="1,+2,-1"/>
                            // means first week, 2nd week, and last week of the year.
                        <bymonth molist="month[,month...]"/>      // month: 1 to 12
                        <bysetpos poslist="[[+]|-]num[,...]"/>    // poslist: 1 to 366
                            // <bysetpos> MUST only be used in conjunction with another
                            // <byXXX> element.
                        <wkst day="WEEKDAY"/>  // WEEKDAY: SU,MO,TU,WE,TH,FR,SA
                      ]*
                      [
                        <x-name name="NAME" value="VALUE"/>  // custom fields
                      ]*
                    </rule>]*

					// RDATE/EXDATE
                    [ <dates [tz="TZID"]>
                        // Start DATE-TIME only.  Instance has same duration as
                        // the default duration.
                        // RDATE[;VALUE=DATE-TIME][;TZID=...]:val,val,val,...
                        <dtval>
                          <s d="YYYYMMDDThhmmss[Z]"/>
                        </dtval>*
                      </dates>
                    ]*
                    [ <dates [tz="TZID"]>
                        // Start DATE only. (all-day)  Instance has same
                        // duration as the default duration.
                        // RDATE;VALUE=DATE[;TZID=...]:val,val,val,...
                        <dtval>
                          <s d="YYYYMMDD"/>
                        </dtval>*
                      </dates>
                    ]*
                    [ <dates [tz="TZID"]>
                        // Start date/time and either end date/time or duration.
                        // Only DATE-TIME format is allowed for start/end.
                        // This format is allowed in <add> only, but not in
                        // <exclude>.
                        // RDATE;VALUE=PERIOD[;TZID=...]:val,val,val,...
                        <dtval>
                          <s d="YYYYMMDDThhmmss[Z]"/>
                          <e d="YYYYMMDDThhmmss[Z]"/> OR <dur ...>
                        </dtval>*
                      </dates>
                    ]*
                  </add|/exclude>

                  ////////////
                  //
                  // These next two (<except> and <cancel>) are only valid for APIs that deal with the
                  // entire appointment such as SetAppointment and GetAppointment: they are IGNORED by
                  // other APIs. 
                  [
                    <except recurId="INSTANCE_START_SECS_GMT" rangeType="RANGETYPE">
                      <add|exclude>
                        ...SAME AS ABOVE...
                      </add|/exclude>      
                    </except>
                  ]*
                  [
                    <cancel recurId="INSTANCE_START_SECS_GMT" rangeType="RANGETYPE"/>
                  ]*
                ]*
             </recur>
           ]

           // VALARMs (RFC2445 Section 4.6.6)
           [
             <alarm action="DISPLAY">
               <trigger>
                 // <rel> has the same attributes as <dur> and an optional
                 // "related" attribute.  Default value of "related" is "START".
                 <rel [related="START|END"] .../> OR <abs d="YYYYMMDDThhmmssZ"/>
               </trigger>
               <desc>{reminder text to display}</desc>
               // <repeat> has the same attributes as <dur> and an additional
               // required count attribute.  The duration is how often to repeat
               // the alarm, and the count is how many times to trigger the
               // alarm IN ADDITION TO the initial alarm.
               [<repeat count="N" .../>]
               [<xprop name="x-name" [value="text"]>
                 [<xparam name="x-name" [value="text"]/>]*
                </xprop>]*
             </alarm>
           ]*
           [
             <alarm action="AUDIO">
               <trigger/>      // same as in DISPLAY alarm
               [<repeat/>]     // same as in DISPLAY alarm
               [
                 <attach ct="{content type}" uri="{uri}"/>
                 OR
                 <attach>{base64-encoded binary data}</attach>
               ]
               [<xprop name="x-name" [value="text"]>
                 [<xparam name="x-name" [value="text"]/>]*
                </xprop>]*
             </alarm>
           ]*
           [
             <alarm action="EMAIL | X-YAHOO-ACTION-IM | X-YAHOO-ACTION-MOBILE">
               <trigger/>      // same as in DISPLAY alarm
               [<repeat/>]     // same as in DISPLAY alarm
               <desc>{email body}</desc>
               <summary>{email subject}</summary>
               <at .../>+      // attendees (one or more email recipients)
               [<attach ... />]  // sam as in AUDIO alarm
               [<xprop name="x-name" [value="text"]>
                 [<xparam name="x-name" [value="text"]/>]*
                </xprop>]*
             </alarm>
           ]*
           [
             <alarm action="PROCEDURE">
               <trigger/>      // same as in DISPLAY alarm
               [<repeat/>]     // same as in DISPLAY alarm
               [<desc>{description test}</desc>]
               <attach ... />  // same as in AUDIO alarm
               [<xprop name="x-name" [value="text"]>
                 [<xparam name="x-name" [value="text"]/>]*
                </xprop>]*
             </alarm>
           ]*

           [
             // non-standard properties (see RFC2445 section 4.8.8.1)
             // e.g.
             // iCalendar:
             //
             //   X-FOO-HELLO;X-FOO-WORLD=world:hello
             //
             // SOAP:
             //
             //   <xprop name="X-FOO-HELLO" value="hello">
             //     <xparam name="X-FOO-WORLD" value="world"/>
             //   </xprop>
             <xprop name="x-name" [value="text"]>
               [<xparam name="x-name" [value="text"]/>]*
             </xprop>
           ]*
        </comp>
        ]+     
     </inv>
     <mp>...</mp>
     [<content (url="{url}")>...</content>]
   </m>
</CreateAppointmentRequest>


// CREATING EXCEPTIONS
// --------------------
//
// Just like CreateAppointment, except that instead of specifying a target FOLDER, you
// specify an existing PID and component-number
//
// *** If id= and comp= are set, then you are creating an EXCEPTION:
//
//   The default invite for the appointment MUST have a recurrence rule....
//      otherwise you should just be using ModifyAppointment!
//
//   EXCEPTION_ID is start-time for the particular instance you are overriding
//     EXCEPTION_ID MUST be some instance that matches the default-invite for
//     the appointment...that is, it MUST NOT BE the start time of the exception!
//
//   **The above is important**   So let me explain:
//
//   Given an appointment, happens every Wednesday @ 9am, with an exception that moves
//      it to 10am on 6/22
//
//   So our instances for June, 2005  are:
//       6/1 9am
//       6/8 9am
//       6/15 9am
//       6/22 10am (an existing EXCEPTION)
//       6/29 9am
//
//  So, if a user clicks on the 6/22 10am appointment and wants to modify it, you MUST NOT
//  try to use <CreateAppointmentExceptionRequest> to modify it!
//  You MUST use ModifyAppointmentRequest instead!!!
//
//  On the other hand, if a user clicks on the 6/15 9am appointment and wants to modify it,
//  then this is the right API to use.
//
<CreateAppointmentException [id="ID_DEFAULT_INVITE" comp="COMP_DEFAULT_INVITE"] 
    [forcesend="0|1"] // if set to 1, ignore smtp 550 errors when sending the notification to attendees. The default is 1.
                      // if set to 0, throw the soapfaultexception with invalid addresses so that client can give forcesend option to enduser. 
>
  <m f="{flags}" l="{folder}">
     ...
     <inv [uid="uid-for-create"]>  // optional: client can request the UID to use
       [
         <exceptId DATETIME> // EXCEPTION_ID -- this is the DateTime of some instance in the default appointment
         ...
      </inv>
   </m>
</CreateAppointmentException>
         




----------------------
RECURRENCE SPECIFIERS!

 <recur> holds a recurence.  Note that the initial instance is NOT specified by <recur>, it is implied
    by the s= and (e=|dur=) parameters.  The initial instance may NOT be modified by an <exclude> parameter
    inside a <recur>
 <add>      - dates or rules which ADD instances.  ADDs are evaluated before EXCLUDEs
 <exclude>  - dates or rules which EXCLUDE instances.  
 <date>     - an SDATE that is added or excluded.  D+DATE values may ONLY be used if this is an all-day-event!
 <rule>     - a RULE for specifying added/exluded instances
 <freq>     - "SEC","MIN","HOU","DAI","WEE","MON","YEA" - event happens every INTERVAL Seconds/Minutes/Hours/etc.
 <ival>     - Default is 1.  Number of (secs/mins/hours/etc)  between occurences.
 <until>    - INCLUSIVE date to stop (ie if there is a recurrence on that date, it IS added to list
 <count>    - number of occurences to be generated by this rule
 <bymonth>,<byweekno>.... --- TODO 
----------------------

<CreateAppointmentResponse calItemId="APPOINTMENT-ID" invId="invite-message-id" ms="change-sequence" rev="revision">
  [<echo><m .../></echo>]  // if echo="1" was specified in the request
</CreateAppointmentResponse>


//////////////////////////////////////////////////////////////////////
//
// Directly set status of an entire appointment.  This API is intended
// for mailbox Migration (ie migrating a mailbox onto this server) and
// is not used by normal mail clients.
//
//   need to specifiy folder for appointment
//
//   need way to add message WITHOUT processing it for calendar parts.
//   need to generate and patch-in the iCalendar for the <inv> but w/o
//   actually processing the <inv> as a new request
//
//   TODO: need way to link message to appointment after the fact
//
//
<SetAppointmentRequest
    [l="folder_to_create_in"] [f="flags"] [t="tags"]
    [noNextAlarm="1"]  // means all alarms have been dismissed; if this is set, nextAlarm should not be set
    [nextAlarm="next alarm will go off at"]  // if specified, time when next alarm should go off
                                             // if missing, two possibilities:
                                             // 1) if noNextAlarm isn't set, keep current next alarm time
                                             //    (this is backward compatibility case)
                                             // 2) if noNextAlarm=1, indicates all alarms have been dismissed
>
  <default
      ptst="NE|AC|TE|DE|DG|CO|IN"  // my participation status
  >
     <m [aid="{uploaded-MIME-body-ID}"] > ...see CreateAppointmentRequest...
**************
ONE OF:        
   1) XML <inv> format from CreateAppointment 
        <inv>
          <comp>
            ...
            <exceptId DATETIME> // EXCEPTION_ID -- this is the DateTime of some instance in the default appointment
            ...
          </comp>
        </inv>
        <mp ct="content type">
          meeting notes parts
        </mp>
OR
   2) Raw MimeMessage import:
       <mp ct="content type">
         <content>
           RAW RFC822 MESSAGE (XML-encoded)  ***MUST CONTAIN A text/calendar PART***  
         </content>
       </mp>
       [<inv> ... </inv] -- optional, overrides the text/calendar from the inlined message body
OR
   3) Raw MimeMessage uploaded as attachment ID (see AddMsgRequest in soap.txt)
       [<inv> ... </inv] -- optional, overrides the text/calendar from the referenced uploaded message body
*************
     </m>
  </default>
  [<except
      ptst="NE|AC|TE|DE|DG|CO|IN"  // my participation status
   >
     <m> Same as under <default> above  
        ...
        **1 of the 3 forms above**
     </m>
  </except>]*
  [<cancel>
     <m> Same as under <default> above  
        ...
        **1 of the 3 forms above**
        
        If using <inv> form, these elements and attributes must be present:

        <inv>
		  [<tz>...</tz>]*
          <comp
                d="{date}"
                uid="{UID}"
                seq="{sequence}"  // must be incremented from original sequence
                [name="{name}]
                [allDay="{allDay}"]>
            <exceptId ...>  // RECURRENCE-ID
            <s ...>         // DTSTART
            <or ...>        // ORGANIZER
            <at ...>+       // ATTENDEEs
          </comp>
        </inv>
        <mp ct="content type">meeting notes parts</mp>
        
        All others are ignored.
     </m>
  </cancel>]*

  // List of replies received from attendees.  If SetAppointmenRequest doesn't contain <replies>
  // block, existing replies will be kept.  If <replies/> element is provided with no <reply>
  // elements inside, existing replies will be removed, replaced with an empty set.  If <replies>
  // contains one or more <reply> elements, existing replies are replaced with the ones provided.
  [<replies>
     [<reply d="TIMESTAMP_OF_REPLY"
             at="foo@bar.com"        // address of attendee who replied
             ptst="AC|DE|TE|NE"      // accepted, declined, etc.
             [  // present if reply is to an instance in a recurrence
              recurId="YYMMDD[THHMMSS[Z]]"
              [tz="timezonename"]
             ]
     />]*
  </replies>] // one or more replies which we have sent out
           
</SetAppointmentRequest>

<SetAppointmentResponse calItemId="appointment_id">
  <default id="invId_of_default_invite/>
  [<except recurId="recurrence_id_of_exception"
  id="invId_of_exception/>]*
</SetAppointmentResponse>


//////////////////////////////////////////////////////////////////////
//
// AddAppointmentInvite
//
// Add an invite.  The invite corresponds to a VEVENT component.  Based on the UID specified (required),
// a new appointment is created in the default calendar if necessary.  If an appointment with the same UID
// exists, the appointment is updated with the new invite only if the invite is not outdated, according to
// the iCalendar sequencing rule (based on SEQUENCE, RECURRENCE-ID and DTSTAMP).
//

<AddAppointmentInviteRequest>
  <m ...>  // same as <m> under <default> in SetAppointmentRequest
  </m>
</AddAppointmentInviteRequest>

<AddAppointmentInviteResponse
  // These attributes are returned only if the invite was added successfully.  They are omitted if invite
  // was ignored as being outdated.
  [calItemId="calendar item id"]
  [invId="invite id of the added invite"]
  [compNum="compNum of the added invite"]
/>

   
//////////////////////////////////////////////////////////////////////
//
// GetApptSummaries
//
// DEPRECATED -- this API is deprectated.  Use <SearchRequest> with
// the calExpandInstStart and calExpandInstEnd parameters
// 
//<GetApptSummariesRequest s="RANGE_START_MSECS_GMT" e="RANGE_END_MSECS_GMT" [l="{folder-id}"]/>
//
//  -- folder-id: optional folder to constrain requests to; otherwise, searches all folders but trash and spam
//
//<GetApptSummariesResponse>
// ( <appt id="appointment_mail_item_id"
//      [fba="F|B|T|U"]
//      [transp="O|T"]
//      [class="PUB|PRI|CON"]
//      status="TENT|CONF|CANC"
//      ptst="NE|TE|AC|DE|DG"
//      [allDay="1"]             // if set, this is an "all day" appointment
//      [draft="1"]              // set if invite has changes that haven't been sent to attendees; for organizer only
//      [neverSent="0|1"]        // set if attendees were never notified of this invite; for organizer only
//      [otherAtt="1"]           // if set, this appointment has other attendees
//      [alarm="1"]
//      [recur="1"]              // if set, this is a recurring appointment
//      [hasEx="1"]              // if set, this is a recurring appointment with exceptions
//      [name="NAME"] [loc="LOCATION"]
//      invId="default_invite_mail_item_id" compNum="default_invite_component_number"
//      isOrg="default_am_i_organizer_flag"
//      [priority="num"]
//      [percentComplete="num"]
//      [d="duration"]  // default duration
//      [f="flags"]
//      [t="tags"]
//   >
//   <fr>FRAGMENT</fr>
//   [<category>CATEGORY</category>]*
//   [<geo lat="LATITUDE (float value)" lon="LONGITUDE (float value)"/]
//
//      ( <inst
//          [s="START_SECS_GMT"]
//          [tzo="ms"]  // offset from GMT in milliseconds for start time in the
//                    // time zone of the instance; this is useful because the
//                    // instance time zone may not be the same as the time zone
//                    // of the requesting client; when rendering an all-day
//                    // appointment, the client must shift the appointment by
//                    // the difference between the instance time zone and its
//                    // local time zone to determine the correct date to render
//                    // the all-day block
//          [ex="1"]
//          [ANY CHANGED PARAMETERS]
//        >
//          [<f>FRAGMENT IF DIFFERENT FROM DEFAULT</f>]
//          [<dur DURATION>] // duration this instance if not same as default
//          [<isOrg>] // isOrg flag if not same as default
//          [<otherAtt>] // otherAtt flag if not same as default
//          [<category>CATEGORY</category>]*
//          [<geo lat="LATITUDE (float value)" lon="LONGITUDE (float value)"/]
//        </inst>
//      )+
//        
//   </appt> )*
//</GetApptSummariesResponse>
//
//   -- fba: actual free-busy status: Free, Busy, busy-Tentative, busy-Unavailable (a.k.a. OutOfOffice)
//           While free-busy status is simply a property of an event that
//           is set during creation/update, "actual" free-busy status is the true
//           free-busy state that depends on appt/invite free-busy, event scheduling
//           status (confirmed vs. tentative vs. cancel), and more importantly, the
//           attendee's participation status.  For example, actual free-busy is
//           busy-Tentative for an event with Busy free-busy value until the attendee
//           has acted on the invite.
//   -- transp: transparency: Opaque, Transparent
//   -- status: status of event: TENTative, CONFirmed or CANCelled
//   -- ptst: **your** participation status: NEeds-action, TEntative, ACcept, DEclined, DG (delegated)
//   -- get the summary of appointments for a specified time period...
//   -- otherAtt: 1 if there are other attendees to the meeting
//   -- alarm: 1 if there are some alarms
//   -- recur: 1 if this is a recurring appointment
//   -- id is mail_item id of APPOINTMENT object
//   -- invId is mail_item id of invite message with detailed information
//   -- comp is component number (invite # within the message)
//   -- parameters in the apptSum are "defaults" -- are same in instance unless specified
//
// END DEPRECATED BLOCK
//
//////////////////////////////////////////////////////////////////////


//////////////////////////////////////////////////////////////////////
//
// GetFreeBusyRequest
//
// (f)ree (b)usy busy-(t)entative busy-(u)navailable or (n)o-data elements
//
<GetFreeBusyRequest s="RANGE_START_MSECS_GMT" e="RANGE_END_MSECS_GMT"
  [uid="zimbraId/email,..."]  // DEPRECATED
                              // comma-separated list of zimraId or email
                              // each value can be zimbraId or email
  [id="zimbraId,..."]         // comma-separated list of zimbraId
  [name="email,..."]          // comma-separated list of email
  // For accounts listed in uid/id/name above, f/b search will be done for all calendar folders.
  // To view free/busy for a single folder in a particular account, use the <usr> format below.
  [excludeUid="UID of appointment to exclude from free/busy search"]
>
  [<usr [id="zimbraId] [name="email"]  // either id or email must be specified
       [l="folder id"]  // calendar folder id; if omitted, get f/b on all calendar folders
  />]*
</GetFreeBusyRequest>
<GetFreeBusyResponse>
  <usr id="id">  // id is always account email; it is not zimbraId as the attribute name may suggest
    <f s="START_MSECS_GMT" e="END_MSECS_GMT"/>*
    <b s="START_MSECS_GMT" e="END_MSECS_GMT"/>*
    <t s="START_MSECS_GMT" e="END_MSECS_GMT"/>*
    <u s="START_MSECS_GMT" e="END_MSECS_GMT"/>* // a.k.a. out of office
    <n s="START_MSECS_GMT" e="END_MSECS_GMT"/>* // could not retrieve data for that user
  </usr>  
<GetFreeBusyResponse>


//////////////////////////////////////////////////////////////////////
//
// GetWorkingHoursRequest
//
// (f)ree busy-(u)navailable or (n)o-data elements
//
// User's working hours within the given time range are expressed in a similar format as GetFreeBusy.
// Working hours are indicated as free, non-working hours as unavailable/out of office.  The entire time
// range is marked as unknown if there was an error determining the working hours, e.g. unknown user.
//
<GetWorkingHoursRequest s="RANGE_START_MSECS_GMT" e="RANGE_END_MSECS_GMT"
  [id="zimbraId,..."]         // comma-separated list of zimbraId
  [name="email,..."]          // comma-separated list of email
/>
<GetWorkingHoursResponse>
  <usr id="id">  // id is always account email; it is not zimbraId as the attribute name may suggest
    <f s="START_MSECS_GMT" e="END_MSECS_GMT"/>* // working hours
    <u s="START_MSECS_GMT" e="END_MSECS_GMT"/>* // non-working hours
    <n s="START_MSECS_GMT" e="END_MSECS_GMT"/>* // could not retrieve data for that user
  </usr>  
<GetWorkingHoursResponse>


//////////////////////////////////////////////////////////////////////
//
// CancelAppointment(DEFAULT-INVITE-ID, COMPONENT-NUMBER)
//
// NOTE: If canceling an exception, the original instance (ie the one the exception was "excepting") WILL NOT
// be restored when you cancel this exception.
//
// if <inst> is set, then this cancels just the specified instance or range of instances,
// otherwise it cancels the entire appointment.  If <inst> is not set, then id MUST refer to the default
// invite for the appointment.
//
<CancelAppointmentRequest id="ID_OF_DEFAULT_INVITE" comp="COMPONENT_NUM_DEFAULT_INVITE">
   [<tz ...>]  // definition for TZID referenced by DATETIME in <inst>
   [<inst [range="THISANDFUTURE|THISANDPRIOR"] DATETTIME/>]?
   [ <m>
       [<e.../>*] // users to send update to
       [<su>{subject of cancellation mail}</su>]
       <mp>...</mp>
     </m> ]
</CancelAppointmentRequest>

<CancelAppointmentResponse/>


//////////////////////////////////////////////////////////////////////
//
// GetMsgResponse 
//
// CALENDAR PART for Invite messages
//
<GetMsgResponse> // mesage with invite
  <m id="{message-id}" f="{flags}" t="{tags}" s="{size}" d="{date}" l="{folder}"
     rev="{revision-number}" md="{date-metadata-changed}" ms="{change-sequence}"
  >
     [<e .../>*]  // optional users to send request to

     <inv type="appt|task" id="{invId}">
       [
       <comp status="TENT|CONF|CANC"
            d="{date}"
       		fb="F|B|T|U"
       		fba="F|B|T|U" // Your current status -- what is returned in FreeBusy for you TODO
       		transp="O|T"
       		[class="PUB|PRI|CON"]
            [ex="1|0]  // 1 if this Invite is an Exception
            [allDay="1|0"] [name="NAME"]
            [loc="LOCATION"]
            [url="URL"]
            [rsvp="1|0"] // rsvp - 1 if response requested, 0 if no response requested
            [calItemId="mail-item-id-of-appointment"]
            [ciFolder="folder of appointment"]
            [updatedMsgId="id" updatedCompNum="compNum"] // if these are set, then this invite has been
                                                      // invalidated because a new update was received that
                                                      // takes precedence over it
                                                      //
                                                      // id=0, compnum=0 is a SPECIAL CASE: it means "we don't know
                                                      // what invite overrides this one, but we do know this one is
                                                      // not referenced.  This can happen if this is a
                                                      // recurrence-exception and default-invite is modified in a way
                                                      // that invalidates this one...or it can happen if there is an
                                                      // out-of-order message delivery (the exception invite is received
                                                      // before the initial invite) or if the Appointment object doesn't
                                                      // exist (ie it was deleted) or various other times...
                                                      // 
                                                      
            [isOrg="1"] // 1 if you are the Organizer of this event
            [ridZ="YYYYMMDD[ThhmmssZ]"]   // RECURRENCE-ID in "Z" (UTC) timezone, if this is an exception
            [changes="comma-separated list of changed data in an updated invite"]
                // Possible values are "subject", "location", "time" (start time, end time, or duration), and "recurrence".
            [draft="0|1"]  // set to 1 if invite has changes that haven't been sent to attendees; for organizer only
            [neverSent="0|1"]  // set if attendees were never notified of this invite; for organizer only
           >

           <s DATETIME
              [u="millis since epoch"]  // set if non-all-day
           /> // Start date-time (required)
           (
              <e DATETIME
                 [u="millis since epoch"]  // set if non-all-day
              /> // End date-time
              OR
              <dur DURATION/>
           )

           [<exceptId .../>]  // RECURRENCE-ID, if this is an exception

           <or ...> // organizer
           <at ...>* // attendee
           [
             <recur>
                RECURRENCE PART
             </recur>  
           ]
           // CATEGORIES
           [<category>CATEGORY</category>]*
           // COMMENTs
           [<comment>COMMENT</comment>]*
           // CONTACTs
           [<contact>CONTACT</contact>]*
           // GEO
           [<geo lat="LATITUDE (float value)" lon="LONGITUDE (float value)"/]
       </comp>


       ]+
     </inv>
     [<mp>...</mp>]
   </m>
</GetMsgResponse>


//////////////////////////////////////////////////////////////////////
//
// ModifyAppointment
//
// Modify an appointment, or if the appointment is a recurrence then modify the "default"
// invites: that is, all instances that do not have exceptions
//
// If the appointment has a <recur>, then the following caveats are worth mentioning:
//        
//   -- If any of: START, DURATION, END or RECUR change, then all exceptions are implicitly canceled!
//
<ModifyAppointmentRequest id="INVITE_ID_OF_DEFAULT_INVITE" comp="COMPONENT_NUM_DEFAULT_INVITE"
    ms="change-sequence of fetched version" rev="revision of fetched version"
    [echo="1"]  // if specified, the modified appointment is echoed back in the response as if a GetMsgRequest was made
    [max="{max-inlined-length}"] [html="*0|1"] [neuter="0|*1"]  // options for echoing
    [forcesend="0|1"] // if set to 1, ignore smtp 550 errors when sending the notification to attendees. The default is 1.
                      // if set to 0, throw the soapfaultexception with invalid addresses so that client can give forcesend option to enduser. 
    
>
   rest is SAME as CreateAppointmentRequest
</ModifyAppointmentRequest>

<ModifyAppointmentResponse calItemId="appointment-id" invId="invite-message-id" ms="change-sequence" rev="revision">
  [<echo><m .../></echo>]  // if echo="1" was specified in the request
</ModifyAppointmentResponse>

"ms" and "rev" are used for conflict detection.  By setting these, the request indicates
which version of the appointment it is attempting to modify.  If the appointment was updated on
the server between the fetch and modify, an INVITE_OUT_OF_DATE exception will be thrown.


//////////////////////////////////////////////////////////////////////
//
// CreateAppointmentException (invId, compNum, instanceid)
//
//   The default invite for the appointment MUST have a recurrence rule....
//      otherwise you should just be using ModifyAppointment!
//
//   EXCEPTION_ID is start-time for the particular instance you are overriding
//     EXCEPTION_ID MUST be some instance that matches the default-invite for
//     the appointment...that is, it MUST NOT BE the start time of the exception!
//
//   **The above is important**   So let me explain:
//
//   Given an appointment, happens every Wednesday @ 9am, with an exception that moves
//      it to 10am on 6/22
//
//   So our instances for June, 2005  are:
//       6/1 9am
//       6/8 9am
//       6/15 9am
//       6/22 10am (an existing EXCEPTION)
//       6/29 9am
//
//  So, if a user clicks on the 6/22 10am appointment and wants to modify it, you MUST NOT
//  try to use <CreateAppointmentExceptionRequest> to modify it!
//  You MUST use ModifyAppointmentRequest instead!!!
//
//  On the other hand, if a user clicks on the 6/15 9am appointment and wants to modify it,
//  then this is the right API to use.
//
<CreateAppointmentExceptionRequest id="ID_DEFAULT_INVITE" comp="COMP_DEFAULT_INVITE"
    ms="change-sequence of fetched series" rev="revision of fetched series"
    [echo="1"]  // if specified, the created exception is echoed back in the response as if a GetMsgRequest was made
    [max="{max-inlined-length}"] [html="*0|1"] [neuter="0|*1"]  // options for echoing
>

  Just like CreateAppointmentRequest above:
  <m f="{flags}" l="{folder}">
    ...
    <inv>
      ...
      <exceptId DATETIME> // EXCEPTION_ID -- this is the DateTime of some instance in the default appointment
      ...
    </inv>
  </m>  
   
</CreateAppointmentExceptionRequest>

<CreateAppointmentExceptionResponse>...

"ms" and "rev" are used for conflict detection.  The create exception request indicates the baseline
series version.  If the appointment was modified on the server between the series fetch and exception
creation, an INVITE_OUT_OF_DATE exception will be thrown.


//////////////////////////////////////////////////////////////////////
//
// ExpandRecur
//

<ExpandRecurRequest s="start time in millis" e="end time in millis">
  <tz/>*
  [<comp>     // series
    <s/>                   // DTSTART
    [<e/> OR <dur/>]       // DTEND/DURATION
    <recur/>               // RRULE/RDATE/EXDATE
  </comp>]
  [<except>  // modified instances
    <s/>                   // DTSTART
    [<e/> OR <dur/>]       // DTEND/DURATION
    <exceptId/>            // RECURRENCE-ID
  </except>]*
  [<cancel>  // canceled instances
    <exceptId/>            // RECURRENCE-ID
  </cancel>]*
</ExpandRecurRequest>

<ExpandRecurResponse>
  <inst s="start time in millis" dur="duration in millis"
        ridZ="recurrence-id string in UTC timezone"
        [allDay="1"]    // if instance is for an all-day appointment
        [tzo="millis"]  // GMT offset of start time in millis; returned only when allDay=1
  />*
</ExpandRecurResponse>


//////////////////////////////////////////////////////////////////////
//
// GetRecur
//
// Retrieve the recurrence definition of an appointment
//
<GetRecurRequest id="calendar item id"/>

<GetRecurResponse>
  [same as ExpandRecurRequest content]
</GetRecurResponse>



//////////////////////////////////////////////////////////////////////
//
// CheckRecurConflicts
//
// Check conflicts in recurrence against list of users.
// Use all=1 to get all instances, even those without conflicts.  By default
// only instances that have conflicts are returned.
//

<CheckRecurConflictsRequest
  [s="start time in millis"]  // if not specified, defaults to current time
  [e="end time in millis"]    // if not specified, unlimited
  [all="1"]
  [excludeUid="UID of appointment to exclude from free/busy search"]
>
  tz/comp/except/cancel elements (same as ExpandRecurRequest content)
  [<usr [id="zimbraId] [name="email"]  // either id or email must be specified
       [l="folder id"]  // calendar folder id; if omitted, get f/b on all calendar folders
  />]*
</CheckRecurConflictsRequest>

<CheckRecurConflictsResponse>
  <inst s="start time in millis" dur="duration in millis"
        ridZ="recurrence-id string in UTC timezone"
        [allDay="1"]    // if instance is for an all-day appointment
        [tzo="millis"]  // GMT offset of start time in millis; returned only when allDay=1
  >
    <usr name="email" fb="B|T|O"/>*  // for all users who have a conflict with the instance
                                     // fb is free/busy status (Busy, Tentative or Out-of-office)
  </inst>*
</CheckRecurConflictsResponse>


//////////////////////////////////////////////////////////////////////
//
// Retrieve the unparsed (but XML-encoded (&quot) iCalendar data for an Invite
//
// This is intended for interfacing with 3rd party programs
//
<GetICalRequest [id="invMsgId"] [s="RANGE_START_MSECS_GMT" e="RANGE_END_MSECS_GMT" l="{folder}"/>

    -- if id is specified, gets iCalendar representation for one
       Invite

    -- if id is not specified, then start/end MUST be, Calendar data
       is returned for entire specified range

<GetICalResponse>
   <ical>
      ICALENDAR DATA
   </ical>
</GetICalResponse>



//////////////////////////////////////////////////////////////////////
//
// SendInviteReply
//
//
<SendInviteReplyRequest id="mail_item_id" compNum="comp_num"
  verb="VERB" [updateOrganizer="1|0"]
  [idnt="{identity-id}"]  // use this identity to send reply
>
  [<tz ...>]  // definition for TZID referenced by DATETIME in <exceptId>
  [<exceptId DATETIME>]? // reply to just one instance of the specified Invite (default is all instances)
  [<m>...</m>]
</SendInviteReplyRequest>  

  id             : unique ID of the invite (and component therein) you are replying to
  comp           : component number of the invite
  verb           : ACCEPT, COMPLETED, DECLINE, DELEGATED, TENTATIVE  (Completed/Delegated are NOT supported as of 9/12/2005)
  m              : embedded message, if the user wants to send a custom update message.
                   The client is responsible for setting the message recipient list in
                   this case (which should include Organizer, if the client wants to tell
                   the organizer about this response)
  updateOrganizer: true by default. if false then only make the update locally.
                   Note that earlier documentation implied incorrectly that if this was false it would be ignored and
                   treated as being true if an <m> element is present.
                   Also take a note that, if RSVP setting in original invite is not present or FALSE then updateOrganizer will be treated as FALSE.
  
<SendInviteReplyResponse status="STATUS"/>

   status: OK, OLD (a newer invite exists for that appointment), ALREADY-REPLIED, FAIL   (other failure)


//////////////////////////////////////////////////////////////////////
//
// CounterAppointment
//
// Propose a new time/location.  Sent by meeting attendee to organizer.
// The syntax is very similar to CreateAppointmentRequest.
//
//
<CounterAppointmentRequest  id="INVITE_ID_OF_DEFAULT_INVITE" comp="COMPONENT_NUM_DEFAULT_INVITE"
    ms="change-sequence of fetched version" rev="revision of fetched version">
  <m>
    <e t="f" .../>  // From
    <e t="t" .../>  // To
    <su>...</su>    // Subject
    <mp>...</mp>    // plain/html texts
    <inv>  // iCalendar COUNTER object
      [<tz .../>]
      <comp name="{subject}" uid="{UID}" seq="{SEQUENCE}" ...>
        [<exceptId .../>]  // RECURRENCE-ID if dealing with an instance of a recurrence
        <s .../>   // start time
        <e .../>   // end time
        <or .../>  // organizer (the appointment's organizer who will be receiving the counter proposal)
        <at .../>  // attendee (the attendee sending this counter request)
      </comp>
    </inv>
  </m>
</CounterAppointmentRequest>

"ms" and "rev" are used for conflict detection.  By setting these, the request indicates
which version of the appointment it is attempting to propose.  If the appointment was updated on
the server between the fetch and modify, an INVITE_OUT_OF_DATE exception will be thrown.

<CounterAppointmentResponse/>


//////////////////////////////////////////////////////////////////////
//
// DeclineCounterAppointment
//
// Decline a change proposal from an attendee.  Sent by organizer to an attendee
// who has previously sent a COUNTER message.  The syntax is very similar to
// CreateAppointmentRequest.
//
<DeclineCounterAppointmentRequest>
  <m>
    <e t="f" .../>  // From
    <e t="t" .../>  // To
    <su>...</su>    // Subject
    <mp>...</mp>    // plain/html texts
    <inv>  // iCalendar DECLINECOUNTER object
      [<tz .../>]
      // comp should echo the same data 
      <comp name="{subject}" uid="{UID}" seq="{SEQUENCE}" ...>
        [<exceptId .../>]  // RECURRENCE-ID if dealing with an instance of a recurrence
        <s .../>   // start time
        <e .../>   // end time
        <or .../>  // organizer
        <at .../>  // attendee (the attendee whose COUNTER proposal is being declined)
      </comp>
    </inv>

    ...  // same as sending email; specify subject, recipient, etc.
    <inv>
      // equivalent of iCalendar DECLINECOUNTER VEVENT
    </inv>
  </m>
</DeclineCounterAppointmentRequest>

<DeclineCounterAppointmentResponse/>


//////////////////////////////////////////////////////////////////////
//
// ForwardAppointment
//
// Used by an attendee to forward an instance or entire appointment to
// another user who is not already an attendee.
//
//
<ForwardAppointmentRequest id="Appointment item id">
  [<tz .../>]             // definition for TZID referenced by DATETIME in <exceptId>
  [<exceptId DATETIME/>]  // RECURRENCE-ID if forwarding a single instance of a recurring appointment
  <m>
    <e t="f" .../>  // From
    <e t="t" .../>+ // To
    <su>...</su>    // Subject
    <mp>...</mp>    // plain/html texts
  </m>
</ForwardAppointmentRequest>

<ForwardAppointmentResponse/>



//////////////////////////////////////////////////////////////////////
//
// ForwardAppointmentInvite
//
// Used by an attendee to forward an appointment invite email to
// another user who is not already an attendee.
//
// To forward an appointment item, use ForwardAppointmentRequest instead.
//
//
<ForwardAppointmentInviteRequest id="invite Message item id">
  <m>
    <e t="f" .../>  // From
    <e t="t" .../>+ // To
    <su>...</su>    // Subject
    <mp>...</mp>    // plain/html texts
  </m>
</ForwardAppointmentInviteRequest>

<ForwardAppointmentInviteResponse/>



//////////////////////////////////////////////////////////////////////
//
// GetAppointment
//
// Returns the metadata info for each Invite that makes up this appointment.
//
// The content (original email) for each invite is stored within the Appointment itself in
// a big multipart/digest containing each invite in the appointment as a sub-mimepart --
// it can be retreived from the content servlet:
//
//       http://servername/service/content/get?id=<calItemId>
//
//
// The content for a single Invite can be requested from the content servlet (or from <GetMsg>)
// Individual  The client can ALSO request just the content for each individual invite using a
// compound item-id request:
//       http://servername/service/content/get?id="calItemId-invite_mail_item_id"
//       <GetMsgRequest><m id="calItemId-invite_mail_item_id"
//
//      
// IMPORTANT NOTE: DO NOT use the raw invite-mail-item-id to fetch the content: it might work
// sometimes, however the invite is a standard mail-message it can be deleted by the user at
// any time!
//
<GetAppointmentRequest
    id="appointment_id"      // either id or uid should be specified, but not both
    uid="iCalendar UID"
    [sync="1"]
    [includeContent="0|1"]   // if 1, MIME parts for body content are returned; default 0
/>

<GetAppointmentResponse>
  <appt uid="UID" id="appointment_id" [f="{flags}"] [t="{tags}"] s="{size}" d="{date}" l="{folder}"
        [nextAlarm="next alarm will go off at"]
        [orphan="1"]  // if appointment has exception instances only without the recurrence series
  >
    [<inv id="invite-original-mail-item-id" compNum="component-number" seq="num">
      ...
        ---See <inv> part of GetMsgResponse---
      ...    

      [<mp> ... </mp>]  // body content, if includeContent="1" was specified in the request
    </inv>]+

  // List of replies received from attendees.
  [<replies>
     [<reply d="TIMESTAMP_OF_REPLY"
             at="foo@bar.com"        // address of attendee who replied
             ptst="AC|DE|TE|NE"      // accepted, declined, etc.
             [  // present if reply is to an instance in a recurrence
              recurId="YYMMDD[THHMMSS[Z]]"
              [tz="timezonename"]
              rangeType="1"          // always 1
              [ridZ="YYMMDDTHHMMSSZ"]  // recurrence-id in UTC time zone; used in non-all-day appointments only
             ]
     />]*
  </replies>] // one or more replies which we have sent out

  </appt>
</GetAppointmentResponse>

  if sync="1" present, return modified date (md) on appointment.

-------------------------------------------------------------------------------

<ImportAppointmentsRequest ct="{content-type}" [l="{folder-id}"]>
  <content [aid="{attach-upload-id}"]                    // use an uploaded object
           [mid="{message-id}" part="{part-identifier}]  // use a part in an existing message
  >
    ...  // or inline the data
  </content>
</ImportAppointmentsRequest>

<ImportAppointmentsResponse>
  <appt ids="{list-of-created-ids} n="{num-imported}"/>
</ImportAppointmentsResponse>

{content-type} = only currently supported content type is "text/calendar" (and its nickname "ics")
{folder-id} = optional folder id to import appointments into

{attach-upload-id} = attachment id from upload server. If specified, then body of content is ignored.

-------------------------------------------------------------------------------

<DismissCalendarItemAlarmRequest>
  <appt|task id="cal item id" dismissedAt="time alarm was dismissed, in millis"/>+
</DismissCalendarItemAlarmRequest>

<DismissCalendarItemAlarmResponse>
  <appt|task calItemId="cal item id">
    <alarmData ...>  // so the client knows when to trigger the next alarm
                     // See <alarmData> definition under SearchResponse, in soap.txt
  </appt|task>+  // one for each <appt|task> in the request
</DismissCalendarItemAlarmResponse>

-------------------------------------------------------------------------------

<SnoozeCalendarItemAlarmRequest>
  <appt|task id="cal item id" until="when to show the alarm agian, in millis"/>+
</SnoozeCalendarItemAlarmRequest>

<SnoozeCalendarItemAlarmResponse>
  <appt|task calItemId="cal item id">
    <alarmData ...>  // so the client knows when to trigger the next alarm
                     // See <alarmData> definition under SearchResponse, in soap.txt
  </appt|task>+  // one for each <appt|task> in the request
</SnoozeCalendarItemAlarmResponse>

-------------------------------------------------------------------------------

<GetMiniCalRequest s="range start time in millis" e="range end time in millis">
  <folder id="folder id"/>+  // local and/or remote calendar folders

  [ // optional timezone specifier
    <tz id="timezonename"/>    // References an existing server-known timezone by ID

    OR

    <tz> ... </tz>  // full specification of a custom timezone; see CreateAppointmentRequest
  ]
</GetMiniCalRequest>

<GetMiniCalResponse>
  [<date>yyyymmdd</date>]*   // e.g. 20080221
  [<error  // error for each calendar folder that couldn't be accessed
     id="folder id"
     code="ServiceException error code"  // e.g. service.PERM_DENIED, mail.NO_SUCH_FOLDER, account.NO_SUCH_ACCOUNT, etc.
   >error message from the exception (but no stack trace)</error>]*
</GetMiniCalResponse>

Date is returned if there is at least one appointment on that date.  The date computation
uses the requesting (authenticated) account's time zone, not the time zone of the account
that owns the calendar folder.



-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------

NOTES NOTES (not part of soap proto)



Internal Server-Side Calendar Data Model
----------------------------------------

An INVITE is an email message with an iCal attachment.  An INVITE has
a mail_item_id, which uniquely identifies it, and a UID which identifies
the APPOINTMENT it is about....plus other normal iCal data.  An Invite
has a START and END time -- which corresponds to the range of time
where this invite is relevant.

   Some sample invites:
   
      INVITE sent on 3/1 with id=5 UID=1234 for an event happening every Monday
      with subject "Gorilla Discussion" (START=3/1, END=none)
      
      INVITE with id=7 UID=1234 for an exception on 3/21
      for the "Left-Handed Gorilla Discussion" (START=3/21 END=3/21)
 

   
An APPOINTMENT consists of one or more INVITES in the same series --
ie that have the same UID. From the appointment you can get the INSTANCES
which are the start/end times of each occurence.  

   Sample Appointment:
       APPOINTMENT UID=1234 (two INVITES above)
          ...Instances on every monday with name "Gorilla Discussion"
          EXCEPT for the 21st, where we talk about lefties instead.


An INSTANCE is simply a start-end time and a pointer to an INVITE
which has detailed information about the meeting (description, etc)

   Instances:
       3/1 "Gorilla Discussion" id=5
       3/14 "Gorilla Discussion" id=5
       3/21 "Left-Handed Gorilla Discussion" id=7
	


       
TIMEZONES:
----------------
Each iCalendar object can define custom time zone names.  For our own web
client, there is a list of well-known time zones.  These are stored in
LDAP.  See conf/ldap/zimbra.ldif for their definition.  The time zone ID
is the cn attribute.




TASKS:
----------------
For every <DoAction>AppointmentRequest, there is <DoAction>TaskRequest, and
corresponding responses.  For GetApptSummariesRequest, there is
GetTaskSummariesRequest.  GetCalendarItemsSummariesRequest is there for
retrieving both appointments and tasks in one shot.

Wherever <appt> element shows up, the corresponding task request/response will
use <task> element.

<appt> element uses apptID for backward compatibility reason.  New code should
ignore apptID and use calItemID instead.  <task> element uses calItemID only.