Back to index

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

Adds WCAP specific capabilities to calICalendar. More...

import "calIWcapCalendar.idl";

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

List of all members.

Public Member Functions

void getCalendarProperties (in string propName, out unsigned long count,[array, size_is(count), retval] out string props)
 Gets calendar properties.
boolean checkAccess (in unsigned long accessControlBits)
 Checks whether the currently logged in user can perform the specified actions.
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 calIWcapSession session
 User session this calendar instance belongs to.
readonly attribute string calId
 Current calId the calendar instance acts on; defaults to userId.
readonly attribute string ownerId
 UserId of primary owner of this calendar instance.
readonly attribute boolean isDefaultCalendar
 Determines whether this calendar instance is the user's default calendar.
readonly attribute boolean isOwnedCalendar
 Whether the currently selected calendar belongs to user.
readonly attribute string description
 Calendar description.
readonly attribute string displayName
 Calendar display name.
readonly attribute string defaultTimezone
 Gets this calendar's (calId) default timezone.
const unsigned long AC_FREEBUSY = 1 << 0
 Scope: getItems only Whether getItems should only return items that have alarms set for the specified range.
const unsigned long AC_SCHEDULE = 1 << 1
 Whether it is allowed or denied to invite a calendar's owner placing an invitation into the calendar.
const unsigned long AC_COMP_READ = 1 << 2
 Whether it is allowed or denied to read components.
const unsigned long AC_COMP_WRITE = 1 << 3
 Whether it is allowed or denied to add, modify or delete components.
const unsigned long AC_PROP_READ = 1 << 4
 Whether it is allowed or denied to read properties.
const unsigned long AC_PROP_WRITE = 1 << 5
 Whether it is allowed or denied to add, modify or delete properties.
const unsigned long AC_FULL
 Full access, includes all of the above.
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 WCAP specific capabilities to calICalendar.

Definition at line 48 of file calIWcapCalendar.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
boolean calIWcapCalendar::checkAccess ( in unsigned long  accessControlBits)

Checks whether the currently logged in user can perform the specified actions.

Clients should check these bits before performing operations on a calendar instance, e.g.

if (cal.checkAccess(calIWcapCalendar.AC_COMP_WRITE)) cal.deleteItem(item, listener);

or

if (cal.checkAccess(calIWcapCalendar.AC_PROP_WRITE)) cal.name = newName;

Exceptions:
NS_ERROR_NOT_AVAILABLEif not logged in
Parameters:
accessControlBitsaccess control bits (above AC_ definitions)
Returns:
true if access is granted, false otherwise

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.

void calIWcapCalendar::getCalendarProperties ( in string  propName,
out unsigned long  count,
[array, size_is(count), retval] out string  props 
)

Gets calendar properties.

Parameters:
propNameproperty name (e.g. X-S1CS-CALPROPS-COMMON-NAME)
countlength of props array
listenercalled with array of strings as result
Exceptions:
NS_ERROR_NOT_AVAILABLEif not logged in
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

Whether it is allowed or denied to read components.

Definition at line 218 of file calIWcapCalendar.idl.

Whether it is allowed or denied to add, modify or delete components.

Definition at line 223 of file calIWcapCalendar.idl.

Scope: getItems only Whether getItems should only return items that have alarms set for the specified range.

Scope: Attendee The event or todo is an invitation from another user and the current user has declined the invitation. Scope: Attendee The event or todo is an invitation from another user and the current user has accepted the invitation. Scope: Organizer The event or todo is an invitation from the current user to other invitees, and all invitees have replied. Scope: Attendee The event or todo is an invitation from another user and the current user has not replied to it yet. Scope: Attendee The event or todo is an invitation from another user and the current user is not required to reply. Scope: Organizer The event or todo is an invitation from the current user to other invitees, and is currently in the process of sending out invitations. Scope: Organizer The event or todo is an invitation from the current user to other invitees, and is currently awaiting. Whether it is allowed or denied to get availability information (i.e. free-busy times).

Definition at line 207 of file calIWcapCalendar.idl.

Initial value:

Full access, includes all of the above.

Definition at line 238 of file calIWcapCalendar.idl.

Whether it is allowed or denied to read properties.

Definition at line 228 of file calIWcapCalendar.idl.

Whether it is allowed or denied to add, modify or delete properties.

Definition at line 233 of file calIWcapCalendar.idl.

Whether it is allowed or denied to invite a calendar's owner placing an invitation into the calendar.

Definition at line 213 of file calIWcapCalendar.idl.

Current calId the calendar instance acts on; defaults to userId.

Exceptions:
NS_ERROR_NOT_AVAILABLEif not logged in

Definition at line 59 of file calIWcapCalendar.idl.

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

Definition at line 111 of file calICalendar.idl.

Gets this calendar's (calId) default timezone.

Exceptions:
NS_ERROR_NOT_AVAILABLEif not logged in

Definition at line 95 of file calIWcapCalendar.idl.

Calendar description.

Exceptions:
NS_ERROR_NOT_AVAILABLEif not logged in

Definition at line 83 of file calIWcapCalendar.idl.

Calendar display name.

Exceptions:
NS_ERROR_NOT_AVAILABLEif not logged in

Definition at line 89 of file calIWcapCalendar.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.

Determines whether this calendar instance is the user's default calendar.

Exceptions:
NS_ERROR_NOT_AVAILABLEif not logged in

Definition at line 71 of file calIWcapCalendar.idl.

Whether the currently selected calendar belongs to user.

Exceptions:
NS_ERROR_NOT_AVAILABLEif not logged in

Definition at line 77 of file calIWcapCalendar.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.

UserId of primary owner of this calendar instance.

Exceptions:
NS_ERROR_NOT_AVAILABLEif not logged in

Definition at line 65 of file calIWcapCalendar.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.

User session this calendar instance belongs to.

Definition at line 53 of file calIWcapCalendar.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: