/usr/share/idl/thunderbird/calIWcapCalendar.idl

/* 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 "calICalendar.idl"
interface calIDateTime;
interface calIWcapSession;

/** Adds WCAP specific capabilities to calICalendar.
 */
[scriptable, uuid(21A189DF-6C92-41f6-9E2B-1929EF25CAEE)]
interface calIWcapCalendar : calICalendar
{
    /**
     * User session this calendar instance belongs to.
     */
    readonly attribute calIWcapSession session;

    /**
     * Current calId the calendar instance acts on; defaults to userId.
     * @exception NS_ERROR_NOT_AVAILABLE if not logged in
     */
    readonly attribute string calId;

    /**
     * UserId of primary owner of this calendar instance.
     * @exception NS_ERROR_NOT_AVAILABLE if not logged in
     */
    readonly attribute string ownerId;

    /**
     * Determines whether this calendar instance is the user's default calendar.
     * @exception NS_ERROR_NOT_AVAILABLE if not logged in
     */
    readonly attribute boolean isDefaultCalendar;

    /**
     * Whether the currently selected calendar belongs to user.
     * @exception NS_ERROR_NOT_AVAILABLE if not logged in
     */
    readonly attribute boolean isOwnedCalendar;

    /**
     * Calendar description.
     * @exception NS_ERROR_NOT_AVAILABLE if not logged in
     */
    readonly attribute string description;

    /**
     * Calendar display name.
     * @exception NS_ERROR_NOT_AVAILABLE if not logged in
     */
    readonly attribute string displayName;

    /**
     * Gets this calendar's (calId) default timezone.
     * @exception NS_ERROR_NOT_AVAILABLE if not logged in
     */
    readonly attribute string defaultTimezone;

    /**
     * Gets calendar properties.
     *
     * @param propName property name (e.g. X-S1CS-CALPROPS-COMMON-NAME)
     * @param count length of props array
     * @param listener called with array of strings as result
     * @exception NS_ERROR_NOT_AVAILABLE if not logged in
     */
    void getCalendarProperties(in string propName,
                               out unsigned long count,
                               [array, size_is(count), retval] out string props);

    /* xxx todo: additional filters sensible for calICalendar, too?
                 claiming bits 24-30 for now.
                 
                 Those bits are somehow handled special now:
                 If at least one of the below is set, then
                 that filter bit(s) are active.
                 If none of the below is set, then those compstate
                 filters are not taken into account at all.
                 So there is no need to OR all of the below together
                 (ITEM_FILTER_ALL_ITEMS does not cover these bits) if you
                 don't care about the REQUEST/REPLY states.

       xxx todo: ITEM_FILTER_CLASS_OCCURRENCES is not filter, rename?
    */

    /* xxx todo: limit to currently needed ones: NEEDS-ACTION */

//     /**
//      * Scope: getItems only
//      * Whether getItems should only return items that have alarms set for the
//      * specified range.
//      */
//     const unsigned long ITEM_FILTER_BY_ALARM_RANGE = 1 << 23;

//     /**
//      * Scope: Attendee
//      * The event or todo is an invitation from another
//      * user and the current user has declined the invitation.
//      */
//     const unsigned long ITEM_FILTER_REPLY_DECLINED = 1 << 24;

//     /**
//      * Scope: Attendee
//      * The event or todo is an invitation from another
//      * user and the current user has accepted the invitation.
//      */
//     const unsigned long ITEM_FILTER_REPLY_ACCEPTED = 1 << 25;

//     /**
//      * Scope: Organizer
//      * The event or todo is an invitation from the current
//      * user to other invitees, and all invitees have replied.
//      */
//     const unsigned long ITEM_FILTER_REQUEST_COMPLETED = 1 << 26;

//     /**
//      * Scope: Attendee
//      * The event or todo is an invitation from another
//      * user and the current user has not replied to it yet.
//      */
//     const unsigned long ITEM_FILTER_REQUEST_NEEDS_ACTION = 1 << 27;

//     /**
//      * Scope: Attendee
//      * The event or todo is an invitation from another
//      * user and the current user is not required to reply.
//      */
//     const unsigned long ITEM_FILTER_REQUEST_NEEDSNOACTION  = 1 << 28;

//     /**
//      * 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.
//      */
//     const unsigned long ITEM_FILTER_REQUEST_PENDING = 1 << 29;

//     /**
//      * Scope: Organizer
//      * The event or todo is an invitation from the current
//      * user to other invitees, and is currently awaiting.
//      */
//     const unsigned long ITEM_FILTER_REQUEST_WAITFORREPLY = 1 << 30;

