Calendar: Managing Events and Tasks

Samsung Web API enables you to manage your schedule and to group related events and tasks using the Calendar API.

A calendar is a collection of events or tasks, depending upon the calendar type. Each event or task has a series of attributes, such as purpose, starting time, and duration.

Note
Due to time zone and daylight saving time, an for ‘today’can actually occur in the past or in the future.

The events and tasks are identified using the CalendarItemId typedef, which is either a CalendarTaskId (for tasks) or CalendarEventId (for events). In recurring events, the CalendarEventId contains a recurrence ID (rid) in addition to the actual event ID, to separately identify each occurrence of the recurring event.

The Calendar API uses the TZDate object of the Time API and not the standard Javascript Date object to handle difficult issues related to the time zone, because the TZDate object handles exact time and provides various utility methods.

The main features of the Calendar API include:

• Calendar management

  To access a calendar item, you must first retrieve the calendar object from the applicable calendar. To access the device calendars, you can use the getDefaultCalendar() method of the CalendarManager interface to retrieve the default calendar, or the getCalendars() method to retrieve all the available calendars as an array.

Note

Using the batch mode with a large number of operations can block other database operations, such as add or remove. To ensure that all database operations are performed and to improve overall application performance, break the batch operation down into multiple smaller batch operations. For example, break down a batch of 100 update requests into 10 batch operations that update 10 records at a time.

• Calendar item management

  You can manage calendar items (add a new item to a calendar or manage a single calendar event) by using the applicable methods of the Calendar interface.

  If you need to update or delete a single instance of a recurring event, get the list of event instances first with the expandRecurrence() method of the CalendarEvent:CalendarItem object. Then, delete the applicable event instance, or update it by calling the update() method with the updateAllInstances parameter set to false.

  You can create and manage multiple calendar items simultaneously by using the applicable batch methods: addBatch(), updateBatch(), and removeBatch(). The batch mode provides faster, optimized processing of multiple calendar items.

  When searching for calendar items, you can create attribute filters, attribute range filters, and composite filters based on specific filter attributes. You can also sort the search results.

• Calendar item alarms

  You can set an alarm for an important event, such as a monthly meeting or a specific task (for example, paying a utility bill), by using the CalendarAlarm interface. The alarm is triggered at a defined time to remind the user of the event or task.

• Calendar change notifications

  You can keep the calendar in your application synchronized with user-specific calendars, such as a calendar on a social networking Web site, by receiving notifications in your application when calendar items change.

  The addChangeListener() method of the Calendar interface registers an event listener, which starts asynchronously once the addChangeListener() method returns the subscription identifier for the listener. You can use the CalendarChangeCallback interface to define listener event handlers for receiving the notifications.

  Every change made to the calendar database triggers an event for which you can define a notification. For batch mode operations, each operation generates only a single event. A recurring calendar event is treated as one event.

• iCalendar 2.0 format conversions

  You can convert the calendar items to iCalendar format or back using the CalendarEvent object constructor and the convertToString() method of the CalendarItem interface, respectively.

  The conversion allows you to exchange calendar data between applications by sharing files with the .ics extension. The iCalendar format is independent of the underlying transport protocol, meaning that calendar items can be exchanged using a variety of transports, including HTTP, SMTP, and Infrared.

  The iCalendar format can be used to store calendar item information and exchange calendar data over the internet.

  The following example shows a sample event in the iCalendar format:

  BEGIN: VCALENDAR
  BEGIN: VEVENT
  DTSTART: 20110714T150000Z
  DTEND: 20110715T173000Z
  SUMMARY: Team meeting
  END: VEVENT
  END: VCALENDAR