CalendarService

Since: BlackBerry 10.0.0

#include <bb/pim/calendar/CalendarService>

To link against this class, add the following line to your .pro file: LIBS += -lbbpim

The CalendarService class provides access to PIM calendar data.

Permissions:

access_pimdomain_calendars

This class is an interface to the calendar service. This service manages a local database and controls a set of synchronization services. Functions in this class affect this database. The signals in this class are emitted by changes in the calendar database, in calendar accounts, or in settings that are relevant to calendar applications (for example, the current timezone).

You can use the CalendarService to create, retrieve, modify, and remove calendar events. For instances of recurring events, the class provides functions for modification and exclusion. There are also functions for responding to requests for meetings and to forward events to email addresses.

Here's an example of how to perform simple operations on a calendar event and save these changes to the database.

CalendarService calendarService;

// create a new event
CalendarEvent ev;
ev.setAccountId(1);
ev.setFolderId(1);
ev.setStartTime(QDateTime(2012, 7, 16, 12, 0, 0));
ev.setEndTime(QDateTime(2012, 7, 16, 13, 0, 0));
ev.setSubject("lunch");

// save it to the database
calendarService.createEvent(ev);

// modify the event, then save it to the database
ev.setStartTime(QDateTime(2012, 7, 16, 12, 30, 0));
ev.setEndTime(QDateTime(2012, 7, 16, 13, 30, 0));
calendarService.updateEvent(ev);

// get any events happening from 12:30 to 13:30
EventSearchParameters params;
params.setStart(QDateTime(2012, 7, 16, 12, 30, 0));
params.setEnd(QDateTime(2012, 7, 16, 13, 30, 0));
params.setDetails(DetailLevel::Full);
QList<CalendarEvent> evs = calendarService.events(params);

// remove the event from the database
calendarService.deleteEvent(ev);

Folders are containers for events. Each folder represents a separate calendar in the Calendar application on the device. You can use the CalendarService to retrieve a list of folders and update the events within these folders. Here's an example of how to do this:

QList<CalendarFolder> folders = calendarService.folders();
CalendarFolder firstFolder = folders.at(0);
firstFolder.setColor(0xFF0000);
calendarService.updateFolder(firstFolder);

You can also retrieve and change calendar-related system settings, such as time zone and snooze time for calendar notifications. These settings are included in the CalendarSettings class, and you can retrieve the current settings by calling CalendarService::settings().

See also:

CalendarEvent


Overview

Public Functions Index

CalendarService ()
virtual ~CalendarService ()
Result::TypeaddOrUpdateEventInICalendarData (AccountId accountId, FolderId folderId, const QString &iCalendarData, const QString &uid=QString())
Result::TypeaddOrUpdateEventInICalendarFile (AccountId accountId, FolderId folderId, const QString &filepath, const QString &uid=QString())
Result::TypeattachCalendar (AccountId calendarId, AccountId messagingId)
QList< AttendeeInEvents >attendees (const AttendeeSearchParameters &params, Result::Type *result=0)
QList< QPair< QString, QString > >attendeesInEvents (const EventSearchParameters &params, Result::Type *result=0)
QMap< QString, QList< CommonAttendee > >commonAttendees (const AnalyticsParams &params, Result::Type *result=0)
QMap< QString, QList< CommonLocation > >commonLocations (const AnalyticsParams &params, Result::Type *result=0)
Result::TypecreateEvent (const CalendarEvent &event, const Notification &notification=Notification())
ICalendarDataPathcreateICalendarData (AccountId accountId, EventId eventId, const QString &destinationPath, Result::Type *result=0)
Result::TypecreateRecurrenceException (const CalendarEvent &occurrence, const QDateTime &originalStartTime, const Notification &notification=Notification())
Result::TypecreateRecurrenceExclusion (const CalendarEvent &occurrence, const Notification &notification=Notification())
QPair< AccountId, FolderId >defaultCalendarFolder (Result::Type *result=0)
Result::TypedeleteEvent (const CalendarEvent &event, const Notification &notification=Notification())
Result::TypedeleteEventByUid (AccountId accountId, const QString &uid, const QDateTime &originalStartTime=QDateTime(), const Notification &notification=Notification())
Result::TypedetachCalendar (AccountId calendarId)
CalendarEventevent (AccountId accountId, EventId eventId, Result::Type *result=0)
QList< CalendarEvent >events (const EventSearchParameters &params, Result::Type *result=0)
QList< CalendarEvent >eventsByUid (AccountId accountId, const QMap< QString, QDateTime > &uids, Result::Type *result=0)
QByteArrayeventToICalendarString (const CalendarEvent &event, Result::Type *result=0)
ICalendarDataPathexportICalendar (AccountId accountId, EventId eventId, const QString &destinationPath, const QDate &trustedDate=QDate(), bool addAttendees=true, int formatVersion=2, Result::Type *result=0)
QList< CalendarFolder >folders (Result::Type *result=0)
Result::TypeforwardEvent (AccountId calendarAccount, EventId calendarEventId, const bb::pim::message::Message &message)
Result::TypeforwardEvent (AccountId calendarAccount, const CalendarEvent &event, const bb::pim::message::Message &message)
QMap< QString, QString >freeBusy (const QStringList &emails, const QDateTime &start, const QDateTime &end, Result::Type *result=0)
QMap< QString, QList< CalendarEvent > >lastEvents (const AnalyticsParams &params, Result::Type *result=0)
QMap< QString, QList< CalendarEvent > >nextEvents (const AnalyticsParams &params, Result::Type *result=0)
CalendarEventparseICalendarData (AccountId calendarAccount, AccountId messagingAccount, const QString &filepath, const QString &mimeType, Result::Type *result=0)
ICalendarObjectsparseICalendarFile (AccountId calendarAccount, AccountId messagingAccount, const QString &filepath, const QString &mimeType, Result::Type *result=0)
Result::TypeproposeNewTime (const CalendarEvent &event, const QDateTime &newTime, AttendeeStatus::Type status, const QString &comments, AccountId emailAccountId, int originalMessageId)
Result::Typereply (const CalendarEvent &event, AttendeeStatus::Type status, const QString &comments, AccountId emailAccountId, bool notify)
Result::TypereplySingleOccurrence (const CalendarEvent &occurrence, const QDateTime &originalStartTime, AttendeeStatus::Type status, const QString &comments, AccountId emailAccountId, bool notify)
Result::TypereplyWithMessageId (const CalendarEvent &event, AttendeeStatus::Type status, const QString &comments, AccountId emailAccountId, bool notify, int originalMessageId)
ICalendarObjectsretrieveICalendarAttachment (AccountId messagingAccount, bb::pim::message::MessageKey messageId, Result::Type *result=0)
Result::TypesetDefaultCalendarFolder (AccountId accountId, FolderId folderId)
CalendarSettingssettings (Result::Type *result=0)
Result::TypeupdateEvent (const CalendarEvent &event, const Notification &notification=Notification())
Result::TypeupdateFolder (const CalendarFolder &folder)
Result::TypeupdateSnoozeDefaultValue (unsigned int minutes)

Signals Index

voidcalendarsChanged ()
voideventsRefreshed (const bb::pim::calendar::EventRefresh &notification)
voidfolderChanged (int folderId, int accountId)
voidfolderCreated (int folderId, int accountId)
voidfolderDeleted (int folderId, int accountId)
voidhourFormatChanged (bool format24Hours)
voidtimezoneChanged (const QString &timezoneId)

Public Functions

CalendarService ()

Constructs a new CalendarService.

Since:

BlackBerry 10.0.0

virtual~CalendarService ()

Destructor.

Since:

BlackBerry 10.0.0

Result::Type addOrUpdateEventInICalendarData (
  • AccountIdaccountId,
  • FolderIdfolderId,
  • const QString &iCalendarData,
  • const QString &uid )

Creates or updates an event from the given iCalendar data.

This function takes the data in the iCalendar string and uses it to create an event in the database. If an event with the same UID already exists, it receives an update.

Only the first event in the iCalendar string is processed.

This function strips off any attendees mentioned in the iCalendar string.

iCalendar is a standard format for representation of events and tasks.
Parameters
accountId

The ID for the account in which the event is created.

folderId

The ID for the folder that contains the event.

iCalendarData

A string containing information about the appointment.

uid

The unique ID for the event. If not provided, the function searches for a UID in the iCalendar string.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.2.0

