Back to index

lightning-sunbird  0.9+nobinonly
Public Member Functions | Public Attributes
calICalDavCalendar Interface Reference

Adds CalDAV specific capabilities to calICalendar. More...

import "calICalDavCalendar.idl";

Inheritance diagram for calICalDavCalendar:
Inheritance graph
[legend]
Collaboration diagram for calICalDavCalendar:
Collaboration graph
[legend]

List of all members.

Public Member Functions

nsIVariant getProperty (in AUTF8String aName)
 Gets a calendar property.
void setProperty (in AUTF8String aName, in nsIVariant aValue)
 Sets a calendar property.
void deleteProperty (in AUTF8String aName)
 Deletes a calendar property.
void addObserver (in calIObserver observer)
void removeObserver (in calIObserver observer)
calIOperation addItem (in calIItemBase aItem, in calIOperationListener aListener)
 The following five "Item" functions are all asynchronous, and return their results to a calIOperationListener object.
calIOperation adoptItem (in calIItemBase aItem, in calIOperationListener aListener)
 adoptItem adds the given calIItemBase to the calendar, but doesn't clone it.
calIOperation modifyItem (in calIItemBase aNewItem, in calIItemBase aOldItem, in calIOperationListener aListener)
 modifyItem takes a modified item and modifies the calendar's internal version of the item to match.
calIOperation deleteItem (in calIItemBase aItem, in calIOperationListener aListener)
 deleteItem takes an item that is to be deleted.
calIOperation getItem (in string aId, in calIOperationListener aListener)
 Get a single event.
calIOperation getItems (in unsigned long aItemFilter, in unsigned long aCount, in calIDateTime aRangeStart, in calIDateTime aRangeEndEx, in calIOperationListener aListener)
 XXX As mentioned above, this method isn't suitably general.
calIOperation refresh ()
 Refresh the datasource, and call the observers for any changes found.
void startBatch ()
 Turn on batch mode.
void endBatch ()
 Turn off batch mode.

Public Attributes

readonly attribute AUTF8String authRealm
 The calendar's RFC 2617 authentication realm.
attribute AUTF8String id
 Unique ID of this calendar.
attribute AUTF8String name
 Name of the calendar Notes: Can only be set after the calendar is registered with the calendar manager.
readonly attribute AUTF8String type
 Type of the calendar 'memory', 'storage', 'caldav', etc.
attribute calICalendar superCalendar
 Multiple calendar instances may be composited, logically acting as a single calendar, e.g.
attribute nsIURI uri
 Setting this URI causes the calendar to be (re)loaded.
attribute boolean readOnly
 Is this calendar read-only? Used by the UI to decide whether or not widgetry should allow editing.
readonly attribute boolean canRefresh
 Whether or not it makes sense to call refresh() on this calendar.
attribute boolean transientProperties
 Setting this attribute to true will prevent the calendar to make calendar properties persistent, which is useful if you would like to set properties on unregistered calendar instances.
const unsigned long ITEM_FILTER_COMPLETED_YES = 1 << 0
 In combination with the other parameters to getItems(), these constants provide for a very basic filtering mechanisms for use in getting and observing items.
const unsigned long ITEM_FILTER_COMPLETED_NO = 1 << 1
const unsigned long ITEM_FILTER_COMPLETED_ALL
const unsigned long ITEM_FILTER_TYPE_TODO = 1 << 2
const unsigned long ITEM_FILTER_TYPE_EVENT = 1 << 3
const unsigned long ITEM_FILTER_TYPE_JOURNAL = 1 << 4
const unsigned long ITEM_FILTER_TYPE_ALL
const unsigned long ITEM_FILTER_ALL_ITEMS = 0xFFFF
const unsigned long ITEM_FILTER_CLASS_OCCURRENCES = 1 << 16
 If set, return calIItemBase occurrences for all the appropriate instances, as determined by an item's recurrenceInfo.
const unsigned long ITEM_FILTER_REQUEST_NEEDS_ACTION = 1 << 17
 Scope: Attendee Filter items that correspond to an invitation from another user and the current user has not replied to it yet.

Detailed Description

Adds CalDAV specific capabilities to calICalendar.

Definition at line 45 of file calICalDavCalendar.idl.


