/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: NPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is Sun Microsystems, Inc.
 * Portions created by Sun Microsystems are Copyright (C) 2006 Sun
 * Microsystems, Inc. All Rights Reserved.
 *
 * Original Author: Daniel Boelzle (daniel.boelzle@sun.com)
 *
 * Contributor(s):
 *
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the NPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the NPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "calICalendar.idl"
#include "calIDateTime.idl"
interface calIWcapSession;

/** Adds WCAP specific capabilities.
 */
[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.
     */
    readonly attribute string calId;
    
    /**
     * UserId of primary owner of this calendar instance.
     */
    readonly attribute string ownerId;
    
    /**
     * Whether the currently selected calendar belongs to user.
     */
    readonly attribute boolean isOwnedCalendar;
    
    /**
     * Calendar description.
     */
    readonly attribute string description;
    
    /**
     * Calendar display name.
     */
    readonly attribute string displayName;
    
//     /**
//      * Gets or sets this calendar's (calId) default timezone.
//      */
//     attribute string defaultTimezone;
    
    /**
     * Gets calendar properties.
     * An error is notified to all registered calIObservers, then thrown.
     *
     * @param propName property name (e.g. X-S1CS-CALPROPS-COMMON-NAME)
     * @return array of property values
     */
    void getCalendarProperties(
        in string propName,
        out unsigned long count,
        [array, size_is(count), retval] out string properties );
    
    /* 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?
    */
    
    /**
     * 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 sync feature: separate into own interface? */
    /** xxx todo: to be moved to calIOperationListener?
     */
    const unsigned long SYNC = 5;

    /**
     * Syncs in changes since time <code>dtFrom</code>.
     * The passed <code>listener</code> receives a
     * <code>SYNC</code> with timestamp as detail.
     *
     * @param destCal destination calendar to write changes to (may be null)
     * @param itemFilter ITEM_FILTER flags OR-ed together,
     *                   ITEM_FILTER_CLASS_OCCURRENCES not allowed
     * @param dtFrom start time to sync changes from,
     *               if null all items are synced in
     * @param listener operation listener for SYNC operation
     *                 (may optionally implemented calIObserver to receive
     *                 onAddItem(), onModifyItem() or onDeleteItem() calls)
     */
    void syncChangesTo(
        in calICalendar destCal,
        in unsigned long itemFilter,
        in calIDateTime dtFrom,
        in calIOperationListener listener );
};