    /* xxx todo:
       separate out into another interface and leave only an attribute
       
       readonly attribute calIWcapAccessControl accessControl;

       here?
       This would bloat client code somehow like

       if (cal.accessControl &&
           cal.accessControl.check(calIAccessControl.AC_COMP_WRITE))
           cal.deleteItem(item, listener);

       but makes it easier for provider implementors not implementing the
       whole stuff...

       Right now, the below are similar to *nix fs rights, i.e. "write" includes
       "add", "delete" and "modify".
       Does it make sense to separate "add" and "delete" out of "write"?
    */

    /**
     * Whether it is allowed or denied to get availability information
     * (i.e. free-busy times).
     */
    const unsigned long AC_FREEBUSY = 1 << 0;

    /**
     * Whether it is allowed or denied to invite a calendar's
     * owner placing an invitation into the calendar.
     */
    const unsigned long AC_SCHEDULE = 1 << 1;

    /**
     * Whether it is allowed or denied to read components.
     */
    const unsigned long AC_COMP_READ = 1 << 2;

    /**
     * Whether it is allowed or denied to add, modify or delete components.
     */
    const unsigned long AC_COMP_WRITE = 1 << 3;

    /**
     * Whether it is allowed or denied to read properties.
     */
    const unsigned long AC_PROP_READ = 1 << 4;

    /**
     * Whether it is allowed or denied to add, modify or delete properties.
     */
    const unsigned long AC_PROP_WRITE = 1 << 5;

    /**
     * Full access, includes all of the above.
     */
    const unsigned long AC_FULL = (AC_FREEBUSY    |
                                   AC_SCHEDULE    |
                                   AC_COMP_READ   |
                                   AC_COMP_WRITE  |
                                   AC_PROP_READ   |
                                   AC_PROP_WRITE);

    /**
     * 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;
     *
     * @exception NS_ERROR_NOT_AVAILABLE if not logged in
     * @param accessControlBits access control bits (above AC_ definitions)
     * @return true if access is granted, false otherwise
     */
    boolean checkAccess(in unsigned long accessControlBits);

//     /**
//      * Defines granted and denied permissions for a specific user or
//      * user domain. Specific user entries precede over domain entries.
//      *
//      * Examples:
//      * a) Allow all users availability and read access,
//      *    but jdoe only availability access:
//      *    defineAccessControl("@", AC_FREEBUSY | AC_COMP_READ);
//      *    defineAccessControl("jdoe", AC_FREEBUSY);
//      *
//      * b) Restrict jdoe to have no access:
//      *    defineAccessControl("jdoe", 0);
//      *
//      * Follow-up definition calls for the same user will overwrite previous
//      * definitions.
//      * 
//      * @param userId user that is affected by the access control bits
//      *               WCAP specific:
//      *                    - @ stands in for everybody
//      *                    xxx todo: change the above
//      * @param accessControlBits access control bits (above AC_ definitions)
//      * @param listener called when access control bits have been updated
//      * @return optional object to track operation
//      */
//     calIOperation defineAccessControl(
//         in string userId, in unsigned long accessControlBits,
//         in calIGenericOperationListener listener);
    
//     /**
//      * To reset a user's access control definition to the default ones
//      * that everybody is granted.
//      * In case the user has no specific access control definition,
//      * Components.results.NS_ERROR_INVALID_ARG is thrown.
//      *
//      * @param userId user id
//      * @param listener called when access control bits have been updated
//      * @return optional object to track operation
//      */
//     calIOperation resetAccessControl(
//         in string userId,
//         in calIGenericOperationListener listener);
    
//     /**
//      * Gets the set of access control definitions (including "everybody").
//      * Both out arrays have the same length.
//      *
//      * @param count length of returned arrays
//      * @param users users ids
//      * @param accessControlBits access control bits
//      * @param listener called with xxx todo
//      * @return optional object to track operation
//      */
//     calIOperation getAccessControlDefinitions(
//         out unsigned long count,
//         [array, size_is(count)] out string users,
//         [array, size_is(count)] out unsigned long accessControlBits );
};
thunderbird-dev 1:52.7.0+build1-0ubuntu1 / usr / share / idl / thunderbird / calIWcapCalendar.idl