Member Function Documentation

The following five "Item" functions are all asynchronous, and return their results to a calIOperationListener object.

addItem adds the given calIItemBase to the calendar.

Parameters:
aItemitem to add
aListenerwhere to call back the results
Returns:
optional operation handle to track the operation
  • If aItem already has an ID, that ID is used when adding.
    • If aItem is mutable and has no ID, the calendar is expected to generate an ID for the item.
    • If aItem is immutable and has no ID, an error is thrown.

The results of the operation are reported through an onOperationComplete call on the listener, with the following parameters:

If an item with a given ID already exists in the calendar, onOperationComplete is called with an aStatus of NS_ERROR_XXXXX, and aDetail set with the calIItemBase of the internal already existing item.

void calICalendar::addObserver ( in calIObserver  observer) [inherited]

adoptItem adds the given calIItemBase to the calendar, but doesn't clone it.

It adopts the item as-is. This is generally for use in performance-critical situations where there is no danger of the caller using the item after making the call.

See also:
addItem

deleteItem takes an item that is to be deleted.

The item is expected to have an ID that already exists in the calendar; if it doesn't, or there is no id, onOperationComplete is called with a status of NS_ERROR_XXXXX.

Parameters:
aItemitem to delete
aListenerwhere to call back the results
Returns:
optional operation handle to track the operation

The results of the operation are reported through an onOperationComplete call on the listener, with the following parameters:

void calICalendar::deleteProperty ( in AUTF8String  aName) [inherited]

Deletes a calendar property.

It's up to the provider where to store properties, e.g. on the server or in local prefs.

Parameters:
aNameproperty name
void calICalendar::endBatch ( ) [inherited]

Turn off batch mode.

calIOperation calICalendar::getItem ( in string  aId,
in calIOperationListener  aListener 
) [inherited]

Get a single event.

The event will be typed as one of the subclasses of calIItemBase (whichever concrete type is most appropriate).

Parameters:
aIdUID of the event
aListenerlistener to which this event will be called back.
Returns:
optional operation handle to track the operation

The results of the operation are reported through the listener, via zero or one onGetResult calls (with aCount set to 1) followed by an onOperationComplete.

The parameters to onOperationComplete will be:

  • aOperationType: calIOperationListener::GET
    • aId: the ID of the requested item
    • aDetail: null (? we can also pass the item back here as well,..)
calIOperation calICalendar::getItems ( in unsigned long  aItemFilter,
in unsigned long  aCount,
in calIDateTime  aRangeStart,
in calIDateTime  aRangeEndEx,
in calIOperationListener  aListener 
) [inherited]

XXX As mentioned above, this method isn't suitably general.

It's just placeholder until it gets supplanted by something more SQL or RDF-like.

Ordering: This method is currently guaranteed to return lists ordered as follows to make for the least amount of pain when migrating existing frontend code:

The events are sorted based on the order of their next occurrence if they recur in the future or their last occurrence in the past otherwise. Here's a presentation of the sort criteria using the time axis:

-----(Last occurrence of Event1)---(Last occurrence of Event2)----(Now)----(Next occurrence of Event3)---->

(Note that Event1 and Event2 will not recur in the future.)

We should probably be able get rid of this ordering constraint at some point in the future.

Note that the range is intended to act as a mask on the occurrences, not just the initial recurring items. So if a getItems() call without ITEM_FILTER_CLASS_occurrenceS is made, all events and todos which have occurrences inside the range should be returned, even if some of those events or todos themselves live outside the range.

Parameters:
aItemFilterITEM_FILTER flags, or-ed together
aCountMaximum number of items to return, or 0 for an unbounded query.
aRangeStartItems starting at this time or after should be returned. If invalid, assume "since the beginning of time".
aRangeEndExItems starting before (not including) aRangeEndEx should be returned. If null, assume "until the end of time".
aListenerThe results will be called back through this interface.
Returns:
optional operation handle to track the operation

The results of the operation are reported through the listener, via zero or more onGetResult calls followed by an onOperationComplete.

The parameters to onOperationComplete will be:

nsIVariant calICalendar::getProperty ( in AUTF8String  aName) [inherited]

Gets a calendar property.

The call returns null in case the property is not known; callers should use a sensible default in that case.

