Calendar Parts

How do the calendar parts work in VisualCard?

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

• Strings

• Integers

• Array of parts

Supported calendar parts across vCalendar versions

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	●

Required calendar parts for vCalendar instances

When parsing vCalendar string representation, VisualCard checks for the below requirements:

• Root calendar component (after START:VCALENDAR before any START:VCOMPONENT specifier)

  • PRODID is required in vCalendar v2.0 but not v1.0

• Events and To-dos (after START:VEVENT or START:VTODO)

  • UID and DTSTAMP properties are required in vCalendar v2.0 but not v1.0

In addition to the above requirements, there are vCalendar 2.0 components that have their own requirements according to the specification:

• Journals and Free/Busy info (after START:VJOURNAL or START:VFREEBUSY)

  • UID and DTSTAMP properties are required

• Time zone info (after START:VTIMEZONE before standard/daylight components)

  • TZID is required

• Standard and daylight info (after START:STANDARD or START:DAYLIGHT)

  • DTSTART is required

  • TZOFFSETFROM and TZOFFSETTO is required

Creating an empty vCalendar instance

You can create empty calendar instances using the Calendar class constructor, but you'll have to specify a version of vCalendar to be used, such as 1.0 or 2.0. The simplest way to create a calendar instance with no properties is:

var calendar = new Calendar(new(2, 0));

The same is true for calendar components, such as CalendarAlarm which you can use to add a new alarm to the calendar using AddAlarm() and remove an alarm from the calendar using RemoveAlarm()

---

Types for some properties

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.

You can access all extra X-named and IANA properties by calling GetExtraPartsArray, passing it either the XNameInfo or the ExtraInfo type as a generic type argument. You can also get all parsed extra X-named and IANA calendar 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.

Obtaining a string or a group of strings

String properties, 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.

---

Integers

Integers in vCalendar and VisualCard are the simplest of the types that allow you to input just a number that represents that property.

Obtaining an integer or a group of integers

Integer properties, 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.

---

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 vCalendar instance) exist in vCalendar.

Obtaining a parts array

Array properties like ATTENDEE can be get 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.

---

Miscellaneous operations

In addition to obtaining strings and parts array, you can also perform other operations that you can take a look at below:

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:

Component	Subcomponent
Events	Event alarms
To-dos	To-do alarms
Journals
Free/busy instances
Timezones	Standard times
	Daylight times

Accessing components

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

Property	Description
Events	Gets a list of events
Events.Alarms	Gets a list of event alarms
Todos	Gets a list of todos
Todos.Alarms	Gets a list of todo alarms
Journals	Gets a list of journals
FreeBusyList	Gets a list of free-busy lists
TimeZones	Gets a list of time zones
TimeZones.StandardTimeList	Gets a list of time zone standard times
TimeZones.DaylightTimeList	Gets a list of time zone daylight times

Adding and deleting components

You can add or remove compatible components to a calendar instance or its compatible parent component to add new information, such as adding new events or event alarms. The following functions are available:

Property	Functions
Events	AddEvent(), DeleteEvent()
Events.Alarms	AddAlarm(), DeleteAlarm()
Todos	AddTodo(), DeleteTodo()
Todos.Alarms	AddAlarm(), DeleteAlarm()
Journals	AddJournal(), DeleteJournal()
FreeBusyList	AddFreeBusy(), DeleteFreeBusy()
TimeZones	AddTimeZone(), DeleteTimeZone()
TimeZones.StandardTimeList	AddStandardTime(), DeleteStandardTime()
TimeZones.DaylightTimeList	AddDaylightTime(), DeleteDaylightTime()

Supported status types

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

vCalendar version	Component	Status
v1.0	Event	NEEDS ACTION
		SENT
		TENTATIVE
		CONFIRMED
		DECLINED
		DELEGATED
	To-do	NEEDS ACTION
		SENT
		ACCEPTED
		COMPLETED
		DECLINED
		DELEGATED
v2.0	Event	TENTATIVE
		CONFIRMED
		CANCELLED
	To-do	NEEDS-ACTION
		COMPLETED
		IN-PROCESS
		CANCELLED
	Journal	DRAFT
		FINAL
		CANCELLED

Supported event/to-do alarm type

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

• AUDIO

• DISPLAY

• EMAIL