ProjectsWebsiteBlog

Calendar Parts

How do the calendar parts work in VisualCard?

Normally, calendars in VisualCard have three types of parts that define a calendar:

  • Strings (GetString())

  • Integers (GetInteger())

  • Array of parts (GetPartsArray())

In the current version of VisualCard, the following parts are supported:

Key
Type
Component
1.0
2.0

PRODID

String

Root

●

●

METHOD

String

Root

●

CALSCALE

String

Root

●

ATTACH

Array

Event, to-do, journal, or alarm

●

●

CATEGORIES

Array

Event, to-do, or journal

●

●

COMMENT

String

Event, to-do, journal, or free/busy

●

GEO

Array

Event or to-do

●

●

LOCATION

String

Event or to-do

●

RESOURCES

Array

Event or to-do

●

●

ATTENDEE

String

Event, to-do, journal, free/busy, or alarm

●

●

CREATED

Array

Event, to-do, or journal

●

DCREATED

Array

Event or to-do

●

DTSTART

Array

Event, to-do, free/busy, or standard/daylight timezone components

●

●

DTEND

Array

Event or free/busy

●

●

DTSTAMP

Array

Event

●

CLASS

String

Event, to-do, or journal

●

●

UID

String

Event, to-do, journal, or free/busy

●

●

ORGANIZER

String

Event, to-do, journal, or free/busy

●

●

STATUS

String

Event, to-do, or journal

●

●

SUMMARY

String

Event, to-do, journal, or alarm

●

●

DESCRIPTION

String

Event, to-do, journal, or alarm

●

●

TRANSP

String

Event

●

●

ACTION

String

Alarm

●

TRIGGER

String

Alarm

●

TZID

String

Timezone

●

TZURL

String

Timezone

●

TZNAME

String

Timezone

●

TZOFFSETFROM

Integer

Timezone

●

TZOFFSETTO

Integer

Timezone

●

RRULE

String

Event, to-do, journal, or daylight and standard time zone components

●

●

RDATE

Array

Event, to-do, journal, or daylight and standard time zone components

●

●

EXDATE

Array

Event, to-do, journal, or daylight and standard time zone components

●

●

PRIORITY

Integer

Event or to-do

●

SEQUENCE

Integer

Event, to-do, or journal

●

●

PERCENT-COMPLETION

Integer

To-do

●

COMPLETED

Array

To-do

●

●

DUE

Array

To-do

●

●

DAYLIGHT

Array

Event, to-do, journal, or daylight and standard time zone components

●

AALARM

Array

Event or to-do

●

DALARM

Array

Event or to-do

●

MALARM

Array

Event or to-do

●

PALARM

Array

Event or to-do

●

RELATED-TO

String

Event, to-do, or journal

●

●

LAST-MODIFIED

Array

Event, to-do, journal, or time zone

●

●

EXRULE

String

Event or to-do

●

RECURRENCE-ID

String

Event, to-do, or journal

●

REPEAT

Integer

Alarm

●

●

DURATION

String

Event, to-do, or alarm

●

REQUEST-STATUS

Array

Event, to-do, journal, or free/busy

●

URL

String

Event, to-do, journal, or free/busy

●

●

TZ

String

Root

●

●

CONTACT

String

Event, to-do, journal, or free/busy

●

RNUM

Integer

Event or to-do

●

The following status types that are allowed in events, to-dos, or journals are:

  • vCalendar 1.0

    • Event

      • NEEDS ACTION

      • SENT

      • TENTATIVE

      • CONFIRMED

      • DECLINED

      • DELEGATED

    • To-do

      • NEEDS ACTION

      • SENT

      • ACCEPTED

      • COMPLETED

      • DECLINED

      • DELEGATED

  • vCalendar 2.0

    • Event

      • TENTATIVE

      • CONFIRMED

      • CANCELLED

    • To-do

      • NEEDS-ACTION

      • COMPLETED

      • IN-PROCESS

      • CANCELLED

    • Journal

      • DRAFT

      • FINAL

      • CANCELLED

Additionally, the event or to-do alarm type for a single alarm component can be one of:

  • AUDIO

  • DISPLAY

  • EMAIL

For the ATTENDEE property, you can either specify nothing as a type (without typing the TYPE= parameter) or specify VCARD and any X-nonstandard type. Same applies for the AALARM property, except that it supports only PCM, WAVE, AIFF, and any X-nonstandard or IANA type as types.

The below sections describe how exactly to parse all the supported types.

You can access all extra X-named and IANA properties by calling GetPartsArray, passing it the ExtraInfo type as a generic type argument. You can also get all parsed extra X-named and IANA components using the Others property from the root calendar.

Strings

Strings in vCalendar and VisualCard are the simplest of the types that allow you to input just text that represent that property. The above table shows all the properties, and those that are listed as a String, such as CLASS, can be get as a string using a function called GetString(). You can also get a dictionary of a list of parsed strings using the Strings property.

This function returns one of the following strings:

  • An empty string

    • If the string is not supported in the calendar's vCalendar version.

    • If the string is not defined in the calendar's vCalendar instance.

    • If the string is explicitly blank.

  • A string value

    • If the string is defined, supported, and is not empty.

When using the above function, it returns an instance of ValueInfo<string> that contains the following properties:

  • Property: An instance of PropertyInfo that shows you a dissection of raw prefix, group, and values. It contains the following properties:

    • Arguments: An array of parsed ArgumentInfo instances that contains the following properties and functions:

      • Key: Argument key name

      • Values: An array of a tuple that describes the value case sensitivity and the unquoted value

      • AllValues: An array of unquoted values

      • MatchValue(): A function that lets you match a value

    • Value: Raw value, as it appears on a vCalendar representation

    • Prefix: Raw prefix, as it appears on a vCalendar representation

    • Group: Raw group, as it appears on a vCalendar representation

    • NestedGroups: Nested groups separated by a dot

  • AltId: Alternative ID. If it's not specified, it returns -1.

  • ElementTypes: Card element type (home, work, ...)

  • ValueType: Value type (usually set by VALUE=)

  • Group: Property group

  • NestedGroups: Nested groups for a property (separated by a dot)

  • Value: A string value

  • IsPreferred: Is this part preferred?

You can also use the following functions:

  • HasType(): Checks to see if this value has a specific type

Integers

Integers in vCalendar and VisualCard are the simplest of the types that allow you to input just a number that represents that property. The above table shows all the properties, and those that are listed as an Integer, such as PRIORITY, can be get as an integer using a function called GetInteger(). You can also get a dictionary of a list of parsed integers using the Integers property.

This function returns one of the following integers:

  • -1

    • If the integer is not supported in the contact's vCard version.

    • If the integer is not defined in the contact's vCard instance.

    • If the integer is specified as -1

  • An integer value

    • If the integer is defined and supported.

When using the above function, it returns an instance of CardValueInfo<double> that contains the following properties:

  • Arguments: An array of parsed ArgumentInfo instances that contains the following properties and functions:

    • Key: Argument key name

    • Values: An array of a tuple that describes the value case sensitivity and the unquoted value

    • AllValues: An array of unquoted values

    • MatchValue(): A function that lets you match a value

  • AltId: Alternative ID. If it's not specified, it returns -1.

  • ElementTypes: Card element type (home, work, ...)

  • ValueType: Value type (usually set by VALUE=)

  • Group: Property group

  • Value: An integer value

  • IsPreferred: Is this part preferred?

You can also use the following functions:

  • HasType(): Checks to see if this value has a specific type

Array of Parts

Parts that can be more than one part (i.e. can be put to an array and can exist more than once per vCard instance) exist in vCard. The above table shows all the properties that are listed as an Array. If they are listed as such, like ATTENDEE, you can get it using GetPartsArray(). You can also get a dictionary of a list of parsed parts array lists using the PartsArray property.

GetPartsArray() is a generic method. This means that you can specify one of the Info classes, as long as it represents a valid class that points to a valid part, such as AttendeeInfo. In this case, you'll have to call it like this:

// Either
Calendar.Events[0].GetPartsArray<AttendeeInfo>()

// or
Calendar.Events[0].GetPartsArray<AttendeeInfo>(CalendarPartsArrayEnum.Attendee)

You can directly get a value of a property without having to cast the resultant part to the correct part info class. The same base properties also apply to the normal Parts.

You can also get any parts array as a base, though you can't call the non-parameterized function against the base part, BaseCardPartInfo. You'll also have to cast the resultant part if you need to access something other than the base properties as mentioned above.

Calendar.Events[0].GetPartsArray<BaseCardPartInfo>(CalendarPartsArrayEnum.Attendee)

This function returns one of the following:

  • An empty array

    • If the parts array is not supported in the contact's vCard version

    • If the parts array is not defined in the contact's vCard instance

  • An array of parts

    • If the part is supported and defined in the contact's vCard instance

Any attempt to specify an incorrect type or enumeration in the second overload of GetPartsArray, such as Calendar.Events[0].GetPartsArray<DateCreatedInfo>(CalendarPartsArrayEnum.Attendee), will throw an exception. However, it doesn't throw an exception in case BaseCardPartInfo is specified.

Getting a Blob Stream

Image parts, icon parts, sound parts, and key parts in a vCalendar instance allow you to get a blob stream from the encoded data that allows you to represent the actual data decoded from the BASE64 encoding as a blob. VisualCard exposes this feature to allow you to perform various operations on them, such as displaying calendar attachments, saving sound attachments as sound files, etc.

You can make use of this feature by invoking the GetBlobData() function from the VcardParserTools class.

This feature doesn't support non-blob values, such as an HTTPS URL to a logo file.

Events, To-dos, and more

A calendar instance may contain one or more of the following components nested inside the root calendar component:

  • Events

  • To-dos

  • Journals

  • Free/busy instances

  • Timezones

    • Standard times

    • Daylight times

  • Event and to-do alarms

You can access this information using their individual properties found in the calendar instance as follows:

  • Events

    • Alarms

  • Todos

    • Alarms

  • Journals

  • FreeBusyList

  • TimeZones

    • StandardTimeList

    • DaylightTimeList

Last updated