Result::Type addOrUpdateEventInICalendarFile (
  • AccountIdaccountId,
  • FolderIdfolderId,
  • const QString &filepath,
  • const QString &uid )

Creates or updates an event from the given iCalendar file.

This function takes the data in the iCalendar file and uses it to create an event in the database. If an event with the same UID already exists, it receives an update.

Only the first event in the iCalendar file is processed.

This function strips off any attendees mentioned in the iCalendar file.

iCalendar is a standard format for representation of events and tasks.
Parameters
accountId

The ID for the account in which the event is created.

folderId

The ID for the folder that contains the event.

filepath

The path to the file containing information about the appointment.

uid

The unique ID for the event. If not provided, the function searches for a UID in the iCalendar string.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.2.0

Result::Type attachCalendar (
  • AccountIdcalendarId,
  • AccountIdmessagingId )

Associates a calendar account with a messaging account.

Attached calendar accounts react to messages containing information about meetings:
  • An event is created in the associated calendar when an invitation email arrives.

  • Updates to a meeting received by email are reflected in the corresponding event.

Parameters
calendarId

The ID of the calendar account.

messagingId

The ID of the messaging account.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.0.0

QList< AttendeeInEvents > attendees (

Retrieves the list of people who participate in the specified events with the user.

The AttendeeSearchParameters parameter contains the list of event IDs to process.

Parameters
params

The search parameters.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

A list of attendees who participate in the specified events with the user.

Since:

BlackBerry 10.0.0

QList< QPair< QString, QString > > attendeesInEvents (

QMap< QString, QList< CommonAttendee > > commonAttendees (

Retrieves common participants.

This function returns people that have been in meetings with the user and the given person.

The emails attribute of the AnalyticsParams parameter identifies the person that should participate (along with the user) with the people in common. It's possible to request common attendees for more than one person by adding multiple associations to the emails map. Here's an example:

CalendarService calendarService;
AnalyticsParams params;
QMap<QString, QVariant> map;

QList<QString> emailsFromSchool;
emailsFromSchool.insert("joe@school.org");
map.insert("school", emailsFromSchool);

QList<QString> emailsFromOffice;
emailsFromOffice.insert("jane@office.com");
map.insert("office", emailsFromOffice);
params.setEmails(map);

QMap<QString, QList<CommonAttendee> > resultMap = calendarService.commonAttendees(params);
QList<CommonAttendee> peopleFromSchool = resultMap.value("school");
QList<CommonAttendee> peopleFromOffice = resultMap.value("office");

The number of returned attendees is controlled by the limit attribute of AnalyticsParams.

Parameters
params

The search parameters to use to search for attendees.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

A map that contains the lists of common attendees.

Since:

BlackBerry 10.0.0

QMap< QString, QList< CommonLocation > > commonLocations (

Retrieves common locations.

This function returns places where the user and the given person have met.

The emails attribute of the AnalyticsParams parameter identifies the person that met or will meet the user at the returned places. It's possible to request common locations for more than one person by adding multiple associations to the emails map. Here's an example:

CalendarService calendarService;
AnalyticsParams params;
QMap<QString, QVariant> map;

QList<QString> joeEmails;
joeEmails.insert("joe@school.org");
map.insert("joe", joeEmails);

QList<QString> janeEmails;
janeEmails.insert("jane@office.com");
map.insert("jane", janeEmails);
params.setEmails(map);

QMap<QString, QList<CommonLocation> > resultMap = calendarService.commonLocations(params);
QList<CommonLocation> joePlaces = resultMap.value("joe");
QList<CommonLocation> janePlaces = resultMap.value("jane");

The number of places returned is controlled by the limit attribute of AnalyticsParams.

Parameters
params

The search parameters to use to search for locations.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

A map that contains the lists of common locations.

Since:

BlackBerry 10.0.0

Result::Type createEvent (

Creates an event.

This function adds a new calendar event to the database. Optionally, this function can notify participants by email.

Some accounts are associated with remote databases. If the new event belongs to this type of account, the calendar service communicates with the remote database to replicate the event there.

The event that you want to add should have values for the following parameters:
  • account ID

  • folder ID

  • start time

  • end time

  • subject

The call fails if any of these values are missing.

The notification parameter is optional.

On success, this function sets the event's ID attribute. This function assigns the ID of the new database row to the ID attribute of the event object that you pass as an argument, and the eventsRefreshed() signal is emitted. This signal includes an EventRefresh parameter, and the createdEventIds list in this parameter contains the event ID of the new event.

Parameters
event

The event to be created.

notification

Details for the email notification sent to the participants.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.0.0

ICalendarDataPath createICalendarData (

Creates an iCalendar file for an event.

This function exports the event specified by the account ID and event ID to an iCalendar file.

The calendar service attempts to create the file at the given path. If it's not able to write at the location requested, it creates the file in a directory that's accessible to it. You can retrieve this new path from the result object.

iCalendar is a standard format that represents events and tasks. The format's specification is available at http://tools.ietf.org/html/rfc5545.

Parameters
accountId

The account that contains the event.

eventId

The ID of the event.

destinationPath

The file path where the ICS should be created.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

An ICalendarDataPath object that contains information about the created iCalendar file.

Since:

BlackBerry 10.0.0

Result::Type createRecurrenceException (

Creates a recurrence exception.

A recurrence exception is an instance of a recurring event that differs from the series. This function changes the database so that a new event is created with data from the modified occurrence. This event's parent ID is equal to the recurring event's ID. The original start time of the modified occurrence is added to the list of exceptions in the recurring event.

Some accounts are associated with remote databases. If the recurring event belongs to this type of account, the calendar service communicates with the remote database to create the exception there.

The notification parameter is optional.

On success, the eventsRefreshed() signal is emitted. This signal includes an EventRefresh parameter, and the createdEventIds list in this parameter contains the ID for the exception. The updatedEventIds list in this parameter contains the ID of the recurring event.

Parameters
occurrence

The modified instance of the recurring event.

originalStartTime

The previous start time for the occurrence being changed.

notification

Details for the email notification sent to the participants.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.0.0

Result::Type createRecurrenceExclusion (

Excludes an occurrence of a recurring event.

A recurrence exclusion is a deleted occurrence in a recurring event.

Occurrences don't exist in the database as separate events. They are represented by a unique event that has a non-empty recurrence rule attribute. The rule specifies the dates on which the event occurs. It contains a list of exceptions, which eliminates dates on which the event would otherwise occur.

This function deletes an occurrence by adding its start time to the list of exceptions of the recurring event.

Some accounts are associated with remote databases. If the recurring event belongs to this type of account, the calendar service communicates with the remote database to create the exclusion there.

The notification parameter is optional.

On success, the eventsRefreshed() signal is emitted. This signal includes an EventRefresh parameter, and the updatedEventIds list in this parameter contains the ID of the recurring event.

Parameters
occurrence

The removed occurrence of the recurring event.

notification

Details for the email notification sent to the participants.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.0.0

QPair< AccountId, FolderId > defaultCalendarFolder (

Retrieves the default calendar folder.

This function returns a pair of IDs (an account ID and a folder ID) that determine the default calendar folder. This folder is the preferred location for events created on the device. The user may select it using the Settings application on the device.

A calendar application should let the user choose the folder for a new event. When user doesn't specify a folder, the application should place the new event in the default folder.

Parameters
result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

A pair of identifiers (an account ID and a folder ID) for the default folder.

Since:

BlackBerry 10.0.0

Result::Type deleteEvent (

Deletes an event.

This function removes an event from the database. Optionally, this function can notify participants by email.

Some accounts are associated with remote databases. If the event belongs to this type of account, the calendar service communicates with the remote database to delete the event from it.

The notification parameter is optional.

On success, the eventsRefreshed() signal is emitted. This signal includes an EventRefresh parameter, and the deletedEventIds list in this parameter contains the event ID of the deleted event.

Parameters
event

The event to be removed.

notification

Details for the email notification sent to the participants.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.0.0

Result::Type deleteEventByUid (

Deletes an event specified by a UID.

This function searches the database for an event having the given UID and deletes it. To delete a recurrence exception, you should also specify the original start time.

Some accounts are associated with remote databases. If the event belongs to this type of account, the calendar service communicates with the remote database to delete the event from it.

On success, the eventsRefreshed() signal is emitted. This signal includes an EventRefresh parameter, and the deletedEventIds list in this parameter contains the event ID of the deleted event.

Parameters
accountId

The ID for the account associated with the event.

uid

The event's universal identifier.

originalStartTime

The recurrence exception's original start time.

notification

Details for the email notification sent to the participants.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.2.0

Result::Type detachCalendar (
  • AccountIdcalendarId)

Disassociates a calendar account and a messaging account.

This function disconnects a calendar account from the associated messaging account. Then, the calendar account can be linked to a different messaging account.

Parameters
calendarId

The calendar account to disassociate.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.0.0

CalendarEvent event (

Retrieves an event.

This function retrieves a single event from the database. You must specify the account ID and event ID of the event that you want to retrieve.

Parameters
accountId

The ID of the account that contains the event.

eventId

The ID of the event to retrieve.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

The event with the specified account ID and event ID.

Since:

BlackBerry 10.0.0

QList< CalendarEvent > events (

Retrieves a list of events that match the specified search criteria.

The EventSearchParameters argument defines what events should be returned:
  • The start and end times define a range for the search. Events that enter this range are eligible to be part of the result set.

  • The detail level controls what attributes are returned for each event.

  • The expand flag causes the expansion of the recurring events that cross the query's range.

  • The limit field defines the maximum number of events in the result set.

  • The sort field determines how the result set is ordered.

  • The events list is used to retrieve events by ID.

  • The folders list is used to retrieve events by their folder IDs.

Depending on the number of events in the database and on the breadth of the time range, this operation may take from tenths of seconds to a few seconds.

The calendar service assumes that the start and end times are in the device's time zone.

Parameters
params

The search parameters to use to search for events.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

A list of events that match the specified criteria.

Since:

BlackBerry 10.0.0

QList< CalendarEvent > eventsByUid (

Retrieves a list of events with the specified event IDs.

This function retrieves events based on unique IDs.

You can pass a start time along with each UID. The start time identifies a recurrence exception, and is required because exceptions usually share the UID of the recurring event that originated them.

A UID that doesn't require a start time should be associated with a plain QDateTime. Here's an example:

QMap<QString, QDateTime> uidMap;
uidMap.insert("6ab40924-cfa1-11e1-9852-002241284a73", QDateTime());
QList<CalendarEvent> evs = calendarService.eventsByUid(1, uidMap);

It's possible to request multiple events by adding as many UID/start time pairs to the map parameter as needed.

Parameters
accountId

The ID of the account that contains the specified events.

uids

A map that associates UIDs with original start times. You should pass a QDateTime() if a start time is not required.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

A list of the specified events.

Since:

BlackBerry 10.0.0

QByteArray eventToICalendarString (

Serializes an event as an iCalendar byte array.

This function generates an iCalendar byte array that represents the event passed as parameter.

iCalendar is a standard format for representation of events and tasks.
Parameters
event

The event to be serialized.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

A byte array containing data from the given event.

Since:

BlackBerry 10.1.0

ICalendarDataPath exportICalendar (
  • AccountIdaccountId,
  • EventIdeventId,
  • const QString &destinationPath,
  • const QDate &trustedDate,
  • booladdAttendees,
  • intformatVersion,
  • Result::Type *result )

Exports an event as an iCalendar file.

This function exports the event specified by the account and event IDs to an iCalendar file.

The calendar service attempts to create the file at the given path. If it's not able to write at the location requested, it creates the file in a directory that's accessible to it. You can retrieve this new path from the result object.

You can specify a trusted date. If present, it replaces the date in the event's start and end times.

The addAttendees parameter may be used to suppress the event's participants in the exported file.

iCalendar is a standard format for representation of events and tasks.
Parameters
accountId

The account that contains the event.

eventId

The event identifier.

destinationPath

The path where the file should be created.

trustedDate

A date that replaces the date when the event starts. This parameter is optional.

addAttendees

If true this function generates an iCalendar that includes attendees, if false this function generates an iCalendar without attendees. This parameter is optional.

formatVersion

The iCalendar format version: 2 (default) or 1.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

An instance of ICalendarDataPath, which provides information about the created iCalendar file.

Since:

BlackBerry 10.0.0

QList< CalendarFolder > folders (

Retrieves calendar folders.

This function returns calendar folders from all calendar accounts. A folder is a container for events, and usually serves as a way to classify the events.

Parameters
result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

A list of calendar folders.

Since:

BlackBerry 10.0.0

Result::Type forwardEvent (

Sends a message with an event (specified by event ID) attached.

The calendar service creates an iCalendar attachment with data from the event specified by the provided IDs and sends an email with it.

iCalendar is a standard format that represents events and tasks. The format's specification is available at http://tools.ietf.org/html/rfc5545.

Parameters
calendarAccount

The account to which the event belongs.

calendarEventId

The ID of the event.

message

The message to which the event is attached.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.0.0

Result::Type forwardEvent (

Sends a message with an event (specified by a CalendarEvent) attached.

The calendar service creates an iCalendar attachment with data from the provided event and sends an email with it.

iCalendar is a standard format that represents events and tasks. The format's specification is available at http://tools.ietf.org/html/rfc5545.

Parameters
calendarAccount

The account to which the event belongs.

event

The event to be sent as an ICS.

message

The message to which the event is attached.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.0.0

QMap< QString, QString > freeBusy (

Retrieves free/busy information.

This function returns a map that associates users' email addresses with their free/busy statuses.

Each digit in a free/busy string corresponds to a 30-minute block. The zero digit means that the block is free (no events in the 30-minute interval). The one digit means that the block is tentative (there are events marked as tentative in the interval). The two digit means that the block is busy (there are events marked as busy in the interval).

Parameters
emails

The list of users for whom the free/busy information should be retrieved

start

The start time for the free/busy query.

end

The end time for the free/busy query.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

A map that associates emails and free/busy data.

Since:

BlackBerry 10.0.0

QMap< QString, QList< CalendarEvent > > lastEvents (

Retrieves the last events that involve the specified person.

This function returns the most recent meetings in which the user and the specified person participate.

The emails attribute of the AnalyticsParams parameter identifies the person that should be present in the returned meetings. It's possible to request common past meetings for more than one person by adding multiple associations to the emails map. Here's an example:

CalendarService calendarService;
AnalyticsParams params;
QMap<QString, QVariant> map;

QList<QString> emailsFromSchool;
emailsFromSchool.insert("joe@school.org");
map.insert("school", emailsFromSchool);

QList<QString> emailsFromOffice;
emailsFromOffice.insert("jane@office.com");
map.insert("office", emailsFromOffice);
params.setEmails(map);

QMap<QString, QList<CalendarEvent> > resultMap = calendarService.lastEvents(params);
QList<CalendarEvent> meetingsAtSchool = resultMap.value("school");
QList<CalendarEvent> meetingsAtOffice = resultMap.value("office");

The number of returned meetings is controlled by the limit attribute of AnalyticsParams.

Parameters
params

The search parameters to use to search for events.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

A map that contains the lists of past events involving the specified people.

Since:

BlackBerry 10.0.0

QMap< QString, QList< CalendarEvent > > nextEvents (

Retrieves the next events that involve the specified person.

This function returns the nearest future meetings in which the user and the specified person participate.

The emails attribute of the AnalyticsParams parameter identifies the person that should be present in the returned meetings. It's possible to request future meetings for more than one person by adding multiple associations to the emails map. Here's an example:

CalendarService calendarService;
AnalyticsParams params;
QMap<QString, QVariant> map;

QList<QString> emailsFromSchool;
emailsFromSchool.insert("joe@school.org");
map.insert("school", emailsFromSchool);

QList<QString> emailsFromOffice;
emailsFromOffice.insert("jane@office.com");
map.insert("office", emailsFromOffice);
params.setEmails(map);

QMap<QString, QList<CalendarEvent> > resultMap = calendarService.nextEvents(params);
QList<CalendarEvent> meetingsAtSchool = resultMap.value("school");
QList<CalendarEvent> meetingsAtOffice = resultMap.value("office");

The number of returned meetings is controlled by the limit attribute of AnalyticsParams.

Parameters
params

The search parameters to use to search for events.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

A map that contains the lists of future events involving the specified people.

Since:

BlackBerry 10.0.0

CalendarEvent parseICalendarData (

Parses an iCalendar file.

This function creates a CalendarEvent object with data taken from the provided iCalendar file.

Any information that the database might have on the previous state of the event is returned as part of its iCalendarData attribute.

The iCalendar file is usually an attachment in a message.

iCalendar is a standard format that represents events and tasks. The format's specification is available at http://tools.ietf.org/html/rfc5545.

Parameters
calendarAccount

The account where the event is searched for.

messagingAccount

The messaging account that received the message containing the iCalendar attachment.

filepath

The file path for the iCalendar file.

mimeType

The MIME type for iCalendar (text/calendar, application/ics). This parameter is optional.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

A calendar event that includes the data from the provided iCalendar file.

Since:

BlackBerry 10.0.0

ICalendarObjects parseICalendarFile (

Builds data objects from the contents of an iCalendar file.

This function reads objects from an iCalendar file.

An iCalendar file may contain calendar events and tasks. This function returns an ICalendarObjects object, which contains the event (if one exists) and the task (if one exists) from the file.

Any information the database might have on the previous state of the event is returned as part of its iCalendarData attribute.

The iCalendar file is usually an attachment in a message.

iCalendar is a standard format for representation of events and tasks. The format's specification is available at http://tools.ietf.org/html/rfc5545.

Parameters
calendarAccount

The account where the event is searched for.

messagingAccount

The messaging account that received the message containing the iCalendar attachment.

filepath

The file path for the iCalendar file.

mimeType

The MIME type for iCalendar (text/calendar, application/ics). This parameter is optional.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

An ICalendarObjects object that includes the event and task from the provided iCalendar file.

Since:

BlackBerry 10.0.0

Result::Type proposeNewTime (

Proposes a new time for a meeting.

This function replies to an event with a proposal for a new time.

Parameters
event

The event that's associated with the invitation.

newTime

The new time proposed.

status

The user acceptance status.

comments

Comments to be sent with the reply.

emailAccountId

The messaging account that sends the reply.

originalMessageId

An identifier for the message containing the invitation.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.3

Result::Type reply (

Replies to an invitation with an acceptance status.

This function changes the acceptance status for the provided event and optionally sends a reply message.

Parameters
event

The event that's associated with the invitation.

status

The user acceptance status.

comments

Comments to be sent with the reply.

emailAccountId

The messaging account that sends the reply.

notify

Indicates whether to send a reply or not. If true a reply is sent, if false the calendar service updates only the status for the event and won't send a reply.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.0.0

Result::Type replySingleOccurrence (

Replies to a single occurrence of a recurring event.

This function changes the acceptance status for the provided occurrence of a recurring event and optionally sends a reply message. The occurrence also becomes a recurrence exception event. That is, it is stored in the database as a separate event and it references the original recurring event by using the parent ID, which you can retrieve using CalendarEvent::parentId().

Parameters
occurrence

The modified instance of the recurring event.

originalStartTime

The previous start time for the occurrence being changed.

status

The user acceptance status.

comments

Comments to be sent with the reply.

emailAccountId

The messaging account that sends the reply.

notify

Indicates whether to send a reply or not. If true a reply is sent, if false the calendar service updates only the status for the event and won't send a reply.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.3.0

Result::Type replyWithMessageId (

Replies to an invitation that includes a message ID with an acceptance status.

This function changes the acceptance status for the provided event and optionally sends a reply message. This function includes a parameter that represents the ID of the message containing the invitation.

Parameters
event

The event that's associated with the invitation.

status

The user acceptance status.

comments

Comments to be sent with the reply.

emailAccountId

The messaging account that sends the reply.

notify

Indicates whether to send a reply or not. If true a reply is sent, if false the calendar service updates only the status for the event and won't send a reply.

originalMessageId

An identifier for the message containing the invitation.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.1.0

ICalendarObjects retrieveICalendarAttachment (
  • AccountIdmessagingAccount,
  • bb::pim::message::MessageKeymessageId,
  • Result::Type *result )

Builds objects from the contents of an iCalendar attachment.

This function reads objects from an iCalendar attachment.

An iCalendar attachment may contain calendar events and tasks. This function returns an ICalendarObjects object, which contains the event (if one exists) and the task (if one exists) from the file.

Any information the database might have on the previous state of the event is returned as part of its iCalendarData attribute.

If a message has an iCalendar attachment that is not yet in the device's database, there will be no events or tasks in the ICalendarObjects returned, but the attachment ID will be available (using ICalendarObjects::attachmentKey()). It's possible to request the download of an attachment by calling bb::pim::message::MessageService::downloadAttachment().

iCalendar is a standard format for representation of events and tasks. The format's specification is available at http://tools.ietf.org/html/rfc5545.

Parameters
messagingAccount

The messaging account that received the message containing the iCalendar attachment.

messageId

The ID of the message containing the iCalendar attachment.

result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

An ICalendarObjects object that includes the event and task from the provided iCalendar file.

Since:

BlackBerry 10.3.0

Result::Type setDefaultCalendarFolder (
  • AccountIdaccountId,
  • FolderIdfolderId )

Sets the default calendar folder.

Parameters
accountId

The ID for the account containing the folder.

folderId

The ID for the folder.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.0.0

CalendarSettings settings (

Retrieves system settings for calendar events.

This function returns system settings that are relevant to calendar applications, such as time zone and snooze time for event notifications.

Parameters
result

A pointer to the variable that receives the operation status. This status indicates whether the operation was successful.

Return:

The system settings for calendar events.

Since:

BlackBerry 10.0.0

Result::Type updateEvent (

Changes an event in the database.

This function saves the current state of an event that already exists in the database. Optionally, this function can notify participants by email.

Some accounts are associated with remote databases. If the event belongs to this type of account, the calendar service communicates with the remote database to replicate the changes there.

It's not possible to move an event to a different account by calling this function.

The notification parameter is optional.

On success, the eventsRefreshed() signal is emitted. This signal includes an EventRefresh parameter, and the updatedEventIds list in this parameter contains the event ID of the updated event.

Parameters
event

The event to be updated.

notification

Details for the email notification sent to the participants.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.0.0

Result::Type updateFolder (

Updates a folder in the database.

This function updates a folder in the calendar database with the data from the provided folder.

It is only possible to update a folder's color to one of the following values: 0xF7941E, 0x779933, 0x289FC5, 0x6B3073, 0x53B89D, 0x864301, 0xFFCB1A, 0xF7668F, 0x40C2CC, 0x425DAB, 0x4BB578, 0xCC3399, 0xC0C61D, 0xCB8600, 0x7D5DE3.

Parameters
folder

The folder to be updated.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.0.0

Result::Type updateSnoozeDefaultValue (
  • unsigned intminutes)

Changes the default snooze time for calendar alerts.

The system's notification manager shows visual alerts to inform the user of upcoming events. When an alert is shown, the user has the option of snoozing it, which means it will occur again after a certain time. The time for this next alert is the default snooze value.

Parameters
minutes

The new value for the snooze time, in minutes.

Return:

A result value that indicates whether the operation was successful.

Since:

BlackBerry 10.0.0

Signals

void calendarsChanged ()

Emitted when the list of available calendars has changed.

This signal is emitted when new calendars become available after an account is integrated, removed, or changed.

Since:

BlackBerry 10.0.0

void eventsRefreshed (

Emitted when events are added, changed, or removed.

The CalendarService emits this signal whenever the events in the database change, either as a result of a CalendarService call or after a synchronization process reconciles the local and remote data sources.

Parameters
notification

A list of IDs for added events, changed events, removed events and changed folders.

Since:

BlackBerry 10.0.0

void folderChanged (
  • intfolderId,
  • intaccountId )

Emitted when a folder has been changed.

Parameters
folderId

The ID of the changed folder.

accountId

The account ID that contained the changed folder.

Since:

BlackBerry 10.0.0

void folderCreated (
  • intfolderId,
  • intaccountId )

Emitted when a new folder has been created.

Parameters
folderId

The ID of the new folder.

accountId

The account ID that contains the new folder.

Since:

BlackBerry 10.0.0

void folderDeleted (
  • intfolderId,
  • intaccountId )

Emitted when a folder has been deleted.

Parameters
folderId

The ID of the deleted folder.

accountId

The account ID that contained the deleted folder.

Since:

BlackBerry 10.0.0

void hourFormatChanged (
  • boolformat24Hours)

Emitted when the hour format on the device has changed.

Parameters
format24Hours

If true, the hour format is 24-hour, if false the hour format is not 24-hour.

Since:

BlackBerry 10.0.0

void timezoneChanged (

Emitted when the time zone on the device has changed.

Parameters
timezoneId

The name of the new time zone.

Since:

BlackBerry 10.0.0

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus