ICS File Format (Calendar)

[Gary Beene]

I'm playing around with creating ICS calendar files to allow a PowerBASIC app to send calendar events to someone, where they would import the received calendar events into their own calendar.

For testing of the calendar events, I'm using the online validation tool at https://icalendar.org/validator.html#results

I've read that many calendar apps support the ICS file format and was able to import this sample calendar event into MS Outlook.

BEGIN:VCALENDAR
VERSION: 2.0
PRODID: gbCalendar
BEGIN:VEVENT
UID:100001
DTSTAMP:20201112T100000
DTSTART:20201112T100000
DTEND:20201111T123000
DESCRIPTION:One for the money \n
 Two for the show \n
 Three to make ready and \n
 Four to GO!
SUMMARY:Annual checkup with Dr. Smith
END:VEVENT
END:VCALENDAR

I just started playing with it last night and am still working through some online examples. The RFC 5545 specification covers the ICS file format.

From the spec, I missed the need to use "\n" at the end of lines and to have a blank space before follow-on text DESCRIPTION lines. I caught those requirements in a discussion I ran across.

Does anyone have any experience with using ICS files? Any tips to pass on?

[Michael Mattias]

The Microsoft Calendar API at https://docs.microsoft.com/en-us/gra...ncept-overview might have some help for you.

[Stuart McLachlan]

...I missed the need to use "\n" at the end of lines...

BEGIN:VCALENDAR
VERSION: 2.0
PRODID: gbCalendar
BEGIN:VEVENT
UID:100001
DTSTAMP:20201112T100000
DTSTART:20201112T100000
DTEND:20201111T123000
DESCRIPTION:One for the money \n
 Two for the show \n
 Three to make ready and \n
 Four to GO!
SUMMARY:Annual checkup with Dr. Smith
END:VEVENT
END:VCALENDAR

Make sure you don't confuse new lines in a field with folding long lines.

Para 3.1:
The iCalendar object is organized into individual lines of text, called content lines.
Content lines are delimited by a line break, which is a CRLF sequence (CR character followed by LF character).
Lines of text SHOULD NOT be longer than 75 octets, excluding the line break.
Long content lines SHOULD be split into a multiple line representations using a line "folding" technique. That is, a long line can be split between any two characters by inserting a CRLF immediately followed by a single linear white-space character (i.e., SPACE or HTAB).
Any sequence of CRLF followed immediately by a single linear white-space character is ignored (i.e., removed) when processing the content type.
For example, the line:
DESCRIPTION:This is a long description that exists on a long line.
Can be represented as:
DESCRIPTION:This is a lo
ng description that exists on a long line.

The process of moving from this folded multiple-line representation to its single-line representation is called "unfolding". Unfolding is accomplished by removing the CRLF and the linear white-space character that immediately follows.

Please ensure you include a time zone.!

[Stuart McLachlan]

One other way to do your DESCRPTION which illustrates line folding versus new lines more clearly. It contains four lines of text which have been folded. (i.e. in two physical lines with $CR,$LF,$SPC. between them)

BEGIN:VCALENDAR
VERSION: 2.0
PRODID: gbCalendar
BEGIN:VEVENT
UID:100001
DTSTAMP:20201112T100000
DTSTART:20201112T100000
DTEND:20201111T123000
DESCRIPTION:One for the money\nTwo for the show\n
 Three to make ready and\nFour to GO!
SUMMARY:Annual checkup with Dr. Smith
END:VEVENT
END:VCALENDAR

Or you could keep it as a single line:

DESCRIPTION:One for the money\nTwo for the show\nThree to make ready and\nFour to GO!

[Gary Beene]

Howdy, Stuart!

I did confuse new lines with folding long lines - thinking that they were just using different terminology for the same structure. There are other aspects of the par3.1 that I just didn't capture on first read.

I appreciate your clarifying remarks!

... added ... and yes, I'll plan on adding the TimeZone. First read of the spec on that was not very illuminating but I'll make a second pass later tonight.

[Gary Beene]

Howdy, Stuart!

For my needs, DESCRIPTION is mostly a group of short lines of text. Keeping the ICS output visually consistent with the visual look of the original text is the way I'll lean towards.

I'll keep in mind that the spec requires folding at 75 characters in any line of text.

[Stuart McLachlan]

Also note that the encoding of iCalendar values is US-ASCII / UTF-8 so if your description has high ANSII characters (or is WSTRING) , you should use ChrToUtf8$ on the output.

See the definition of "value" in para 3.1 and
6. Internationalization Considerations
Applications MUST generate iCalendar streams in the UTF-8 charset and MUST accept an iCalendar stream in the UTF-8 or US-ASCII charset.

[Stuart McLachlan]

... added ... and yes, I'll plan on adding the TimeZone. First read of the spec on that was not very illuminating but I'll make a second pass later tonight.

The simplest was is to convert everything to UTC (PowerTIMIE is your friend) and append a "Z".

Using VTIMEZONE and TZID gets a lot more fiddly.

[Stuart McLachlan]

WRT Times:

Your ics file won't validate with a TZID without a VTIMEZONE definition, but a slash (solidus) before an Olson ID is recognised by many iCalendar implementations so you can probably use something like:

DTSTART;TZID=/America/Chicago:20201112T100000

See https://documents.polycom.com/bundle...e/r2732735.html for Olson IDs


For all the gory details and pitfalls of TZID implementations, see: https://icalevents.com/2613-what-eve...alendar-files/

[Gary Beene]

Howdy, Stuart!

More good stuff. Thanks!