Revision control
Copy as Markdown
Other Tools
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
#include "nsISupports.idl"
interface nsIVariant;
interface calIItemACLEntry;
interface calIAlarm;
interface calIAttachment;
interface calIAttendee;
interface calICalendar;
interface calIDateTime;
interface calIDuration;
interface calIIcalComponent;
interface calIRecurrenceInfo;
interface calIRelation;
//
// calIItemBase
//
// Base for Events, Todos, Journals, etc.
//
[scriptable, uuid(9c988b8d-af45-4046-b05e-34417bba9058)]
interface calIItemBase : nsISupports
{
// returns true if this thing is able to be modified;
// if the item is not mutable, attempts to modify
// any data will throw CAL_ERROR_ITEM_IS_IMMUTABLE
readonly attribute boolean isMutable;
// makes this item immutable
void makeImmutable();
// clone always returns a mutable event
calIItemBase clone();
/**
* Returns true if this item is an instance of calIEvent.
*/
boolean isEvent();
/**
* Returns true if this item is an instance of calITodo.
*/
boolean isTodo();
/**
* Hash Id that incorporates the item's UID, RECURRENCE-ID and calendar.id
* to be used for lookup of items that come from different calendars.
* Setting either id, recurrenceId or the calendar attribute leads to
* a recomputation of hashId.
*
* @attention Individual implementors of calIItemBase must stick to the
* same algorithm that base/src/CalItemBase.sys.mjs uses.
*/
readonly attribute AUTF8String hashId;
/**
* Checks whether the argument object refers the same calendar item as
* this one, by testing both the id and recurrenceId property. This
*
* @arg aItem the item to compare against this one
*
* @return true if both ids match, false otherwise
*/
boolean hasSameIds(in calIItemBase aItem);
/**
* Returns the acl entry associated to the item.
*/
readonly attribute calIItemACLEntry aclEntry;
//
// the generation number of this item
//
attribute uint32_t generation;
// the time when this item was created
readonly attribute calIDateTime creationDate;
// last time any attribute was modified on this item, in UTC
readonly attribute calIDateTime lastModifiedTime;
// last time a "significant change" was made to this item
readonly attribute calIDateTime stampTime;
// the calICalendar to which this event belongs
attribute calICalendar calendar;
// the ID of this event
attribute AUTF8String id;
// event title
attribute AUTF8String title;
/**
* The event's description in plain text.
*
* Setting this will reset descriptionHTML.
*/
attribute AUTF8String descriptionText;
/**
* The event's description, as HTML.
*
* The text content MUST match descriptionText but the HTML can contain
* formatting, links etc.
*
* Getter: If HTML was not set, the plain text will be upconverted to HTML.
*
* Setter: Setting HTML data will set descriptionText to the
* downconverted pretty-printed plain text.
*/
attribute AUTF8String descriptionHTML;
// event priority
attribute short priority;
attribute AUTF8String privacy;
// status of the event
attribute AUTF8String status;
// ical interop; writing this means parsing
// the ical string into this event
attribute AUTF8String icalString;
// an icalComponent for this item, suitable for serialization.
// the icalComponent returned is not live: changes in it or this
// item will not be reflected in the other.
attribute calIIcalComponent icalComponent;
//
// alarms
//
/**
* Get all alarms assigned to this item
*
* @param aAlarms The array of calIAlarms
*/
Array<calIAlarm> getAlarms();
/**
* Add an alarm to the item
*
* @param aAlarm The calIAlarm to add
*/
void addAlarm(in calIAlarm aAlarm);
/**
* Delete an alarm from the item
*
* @param aAlarm The calIAlarm to delete
*/
void deleteAlarm(in calIAlarm aAlarm);
/**
* Clear all alarms from the item
*/
void clearAlarms();
// The last time this alarm was fired and acknowledged by the user; coerced to UTC.
attribute calIDateTime alarmLastAck;
//
// recurrence
//
attribute calIRecurrenceInfo recurrenceInfo;
readonly attribute calIDateTime recurrenceStartDate;
//
// All event properties are stored in a property bag;
// some number of these are "promoted" to top-level
// accessor attributes. For example, "SUMMARY" is
// promoted to the top-level "title" attribute.
//
// If you use the has/get/set/deleteProperty
// methods, property names are case-insensitive.
//
// For purposes of ICS serialization, all property names in
// the hashbag are in uppercase.
//
// The isPropertyPromoted() attribute can will indicate
// if a particular property is promoted or not, for
// serialization purposes.
//
// Note that if this item is a proxy, then any requests for
// non-existent properties will be forward to the parent item.
// some other properties that may exist:
//
// 'description' - description (string)
// 'location' - location (string)
// 'categories' - categories (string)
// 'syncId' - sync id (string)
// 'inviteEmailAddress' - string
// alarmLength/alarmUnits/alarmEmailAddress/lastAlarmAck
// recurInterval/recurCount/recurWeekdays/recurWeeknumber
// these forward to an internal property bag; implemented here, so we can
// do access control on set/delete to have control over mutability.
// Each inner array has two elements: a string and a nsIVariant.
readonly attribute Array<Array<jsval> > properties;
boolean hasProperty(in AString name);
/**
* Gets a particular property.
* Objects passed back are still owned by the item, e.g. if callers need to
* store or modify a calIDateTime they must clone it.
*/
nsIVariant getProperty(in AString name);
/**
* Sets a particular property.
* Ownership of objects gets passed to the item, e.g. callers must not
* modify a calIDateTime after it's been passed to an item.
*
* @warning this reflects the current implementation
* xxx todo: rethink whether it's more sensible to store
* clones in calItemBase.
*/
void setProperty(in AString name, in nsIVariant value);
// will not throw an error if you delete a property that doesn't exist
void deleteProperty(in AString name);
// returns true if the given property is promoted to some
// top-level attribute (e.g. id or title)
boolean isPropertyPromoted(in AString name);
/**
* Returns a particular parameter value for a property, or null if the
* parameter does not exist. If the property does not exist, throws.
*
* @param aPropertyName the name of the property
* @param aParameterName the name of the parameter on the property
*/
AString getPropertyParameter(in AString aPropertyName,
in AString aParameterName);
/**
* Checks if the given property has the given parameter.
*
* @param aPropertyName The name of the property.
* @param aParameterName The name of the parameter on the property.
* @return True, if the parameter exists on the property
*/
boolean hasPropertyParameter(in AString aPropertyName,
in AString aParameterName);
/**
* Sets a particular parameter value for a property, or unsets if null is
* passed. If the property does not exist, throws.
*
* @param aPropertyName The name of the property
* @param aParameterName The name of the parameter on the property
* @param aParameterValue The value of the parameter to set
*/
void setPropertyParameter(in AString aPropertyName,
in AString aParameterName,
in AUTF8String aParameterValue);
/**
* Returns the names of all the parameters set on the given property.
*
* @param aPropertyName {AString} The name of the property.
* @return {Array<AString} The parameter names.
*/
Array<AString> getParameterNames(in AString aPropertyName);
/**
* The organizer (originator) of the item. We will likely not
* honour or preserve all fields in the calIAttendee passed around here.
* A base class like calIPerson might be more appropriate here, if we ever
* grow one.
*/
attribute calIAttendee organizer;
//
// Attendees
//
// The array returned here is not live; it will not reflect calls to
// removeAttendee/addAttendee that follow the call to getAttendees.
Array<calIAttendee> getAttendees();
/**
* getAttendeeById's matching is done in a case-insensitive manner to handle
* places where "MAILTO:" or similar properties are capitalized arbitrarily
* by different calendar clients.
*/
calIAttendee getAttendeeById(in AUTF8String id);
void addAttendee(in calIAttendee attendee);
void removeAttendee(in calIAttendee attendee);
void removeAllAttendees();
//
// Attachments
//
Array<calIAttachment> getAttachments();
void addAttachment(in calIAttachment attachment);
void removeAttachment(in calIAttachment attachment);
void removeAllAttachments();
//
// Categories
//
/**
* Gets the array of categories this item belongs to.
*/
Array<AString> getCategories();
/**
* Sets the array of categories this item belongs to.
*/
void setCategories(in Array<AString> aCategories);
//
// Relations
//
/**
* This gives back every relation where the item is neither the owner of the
* relation nor the referred relation
*/
Array<calIRelation> getRelations();
/**
* Adds a relation to the item
*/
void addRelation(in calIRelation relation);
/**
* Removes the relation for this item and the referred item
*/
void removeRelation(in calIRelation relation);
/**
* Removes every relation for this item (in this items and also where it is referred
*/
void removeAllRelations();
// Occurrence querying
//
/**
* Return a list of occurrences of this item between the given dates. The items
* returned are the same type as this one, as proxies.
*/
Array<calIItemBase> getOccurrencesBetween(in calIDateTime aStartDate, in calIDateTime aEndDate);
/**
* If this item is a proxy or overridden item, parentItem will point upwards
* to our parent. Otherwise, it will point to this.
* parentItem can thus always be used for modifyItem() calls
* to providers.
*/
attribute calIItemBase parentItem;
/**
* The recurrence ID, a.k.a. DTSTART-of-calculated-occurrence,
* or null if this isn't an occurrence.
* Be conservative about setting this. It isn't marked as such, but
* consider it as readonly.
*/
attribute calIDateTime recurrenceId;
};