It's up to the provider where to store properties, e.g. on the server or in local prefs.

Currently known properties are: [boolean] disabled [boolean] calendar-main-in-composite [string] name [boolean] readOnly [boolean] requiresNetwork If false, the calendar does not require network access at all. This is mainy used as a UI hint. [boolean] suppressAlarms If true, alarms of this calendar are not minded. [boolean] cache.supported If true, the calendar should to be cached, e.g. this generally applies to network calendars; default is true (if not present). [boolean] cache.enabled If true, the calendar is cached; default is false.

[nsresult] currentStatus The current error status of the calendar (transient).

[calIItipTransport] itip.transport If the provider implements a custom calIItipTransport (transient) If null, then Email Scheduling will effectively be disabled. This means for example, the calendar will not show up in the list of calendars to store an invitation in. [boolean] itip.disableRevisionChecks If true, the iTIP handling code disables revision checks against SEQUENCE and DTSTAMP, and will never reject an iTIP message as outdated [nsIMsgIdentity] imip.identity If provided, this is the email identity used for scheduling purposes [boolean] imip.identity.disabled If true, this calendar doesn't support switching imip identities. This for example means that the dropdown of identities will not be shown in the calendar properties dialog. (transient) scheduling purposes [nsIMsgAccount] imip.account If provided, this is the email account used for scheduling purposes [string] imip.identity.key If provided, this is the email internal identity key used to get the above

[string] organizerId If provided, this is the preset organizer id on creating scheduling appointments (transient) [string] organizerCN If provided, this is the preset organizer common name on creating scheduling appointments (transient)

The following calendar capabilities can be used to inform the UI or backend that certain features are not supported. If not otherwise mentioned, not specifying these capabilities assumes a default value of true capabilities.attachments.supported Supports attachments capabilities.privacy.supported Supports a privacy state capabilities.priority.supported Supports the priority field capabilities.events.supported Supports tasks capabilities.tasks.supported Supports events capabilities.alarms.popup.supported Supports popup alarms capabilities.alarms.oninviations.supported Supports alarms on inviations. capabilities.timezones.floating.supported Supports local time capabilities.timezones.UTC.supported Supports UTC/GMT timezone

The following capabilities are used to restrict the values for specific fields. An array should be specified with the values, the default values are specified here. Extensions using this need to take care of adding any UI elements needed in an overlay. To make sure the correct elements are shown, those elements should additionally specify an attribute "provider", with the type of the provider.

capabilities.privacy.values = ["PUBLIC", "CONFIDENTIAL", "PRIVATE"];

Parameters:
aNameproperty name
Returns:
value (string, integer and boolean values are supported), else null
calIOperation calICalendar::modifyItem ( in calIItemBase  aNewItem,
in calIItemBase  aOldItem,
in calIOperationListener  aListener 
) [inherited]

modifyItem takes a modified item and modifies the calendar's internal version of the item to match.

The item is expected to have an ID that already exists in the calendar; if it doesn't, or there is no id, onOperationComplete is called with a status of NS_ERROR_XXXXX. If the item is immutable, onOperationComplete is called with a status of NS_ERROR_XXXXX.

If the generation of the given aNewItem does not match the generation of the internal item (indicating that someone else modified the item), onOperationComplete is called with a status of NS_ERROR_XXXXX and aDetail is set to the latest-version internal immutable item.

Parameters:
aNewItemnew version to replace the old one
aOldItemcaller's view of the item to be changed, as it is now
aListenerwhere to call back the results
Returns:
optional operation handle to track the operation

The results of the operation are reported through an onOperationComplete call on the listener, with the following parameters:

Refresh the datasource, and call the observers for any changes found.

If the provider doesn't know the details of the changes it must call onLoad on its observers.

Returns:
optional operation handle to track the operation
void calICalendar::removeObserver ( in calIObserver  observer) [inherited]
void calICalendar::setProperty ( in AUTF8String  aName,
in nsIVariant  aValue 
) [inherited]

Sets a calendar property.

This will (only) cause a notification onPropertyChanged() in case the value has changed.

It's up to the provider where to store properties, e.g. on the server or in local prefs.

Parameters:
aNameproperty name
aValuevalue (string, integer and boolean values are supported)
void calICalendar::startBatch ( ) [inherited]

Turn on batch mode.

Observers will get a notification of this. They will still get notified for every individual change, but they are free to ignore those notifications. Use this when a lot of changes are about to happen, and it would be useless to refresh the display (or the backend store) for every change. Caller must make sure to also call endBatchMode. Make sure all errors are caught!


Member Data Documentation

The calendar's RFC 2617 authentication realm.

Definition at line 50 of file calICalDavCalendar.idl.

Whether or not it makes sense to call refresh() on this calendar.

Definition at line 111 of file calICalendar.idl.

attribute AUTF8String calICalendar::id [inherited]

Unique ID of this calendar.

Only the calendar manager is allowed to set this attribute. For everybody else, it should be considered to be read-only. The id is null for unregistered calendars.

Definition at line 70 of file calICalendar.idl.

const unsigned long calICalendar::ITEM_FILTER_ALL_ITEMS = 0xFFFF [inherited]

Definition at line 249 of file calICalendar.idl.

const unsigned long calICalendar::ITEM_FILTER_CLASS_OCCURRENCES = 1 << 16 [inherited]

If set, return calIItemBase occurrences for all the appropriate instances, as determined by an item's recurrenceInfo.

All of these occurrences will have their parentItem set to the recurrence parent. If not set, will return only calIItemBase parent items.

Definition at line 257 of file calICalendar.idl.

Initial value:

Definition at line 239 of file calICalendar.idl.

const unsigned long calICalendar::ITEM_FILTER_COMPLETED_NO = 1 << 1 [inherited]

Definition at line 238 of file calICalendar.idl.

const unsigned long calICalendar::ITEM_FILTER_COMPLETED_YES = 1 << 0 [inherited]

In combination with the other parameters to getItems(), these constants provide for a very basic filtering mechanisms for use in getting and observing items.

At some point fairly soon, we're going to need to generalize this mechanism significantly (so we can allow boolean logic, categories, etc.).

When adding item filters (bits which, when not set to 1, reduce the scope of the results), use bit positions <= 15, so that ITEM_FILTER_ALL_ITEMS remains compatible for components that have the constant compiled in.

XXX the naming here is questionable; adding a filter (setting a bit, in this case) usually reduces the set of items that pass the set of filters, rather than adding to it.

Definition at line 237 of file calICalendar.idl.

Scope: Attendee Filter items that correspond to an invitation from another user and the current user has not replied to it yet.

Definition at line 264 of file calICalendar.idl.

const unsigned long calICalendar::ITEM_FILTER_TYPE_EVENT = 1 << 3 [inherited]

Definition at line 243 of file calICalendar.idl.

const unsigned long calICalendar::ITEM_FILTER_TYPE_JOURNAL = 1 << 4 [inherited]

Definition at line 244 of file calICalendar.idl.

const unsigned long calICalendar::ITEM_FILTER_TYPE_TODO = 1 << 2 [inherited]

Definition at line 242 of file calICalendar.idl.

attribute AUTF8String calICalendar::name [inherited]

Name of the calendar Notes: Can only be set after the calendar is registered with the calendar manager.

Definition at line 76 of file calICalendar.idl.

Is this calendar read-only? Used by the UI to decide whether or not widgetry should allow editing.

Definition at line 106 of file calICalendar.idl.

Multiple calendar instances may be composited, logically acting as a single calendar, e.g.

for caching puorposing. This attribute determines the topmost calendar that returned items should belong to. If the current instance is the topmost calendar, then it should be returned directly.

See also:
calIItemBase::calendar

Definition at line 93 of file calICalendar.idl.

Setting this attribute to true will prevent the calendar to make calendar properties persistent, which is useful if you would like to set properties on unregistered calendar instances.

Definition at line 118 of file calICalendar.idl.

readonly attribute AUTF8String calICalendar::type [inherited]

Type of the calendar 'memory', 'storage', 'caldav', etc.

Definition at line 82 of file calICalendar.idl.

Setting this URI causes the calendar to be (re)loaded.

This is not an unique identifier! It is also not unchangeable. Don't use it to identify a calendar, use the id attribute for that purpose.

Definition at line 100 of file calICalendar.idl.


The documentation for this interface was generated from the following file: