diff options
author | Ken Murchison <murch@andrew.cmu.edu> | 2015-08-18 11:23:36 -0400 |
---|---|---|
committer | Ken Murchison <murch@andrew.cmu.edu> | 2015-08-18 11:23:36 -0400 |
commit | 62cd9b001e35ef0bb0ff7f53524fbfdb7bcf11a9 (patch) | |
tree | b4aead27cbef0a4c3cee7225fd8facf7e7739c39 /doc | |
parent | 439f1ab7ebe8878fe8a9590144bbc5aff08c8e75 (diff) | |
download | libical-git-62cd9b001e35ef0bb0ff7f53524fbfdb7bcf11a9.tar.gz |
Change RFC2445/2446 references to RFC5545/5546
Diffstat (limited to 'doc')
-rw-r--r-- | doc/UsingLibical.txt | 43 |
1 files changed, 22 insertions, 21 deletions
diff --git a/doc/UsingLibical.txt b/doc/UsingLibical.txt index 8e31c559..92a766b0 100644 --- a/doc/UsingLibical.txt +++ b/doc/UsingLibical.txt @@ -15,10 +15,11 @@ and protocol data units. The iCalendar specification describes how calendar clients can communicate with calendar servers so users can store their calendar data and arrange meetings with other users. -Libical implements RFC2445, RFC2446 and some of RFC2447. +Libical implements RFC5545, RFC5546, RFC7529; the iCalendar extensions +in RFC6638; and some of RFC6047. This documentation assumes that you are familiar with the iCalendar -standards RFC2445 and RFC2446. these specifications are online on +standards RFC5545 and RFC5546. these specifications are online on the CALSCH webpage at: http://www.imc.org/ietf-calendar/ @@ -133,7 +134,7 @@ of these associations of data and routines is very similar to a class. 3.1.1 Properties Properties are represented with the icalproperty class and its many -"derived" classes with on "derived" class per property type in RFC2445. +"derived" classes with on "derived" class per property type in RFC5545. Again, there is no actual inheritance relations, but there are clusters of routines that make this term useful. A property is a container for a single value and a set of parameters. @@ -167,7 +168,7 @@ or union. 3.2.2 The parser -The libical parser offers a variety of ways to convert RFC2445 text +The libical parser offers a variety of ways to convert RFC5545 text into a libical internal component structure. the parser can parse blocks of text as a string, or it can parse line-by-line. @@ -204,13 +205,13 @@ XDAYLIGHT and XSTANDARD are notable examples. These pseudo components group properties within the VTIMEZONE components. For instanace, the timezone properties associated with daylight savings time starts with "BEGIN:DAYLIGHT" and ends with "END:DAYLIGHT, just like other components, -but is not defined as a component in RFC2445 (see RFC2445, page -61). In Libical,this grouping is represented by the XDAYLIGHT component. +but is not defined as a component in RFC5545 (see RFC5545, section 3.6.5) +In Libical,this grouping is represented by the XDAYLIGHT component. Standard iCAL components all start with the letter "V," while pseudo components start with"X." There are also pseudo components that are conceptually derived classes -of VALARM. RFC2446 defines what properties may be included in each +of VALARM. RFC5546 defines what properties may be included in each component, and for VALARM, the set of properties it may have depends on the value of the ACTION property. @@ -233,7 +234,7 @@ with a property. It is natural to have interfaces that would return the value of a property, but it is cumbersome for a single routine to return multiple types. So, in libical, properties that can have multiple types are given -a single type that is the union of their RFC2445 types. For instance, +a single type that is the union of their RFC5545 types. For instance, in libical, the value of the TRIGGER property resolves to struct icaltriggertype. This type is a union of a DURATION and a DATE-TIME. @@ -255,7 +256,7 @@ CATEGORIES: work CATEGORIES: home -Oddly, RFC2445 allows some multi-valued properties (like FREEBUSY) +Oddly, RFC5545 allows some multi-valued properties (like FREEBUSY) to exist as both a multi-values property and as multiple single value properties, while others (like CATEGORIES) can only exist as single multi-valued properties. This makes the internal representation @@ -390,7 +391,7 @@ are lucky. 5.1.3 Parsing Text Files The final way to create components will probably be the most common; -you can create components from RFC2445 compliant text. If you have +you can create components from RFC5545 compliant text. If you have the string in memory, use icalcomponent* icalparser_parse_string(char* str); @@ -773,22 +774,22 @@ void icalproperty_set_x_name(icalproperty* prop, char* name); 5.2.7 Checking Component Validity -RFC 2446 defines rules for what properties must exist in a component +RFC 5546 defines rules for what properties must exist in a component to be used for transferring scheduling data. Most of these rules relate to the existence of properties relative to the METHOD property, which declares what operation a remote receiver should use to process a component. For instance, if the METHOD is REQUEST and the component is a VEVENT, the sender is probably asking the receiver to join in -a meeting. In this case, RFC2446 says that the component must specify +a meeting. In this case, RFC5546 says that the component must specify a start time (DTSTART) and list the receiver as an attendee (ATTENDEE). Libical can check these restrictions with the routine: int icalrestriction_check(icalcomponent* comp); -This routine returns 0 if the component does not pass RFC2446 restrictions, +This routine returns 0 if the component does not pass RFC5546 restrictions, or if the component is malformed. The component you pass in must be -a VCALENDAR, with one or more children, like the examples in RFC2446. +a VCALENDAR, with one or more children, like the examples in RFC5546. When this routine runs, it will insert new properties into the component to indicate any errors it finds. See section 6.5.3, X-LIC-ERROR for @@ -796,7 +797,7 @@ more information about these error properties. 5.2.8 Converting Components to Text -To create an RFC2445 compliant text representation of an object, use +To create an RFC5545 compliant text representation of an object, use one of the *_as_ical_string() routines: char* icalcomponent_as_ical_string (icalcomponent* component) @@ -858,7 +859,7 @@ struct icaltimetype icaltime_from_timet(time_t v, int is_date); struct icaltimetype icaltime_from_int(int v, int is_date, int is_utc); -Icaltime_from_string takes any RFC2445 compliant time string: +Icaltime_from_string takes any RFC5545 compliant time string: struct icaltimetype tt = icaltime_from_string("19970101T103000"); @@ -867,7 +868,7 @@ the POSIX epoch, and a flag to indicate if the time is a date. Dates have an identical structure to a time, but the time portion ( hours, minuts and seconds ) is always 00:00:00. Dates act differently in sorting an comparision, and they have a different string representation -in RFC2445. +in RFC5545. The icaltime_from_int is like icaltime_from_timet, but with an arbitrary epoch. This routine was a mistake and is deprecated. @@ -1231,7 +1232,7 @@ The library handles semantic and syntactic errors in components by inserting errors properties into the components. If the parser cannot parse incoming text ( a syntactic error ) or if the icalrestriction_check() routine indicates that the component does not meet the requirements -of RFC2446 ( a semantic error) the library will insert properties +of RFC5546 ( a semantic error) the library will insert properties of the type X-LIC-ERROR to describe the error. Here is an example of the error property: @@ -1242,7 +1243,7 @@ Expected 1 instances of the property and got 0 This error resulted from a call to icalrestriction_check(), which discovered that the component does not have a DTSTART property, as required by -RFC2445. +RFC5545. There are a few routines to manipulate error properties: @@ -1252,7 +1253,7 @@ but does not format propertly in output. ] +-------------------------------------+---------------------------------------------------------+ | Routine | Purpose | +-------------------------------------+---------------------------------------------------------+ -| void icalrestriction_check() | Check a component against RFC2446 and insert | +| void icalrestriction_check() | Check a component against RFC5546 and insert | +-------------------------------------+---------------------------------------------------------+ | | error properties to indicate non compliance | +-------------------------------------+---------------------------------------------------------+ @@ -1324,7 +1325,7 @@ at. Structures that you access though a typedef, such as "icalcomponent" are things where all of the data is hidden. -Component names that start with "V" are part of RFC 2445 or another +Component names that start with "V" are part of RFC 5545 or another iCal standard. Component names that start with "X" are also part of the spec, but they are not actually components in the spec. However, they look and act like components, so they are components in libical. |