diff options
Diffstat (limited to 'comm/calendar/base/public/calIItemBase.idl')
| -rw-r--r-- | comm/calendar/base/public/calIItemBase.idl | 372 |
1 files changed, 372 insertions, 0 deletions
diff --git a/comm/calendar/base/public/calIItemBase.idl b/comm/calendar/base/public/calIItemBase.idl new file mode 100644 index 0000000000..f87935b297 --- /dev/null +++ b/comm/calendar/base/public/calIItemBase.idl @@ -0,0 +1,372 @@ +/* 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 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#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.js 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; +}; |