diff options
Diffstat (limited to 'doc/UsingLibical.md')
| -rw-r--r-- | doc/UsingLibical.md | 77 |
1 files changed, 27 insertions, 50 deletions
diff --git a/doc/UsingLibical.md b/doc/UsingLibical.md index 39e9901f..721523f7 100644 --- a/doc/UsingLibical.md +++ b/doc/UsingLibical.md @@ -11,24 +11,18 @@ 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 [RFC5545][], [RFC5546][], [RFC7529][]; the -iCalendar extensions in [RFC6638][]; and some of [RFC6047][]. +Libical implements multiple [RFC calendar standards](@ref rfcs). This documentation assumes that you are familiar with the iCalendar standards RFC5545 and RFC5546. These specifications are available at the [IETF Tools][] website: -[RFC5545]: https://tools.ietf.org/html/rfc5545 -[RFC5546]: https://tools.ietf.org/html/rfc5546 -[RFC7529]: https://tools.ietf.org/html/rfc7529 -[RFC6638]: https://tools.ietf.org/html/rfc6638 -[RFC6047]: https://tools.ietf.org/html/rfc6047 [IETF Tools]: https://tools.ietf.org/ ### 1.1 The libical project This code is under active development. If you would like to contribute -to the project, visit <https://libical.github.io/libical/> +to the project, visit <https://libical.github.io/libical/>. ### 1.2 License @@ -40,8 +34,8 @@ See <https://www.gnu.org/licenses/lgpl-2.1.html> for a copy of the LGPL. This dual license ensures that the library can be incorporated into both proprietary code and GPL'd programs, and will benefit from improvements -made by programmers in both realms. I will only accept changes into -my version of the library if they are similarly dual-licensed. +made by programmers in both realms. We (the libical developers) will only +accept changes to this library if they are similarly dual-licensed. ### 1.3 Example Code @@ -439,7 +433,7 @@ int main(int argc, char *argv[]) } ``` -The parser object parameterizes the routine used to get input lines +The parser object parametrizes the routine used to get input lines with `icalparser_set_gen_data()`and `icalparser_get_line()`. In this example, the routine `read_stream()` will fetch the next line from a stream, with the stream passed in as the `void*` parameter d. The parser @@ -870,7 +864,7 @@ struct icaltimetype icaltime_from_string( const char* str); struct icaltimetype icaltime_from_timet_with_zone( - time_t v, + icaltime_t v, int is_date, icaltimezone* zone); ``` @@ -881,7 +875,7 @@ struct icaltimetype icaltime_from_timet_with_zone( struct icaltimetype tt = icaltime_from_string("19970101T103000"); ``` -`icaltime_from_timet_with_zone()` takes a `time_t` value, representing seconds past +`icaltime_from_timet_with_zone()` takes a `icaltime_t` value, representing seconds past the POSIX epoch, a flag to indicate if the time is a date, and a time zone. Dates have an identical structure to a time, but the time portion (hours, minutes and seconds) is always 00:00:00. Dates act differently in @@ -954,11 +948,11 @@ the hour, minute and second fields should be used in the conversion. ```c struct icaltimetype icaltime_from_timet_with_zone( - time_t v, + icaltime_t v, int is_date, icaltimezone* zone); -time_t icaltime_as_timet( +icaltime_t icaltime_as_timet( struct icaltimetype); ``` @@ -1113,7 +1107,7 @@ open an existing file for reading and writing, or create a new file if it does not exist. `icalfileset_new_open()` takes the same arguments as the open() system routine and behaves in the same way. -The icalset and icalfilset objects are somewhat interchangeable -- you +The icalset and icalfileset objects are somewhat interchangeable -- you can use an `icalfileset*` as an argument to any of the icalset routines. The following examples will all use icalfileset routines; using the @@ -1129,7 +1123,7 @@ icalerrorenum icalfileset_add_component( icalcomponent* child); ``` -The fileset keeps an inmemory copy of the components, and this set +The fileset keeps an in-memory copy of the components, and this set must be written back to the file occasionally. There are two routines to manage this: @@ -1191,8 +1185,7 @@ DTSTART <= '20000106T120000Z'"); fs = icalfileset_new(path); for (i = 0; i!= 10; i++){ - c = make_component(i); /* Make a new component where DTSTART -has month of i */ + c = make_component(i); /* Make a new component where DTSTART has month of i */ icalfileset_add_component(fs,c); } @@ -1217,7 +1210,8 @@ has month of i */ There are several other routines in the icalset interface, but they not fully implemented yet. -#### <a id="memory"></a>5.5 Memory Management +<a id="memory"></a> +#### 5.5 Memory Management Libical relies heavily on dynamic allocation for both the core objects and for the strings used to hold values. Some of this memory the library @@ -1225,13 +1219,14 @@ caller owns and must free, and some of the memory is managed by the library. Here is a summary of the memory rules. 1. If the function name has "new" in it (such as `icalcomponent_new()`, - or `icalpropert_new_clone()`), the caller gets control - of the memory. + or `icalproperty_new_from_string()`), the caller gets control + of the memory. The caller also gets control over an object that is + cloned via a function that ends with "_clone" (like `icalcomponent_clone()`) -2. If you got the memory from a routine with new in it, you must - call the corresponding `*_free()` routine to free the memory, for - example use `icalcomponent_free()` to free objects created with - `icalcomponent_new()`) +2. If you got the memory from a routine with "clone" or "new" in it, you + must call the corresponding `*_free()` routine to free the memory, + for example use `icalcomponent_free()` to free objects created with + `icalcomponent_new()` or `icalcomponent_clone()` 3. If the function name has "add" in it, the caller is transferring control of the memory to the routine, for example the function @@ -1322,30 +1317,12 @@ RFC5545. There are a few routines to manipulate error properties: -The following data is supposed to be in a table. It looks OK in LyX, -but does not format properly in output. - -+-------------------------------------+---------------------------------------------------------+ -| Routine | Purpose | -+-------------------------------------+---------------------------------------------------------+ -| void icalrestriction_check() | Check a component against RFC5546 and insert | -+-------------------------------------+---------------------------------------------------------+ -| | error properties to indicate non compliance | -+-------------------------------------+---------------------------------------------------------+ -| int icalcomponent_count_errors() | Return the number of error properties | -+-------------------------------------+---------------------------------------------------------+ -| | in a component | -+-------------------------------------+---------------------------------------------------------+ -| void icalcomponent_strip_errors() | Remove all error properties in as | -+-------------------------------------+---------------------------------------------------------+ -| | component | -+-------------------------------------+---------------------------------------------------------+ -| void icalcomponent_convert_errors() | Convert some error properties into | -+-------------------------------------+---------------------------------------------------------+ -| | REQUESTS-STATUS proprties to indicate the inability to | -+-------------------------------------+---------------------------------------------------------+ -| | process the component as an iTIP request. | -+-------------------------------------+---------------------------------------------------------+ +| Routine | Purpose | +|:--------------------------------------|:-----------------------------------------------------| +| `void icalrestriction_check()` | Check a component against RFC5546 and insert error properties to indicate non compliance | +| `int icalcomponent_count_errors()` | Return the number of error properties in a component | +| `void icalcomponent_strip_errors()` | Remove all error properties in a component | +| `void icalcomponent_convert_errors()` | Convert some error properties into REQUESTS-STATUS properties to indicate the inability to process the component as an iTIP request | The types of errors are listed in icalerror.h. They are: |