Manipulating Events and To-dos
Major Interfaces and Classes
Below you can see a class diagram with major interfaces used to create calendars, events, to-dos:
Creating Events and To-dos
To create a new calendar object use the CalendarFactory class which provides a single static method for creating new calendars - CreateCalendar2. The ICalendar2 interfaces returned from this method represents a VCALENDAR object and provides properties and methods for accessing VCALENDAR properties and managing events, to-dos, journals, free-busy and time zones.
For example to create a new event use the ICalendar2.Events collection. Call IComponentList<T>.CreateComponent method to create a new event and use Add method to add it to the list:
LicenseValidator.SetLicense("<?xml ...");
ICalendar2 cal = CalendarFactory.CreateCalendar2();
IEvent evt = cal.Events.CreateComponent();
// Create SUMMARY property
ICalText summaryProp = cal.CreateProperty<ICalText>();
summaryProp.Text = "Meeting";
evt.Summary = summaryProp;
// Create DTSTART property
ICalDate startProp = cal.CreateProperty<ICalDate>();
startProp.Value = newDate(newDateTime(2017, 4, 20, 3, 40, 0));
startProp.TimeZoneId = "Africa/Johannesburg";
evt.Start = startProp;
...
cal.Events.Add(evt);
string strCal = new vFormatter().Serialize(cal)
As you can see in the above example to create new properties you will use the ICalendar2.CreateProperty method. This is a generic method in which you will pass the type of the property that you wish to create. You can also create properties using helper methods, see below.
List-Properties
Many properties can be present in iCalendar more than once. Such properties are represented by IPropertyList<T> interface or interfaces derived from it, such as ITextPropertyList<T>. To create a new property call CreateProperty method, to add an item to the list call Add method:
ICalText commentProp = evt.Comments.CreateProperty(); commentProp.Text = "Bring project documentation"; evt.Comments.Add(commentProp);
or in the case or ITextPropertyList<T> you can directly call Add method specifying text:
evt.Comments.Add("Bring project documentation");
Deleting Properties
To delete any property that has a cardinality of 1 or 0 assign null as a value:
evt.Description = null;
For list-properties call Clear() method:
evt.Comments.Clear()
Required Properties
Even though with IT Hit Collab library you are free to create iCalendar objects with any properties the iCalendar standard implies a limitation on a minimum number of properties you must provide in the component. For example, all events, to-dos, journals and free-busy components must provide Uid (UID) and DateTimeStampUtc (DTSTAMP) properties:
ICalendar2 cal = CalendarFactory.CreateCalendar2(); IEvent evt = cal.Events.CreateComponent(); // UID property ITextProperty uidProp = cal.CreateProperty<ITextProperty>(); uidProp.Text = Guid.NewGuid().ToString().ToUpper(); // iOS and OS X require uppercase UID! evt.Uid = uidProp; // DTSTAMP property IDate dtStampProp = cal.CreateProperty<IDate>(); dtStampProp.Value = newDate(DateTime.UtcNow); evt.DateTimeStampUtc = dtStampProp; ... cal.Events.Add(evt);
For other types of components, such as IAlarm, ITimeZone, etc. you can find which properties are required in the class reference documentation in the interface description.
Creating Properties using Helper Methods
Many properties in iCalendar standard have several parameters that may require knowledge of iCalendar standard. To simplify the creation of such properties the ICalendar2 class provides a bunch of CreateX methods. For example, the code from the previous example could be rewritten as:
ICalendar2 cal = CalendarFactory.CreateCalendar2(); IEvent evt = cal.Events.CreateComponent(); evt.Uid = cal.CreateTextProp(Guid.NewGuid().ToString().ToUpper()); evt.DateTimeStampUtc = cal.CreateDateProp(DateTime.UtcNow, DateTimeKind.Utc); ... cal.Events.Add(evt);
Another functionality that helper method provides – is a convenient way to process nulls, typically when reading data from the database, CMS/CRM/ERP or any other storage. All helper methods support null as at least one of the parameters and return null if null is passed. This eliminates the need to analyze your data for null values in most cases. Here is one example how you can use the DataRow class to read nullable values from database and assign IEvent properties:
DataRow row = ...
evt.CreatedUtc = cal.CreateDateProp(row.Field<DateTime?>("CreatedUtc"), DateTimeKind.Utc); // CREATED property
evt.LastModifiedUtc = cal.CreateDateProp(row.Field<DateTime?>("LastModifiedUtc"), DateTimeKind.Utc); // LAST-MODIFIED property
evt.Summary = cal.CreateCalTextProp(row.Field<string>("Summary")); // SUMMARY property
evt.Start = cal.CreateCalDateProp(row.Field<DateTime?>("Start"), row.Field<string>("StartTimeZoneId"), isAllDay); // DTSTART property
evt.Duration = cal.CreateDurationProp(row.Field<long?>("Duration")); // DURATION property
evt.Class = cal.CreateClassProp(row.Field<string>("Class")); // CLASS property
evt.Location = cal.CreateCalTextProp(row.Field<string>("Location")); // LOCATION property
evt.Priority = cal.CreateIntegerProp(row.Field<int?>("Priority")); // PRIORITY property
evt.Sequence = cal.CreateIntegerProp(row.Field<int?>("Sequence")); // SEQ property
evt.Status = cal.CreateStatusProp(row.Field<string>("Status")); // STATUS property
evt.Organizer = cal.CreateCalAddressProp(EmailToUri(row.Field<string>("OrganizerEmail")), row.Field<string>("OrganizerCommonName")); // ORGANIZER property
If null is assigned to a property - the property is not created and if it exists – it will be deleted.
Serializing Calendars
To serialize your calendar object to a string or stream use the vFormatter.Serialize() method:
ICalendar2 cal = CalendarFactory.CreateCalendar2(); ... string strCal = new vFormatter().Serialize(cal);
Deserializing Calendars
To deserialize a calendar from string or stream use the vFormatter.Deserialize() method. A string or stream passed as a parameter to this method can contain more than one calendar object, so the deserialization methods return a list of calendars:
string strCal = File.ReadAllText(“C:\\event.ics”); IEnumerable<ICalendar2> calList = newvFormatter().Deserialize(strCal).Cast<ICalendar2>();
The Deserialize method is used to deserialize both business cards and calendar objects. That is why after deserialization you have to cast each object to ICalendar2 or ICardX interfaces.