/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 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 OEone Calendar Code, released October 31st, 2001.
 *
 * The Initial Developer of the Original Code is
 * OEone Corporation.
 * Portions created by the Initial Developer are Copyright (C) 2001
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s): Mostafa Hosseini <mostafah@oeone.com>
 *                 Chris Charabaruk <ccharabaruk@meldstar.com>
 *                 ArentJan Banck <ajbanck@planet.nl>
 *                 Dan Mosedale <dan.mosedale@oracle.com>
 *
 * 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 MPL, 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 MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"

// decls for stuff from other files
interface nsIURI;
interface calIItemBase;
interface nsIVariant;

// forward decls for this file
interface calIObserver;
interface calIOperationListener;
interface calIRange;
interface calIDateTime;

[scriptable, uuid(4c352774-2c4f-11d9-9c63-00045ace3b8d)]
interface calICalendar : nsISupports
{
  /** 
   * 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.).
   */
  const unsigned long ITEM_FILTER_COMPLETED_YES = 1 << 0; 
  const unsigned long ITEM_FILTER_COMPLETED_NO = 1 << 1; 
  const unsigned long ITEM_FILTER_COMPLETED_ALL = 
    (ITEM_FILTER_COMPLETED_YES | ITEM_FILTER_COMPLETED_NO);

  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 = 
    (ITEM_FILTER_TYPE_TODO | ITEM_FILTER_TYPE_EVENT |
     ITEM_FILTER_TYPE_JOURNAL);

  void addObserver( in calIObserver observer, in unsigned long aItemFilter );
  void removeObserver( in calIObserver observer );

  /**
   * The following five "Item" functions are all asynchronous, and get 
   * their results called back through an calIOperationListener object.
   *
   * @param aItem	The item to add or modify
   * @param aListener 	Where to call back the results
   * @param aId		UUID of the event in question
   */
  void addItem( in calIItemBase aItem, in calIOperationListener aListener );
  void modifyItem( in calIItemBase aItem, in calIOperationListener aListener );
  void deleteItem( in string aId, in calIOperationListener aListener );
  void getItem( in string aId, in calIOperationListener aListener );

  /**
   * XXX As mentioned above, this method isn't suitably general.  We need to
   * do better than this.
   * 
   * XXX what do we guarantee about item ordering, especially regarding
   * which items are returned when aCount != 0
   *
   * @param aItemType	The interface that we want returned.  This could be 
   * 			either something that inherits from calIItemBase,
   * 			or it could be calIOccurence.
   *
   * @param aRangeStart Items starting at this time or after should be 
   *                    returned.  If invalid, assume "since the beginning
   *                    of time".
   * @param aRangeEnd   Items starting at this time or before should be
   *			returned.  If invalid, assume "until the end of time".
   * @param aCount	Maximum number of items to return.  
   */
  void getItems( in nsIIDRef aItemType, in unsigned long aItemFilter, 
                 in unsigned long aCount, in calIDateTime aRangeStart,
                 in calIDateTime aRangeEnd, 
		 in calIOperationListener aListener );

  /** 
   * Remaining stuff is holdovers from oeIICal.idl; doxygen comments required
   * (assuming we keep all these).
   */

  void reportError( in unsigned long errorid, in AUTF8String aMessage );

  attribute boolean batchMode; // XXX use start/end methods instead of attr?
  attribute nsIURI uri; // XXX is this heavier weight than we need?
  attribute boolean suppressAlarms;
};

/** 
 * Used to allow multiple calendars (eg work and home) to be easily queried
 * and displayed as a single unit.
 */
[scriptable, uuid(1f6dba37-8ce4-4c51-bc10-6892d3e6f5ed)]
interface calICompositeCalendar : calICalendar
{
  void addCalendar( in string server, in string type );
  void removeCalendar( in string server );
  calICalendar getCalendar( in string server );
};

/**
 * Make a more general nsIObserverService2 and friends to support
 * nsISupports data and use that instead?
 */
[scriptable, uuid(2953c9b2-2c73-11d9-80b6-00045ace3b8d)]
interface calIObserver : nsISupports
{
  void onStartBatch();
  void onEndBatch();
  void onLoad();
  void onAddItem( in calIItemBase aItem );
  void onModifyItem( in calIItemBase aNewItem, in calIItemBase aOldItem );
  void onDeleteItem( in calIItemBase aDeletedItem );
  void onAlarm( in calIItemBase aAlarmItem );
  void onError( in nsresult aErrNo, in AUTF8String aMessage );
};


/**
 * Async operations are called back via this interface.  If you know that your
 * object is not going to get called back for either of these methods, having
 * them return NS_ERROR_NOT_IMPLEMENTED is reasonable.
 */
[scriptable, uuid(ed3d87d8-2c77-11d9-8f5f-00045ace3b8d)]
interface calIOperationListener : nsISupports
{
  /**
   * For add, modify, and delete.
   *
   * @param aOperationType 	type of operation that was completed
   * @param aId			UUID of element that was changed
   * @param aStatus		status code summarizing what happened
   * @param aDetail		Not yet fully specified.  If aStatus is an
   * 				error result, this will probably be any 
   *                            extended error string (eg one returned by
   * 				a server).
   */
  void onOperationComplete(in unsigned long aOperationType,
			   in string aId,
			   in nsresult aStatus,
			   in nsIVariant aDetail);
  const unsigned long ADD = 1;
  const unsigned long MOVE = 2;
  const unsigned long DELETE = 3;

  /**
   * For getItem and getItems.
   * 
   * @param aStatus	status code summarizing what happened.
   * @param aItemType	type of interface returned in the array (@see
   *			calICalendar::GetItems).
   * @param aDetail	Not yet fully specified.  If aStatus is an
   * 			error result, this will probably be any 
   *                    extended error string (eg one returned by
   * 			a server).
   * @param aCount      size of array returned, in items
   * @param aItems	array of item interfaces
   *			
   */
  void onGetComplete(in nsresult aStatus, in nsIIDRef aItemType, 
		     in nsIVariant aDetail, in PRUint32 aCount, 
		     [array, size_is(aCount), iid_is(aItemType)] 
		     in nsQIResult aItems ); 
};
