/* -*- 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 "calIWcapCalendar.idl"
#include "calIWcapFreeBusyListener.idl"

/**
 * WCAP session.
 */
[scriptable, uuid(477B4534-C297-40a1-ADF2-5A7E2A81816A)]
interface calIWcapSession : nsISupports
{
    /**
     * Setting this URI causes the session to be disconnected.
     */
    attribute nsIURI uri;
    
    /**
     * User that has established this session.
     * Reading this attribute prompts for login if the session has not yet
     * been established.
     * An error is notified to all registered calIObservers, then thrown.
     */
    readonly attribute string userId;
    
    /**
     * Determines whether the user is currentl logged in.
     * Does _not_ check whether the user's ticket has timed out!
     */
    readonly attribute boolean isLoggedIn;
    
    /**
     * Explicitly performs a session establishment.
     * Commonly not needed, because any attempt to get a calendar instance
     * will establish a session automatically.
     * If the user is already logged in, she will be logged out before.
     * UI will prompt for a userId and password.
     * An error is notified to all registered calIObservers, then thrown.
     */
    void login();
    
    /**
     * Explicitly performs a session logout.
     * Commonly not needed, because the user will be logged out upon
     * "network:offline-about-to-go-offline" and "quit-application"
     * automatically.
     * An error is notified to all registered calIObservers, then thrown.
     */
    void logout();
    
    /**
     * Gets a text for an error code.
     *
     * @param rc error code defined in calIWcapErrors
     * @return error string
     * @exception NS_ERROR_INVALID_ARG
     */
    string getWcapErrorString( in unsigned long rc );
    
    /**
     * The user's default calendar.
     * An error is notified to all registered calIObservers, then thrown.
     */
    readonly attribute calIWcapCalendar defaultCalendar;
    
    /**
     * Gets a calendar instance for the passed calId using this session.
     * An error is notified to all registered calIObservers, then thrown.
     *
     * @param calId full calId (incl. "<user>:")
     * @return calendar instance
     */
    calIWcapCalendar getCalendarByCalId( in string calId );
    
    /**
     * Gets calendars where the user is the primary owner
     * (including default calendar).
     * An error is notified to all registered calIObservers, then thrown.
     *
     * @return array of owned calendars
     */
    void getOwnedCalendars(
        out unsigned long count,
        [array, size_is(count), retval] out calIWcapCalendar ownedCals );
    
    /**
     * Gets subscribed calendars (may include calendars where the user
     * is the primary owner).
     * An error is notified to all registered calIObservers, then thrown.
     *
     * @return array of subscribed calendars
     */
    void getSubscribedCalendars(
        out unsigned long count,
        [array, size_is(count), retval] out calIWcapCalendar subscribedCals );
    
    /**
     * Creates a new calendar for the session's user.
     * An error is notified to all registered calIObservers, then thrown.
     *
     * @param calId calendar's calId (portion);
     *        without user's id, e.g. "test-cal".
     *        valid characters for the calId parameter are:
     *        - Alphabet characters (A-Z, a-z)
     *        - Numeric characters (0-9)
     *        - Three special characters
     *        - Dash (-)
     *        - Underscore (_)
     *        - Period (.)
     * @param name calendar's name, e.g. "My Work Cal"
     * @param bAllowDoubleBooking whether double booking (events/todos) is
     *                            allowed
     * @param bSetCalProps whether properties of the new calendar are set
     * @param bAddToSubscribed allows a user to specify if the newly
     *                         created calendar should be added to the
     *                         user’s subscribed calendar list
     * @return created calendar
     */
    calIWcapCalendar createCalendar(
        in string calId,
        in string name,
        in boolean bAllowDoubleBooking,
        in boolean bSetCalProps,
        in boolean bAddToSubscribed );
    
    /**
     * Deletes a calendar.
     * An error is notified to all registered calIObservers, then thrown.
     *
     * @param calId full calId (incl. "<user>:")
     * @param bRemoveFromSubscribed whether calendar ought to be removed
     *                              from subscription list
     */
    void deleteCalendar(
        in string calId,
        in boolean bRemoveFromSubscribed );
    
    /**
     * Subscribe to calendar(s).
     * An error is notified to all registered calIObservers, then thrown.
     *
     * @param count number of calIds
     * @param calIds array of calIds (calid or "mailto:rfc822addr")
     */
    void subscribeToCalendars(
        in unsigned long count,
        [array, size_is(count)] in string calIds );
    
    /**
     * Unsubscribe from calendar(s).
     * An error is notified to all registered calIObservers, then thrown.
     *
     * @param count number of calIds
     * @param calIds array of calIds (calid or "mailto:rfc822addr")
     */
    void unsubscribeFromCalendars(
        in unsigned long count,
        [array, size_is(count)] in string calIds );
    
    /**
     * Gets the user's preferences.
     * An error is notified to all registered calIObservers, then thrown.
     *
     * @param prefName preference name
     * @return array of preference values
     */
    void getUserPreferences(
        in string prefName,
        out unsigned long count,
        [array, size_is(count), retval] out string properties );
    
    /* xxx todo freebusy: separate into own interface? */
    /**
     * Gets free-busy entries for calid.
     * Results are notifies to passed listener instance.
     * An error is notified to all registered calIObservers and
     * to calIWcapFreeBusyListener::onGetFreeBusyTimes with rc != NS_OK.
     * Additionally, when an error occurs within getFreeBusyTimes,
     * the error is also thrown.
     *
     * @param calId a calid or "mailto:rfc822addr"
     * @param dtRangeStart start time of free-busy search
     * @param dtRangeEnd end time of free-busy search
     * @param bBusyOnly whether to return busy entries only
     * @param listener listener receiving results
     * @param bAsync whether the listener receives results asynchronously
     * @param requestId request id to distinguish asynchronous requests
     */
    void getFreeBusyTimes(
        in string calId,
        in calIDateTime dtRangeStart,
        in calIDateTime dtRangeEnd,
        in boolean bBusyOnly,
        in calIWcapFreeBusyListener listener,
        in boolean bAsync,
        in unsigned long requestId );
};

