/* Evolution calendar interface
 *
 * Copyright (C) 2000 Eskil Heyn Olsen
 * Copyright (C) 2000 Helix Code, Inc.
 * Copyright (C) 2000 Ximian, Inc.
 *
 * Authors: Eskil Heyn Olsen <deity@eskil.dk>
 *          Federico Mena-Quintero <federico@ximian.com>
 */

#ifndef _EVOLUTION_CALENDAR_IDL_
#define _EVOLUTION_CALENDAR_IDL_

#include <Bonobo.idl>

module GNOME {
module Evolution {

module Calendar {
	/* A calendar component (event/todo/journal/etc), represented as an
	 * iCalendar string.
	 */
	typedef string CalObj;

	/* A unique identifier for a calendar component */
	typedef string CalObjUID;

	/* Sequence of unique identifiers */
	typedef sequence<CalObjUID> CalObjUIDSeq;

	/* A unique identifier for an alarm subcomponent */
	typedef string CalAlarmUID;

	/* Flags for getting UID sequences */
	typedef long CalObjType;
	const CalObjType TYPE_EVENT   = 1 << 0;
	const CalObjType TYPE_TODO    = 1 << 1;
	const CalObjType TYPE_JOURNAL = 1 << 2;
	const CalObjType TYPE_ANY     = 0x07;

	/* Types of object changes made */
	typedef long CalObjChangeType;
	const CalObjChangeType ADDED = 1 << 0;
	const CalObjChangeType MODIFIED = 1 << 1;
	const CalObjChangeType DELETED = 1 << 2;
	
	/* Types of alarms */
	enum AlarmType {
		MAIL,
		PROGRAM,
		DISPLAY,
		AUDIO
	};

	/* Used to store a time_t */
	typedef unsigned long Time_t;

	/* An instance of a calendar component that actually occurs.  These are
	 * "virtual" objects in that they are used to represent instances of
	 * recurring events and alarms.  "Real" objects just contain the
	 * information required to figure out the times at which they recur or
	 * trigger.  
	 */
	struct CalObjInstance {
		CalObjUID uid;
		Time_t start;
		Time_t end;
	};

	/* Used to transfer a list of component occurrences */
	typedef sequence<CalObjInstance> CalObjInstanceSeq;

	/* An object change */
	struct CalObjChange {
		CalObj calobj;
		CalObjChangeType type;
	};

	/* Used to transfer a list of changed components */
	typedef sequence<CalObjChange> CalObjChangeSeq;

	/* An alarm trigger instance */
	struct CalAlarmInstance {
		CalAlarmUID auid;
		Time_t trigger;
		Time_t occur;
	};

	/* Used to represent a list of alarm triggers for a single component */
	typedef sequence<CalAlarmInstance> CalAlarmInstanceSeq;

	/* Alarms for a component */
	struct CalComponentAlarms {
		CalObj calobj;
		CalAlarmInstanceSeq alarms;
	};

	/* Used to represent a list of components plus their triggers */
	typedef sequence<CalComponentAlarms> CalComponentAlarmsSeq;

	interface Query;

	interface Listener;

	interface QueryListener;

	/* Calendar client interface */
	interface Cal : Bonobo::Unknown {
		exception NotFound {};
		exception InvalidRange {};
		exception InvalidObject {};
		exception CouldNotCreate {};

		/* A calendar is identified by its URI */
		readonly attribute string uri;

		/* Gets the number of components of the specified types */
		long countObjects (in CalObjType type);

		/* Gets a component based on its URI */
		CalObj getObject (in CalObjUID uid)
			raises (NotFound);

		/* Gets a list of UIDs based on component type */
		CalObjUIDSeq getUIDs (in CalObjType type);

		/* Gets a list of components that changed based on object type */
		CalObjChangeSeq getChanges (in CalObjType type, in string change_id);

		/* Gets a list of components that occur or recur in the specified time range */
		CalObjUIDSeq getObjectsInRange (in CalObjType type, 
						in Time_t start, in Time_t end)
			raises (InvalidRange);

		/* Gets a list of the components that have alarms that trigger
		 * in the specified range of time, and the trigger/occurrence
		 * structures themselves.  
		 */
		CalComponentAlarmsSeq getAlarmsInRange (in Time_t start, in Time_t end)
			raises (InvalidRange);

		/* Gets the alarms for the specified component that trigger in
		 * the specified time range.  
		 */
		CalComponentAlarms getAlarmsForObject (in CalObjUID uid,
						       in Time_t start, in Time_t end)
			raises (NotFound, InvalidRange);


		/* Updates a component by adding it if it does not exist or by
		 * changing an existing one.  
		 */
		void updateObject (in CalObjUID uid, in CalObj calobj)
			raises (InvalidObject);

		/* Removes a component */
		void removeObject (in CalObjUID uid)
			raises (NotFound);

		/* Initiates a live query of the calendar.  Returns a handle
		 * to the live query itself; changes to components that are
		 * present in the query are notified to the listener.
		 */
		Query getQuery (in string sexp, in QueryListener ql)
			raises (CouldNotCreate);
	};

	/* Listener for changes in a calendar */
	interface Listener : Bonobo::Unknown {
		/* Return status when opening a calendar */
		enum OpenStatus {
			SUCCESS,		/* All OK */
			ERROR,			/* Generic error */
			NOT_FOUND,		/* Requested opening in only_if_exists mode
						 * when the URI did not exist.
						 */
			METHOD_NOT_SUPPORTED	/* A method handler is not registered */
		};

		/* Called from a CalFactory when a calendar is initially opened.
		 * The listener must remember the cal object.  
		 */
		void notifyCalOpened (in OpenStatus status, in Cal cal);

		/* Called from a Calendar when a component is added or changed */
		void notifyObjUpdated (in CalObjUID uid);

		/* Called from a Calendar when a component is removed */
		void notifyObjRemoved (in CalObjUID uid);
	};

	/* Handle to a live query on a calendar */
	interface Query : Bonobo::Unknown {
	};

	/* Listener for changes in a query of a calendar */
	interface QueryListener : Bonobo::Unknown {
		/* Called when a component is added or changed.  If
		 * query_in_progress is true, then the initial query results are
		 * being populated and the other arguments indicate the
		 * percentage of completion Otherwise, the percent value is
		 * unspecified.  */
		void notifyObjUpdated (in CalObjUID uid, 
				       in boolean query_in_progress, 
				       in long n_scanned,
				       in long total);

		/* Called when a component is removed */
		void notifyObjRemoved (in CalObjUID uid);

		/* Reported when a query ends */
		enum QueryDoneStatus {
			SUCCESS,
			PARSE_ERROR
		};

		/* Called when the query finishes populating itself some time
		 * after it is created.  Before this is called,
		 * notifyObjUpdated() may have been called several times to
		 * indicate which objects are actually in the query, unless the
		 * status result is a parse error.  
		 */
		void notifyQueryDone (in QueryDoneStatus status, in string error_str);

		/* Called when an evaluation error occurs while performing a query */
		void notifyEvalError (in string error_str);
	};

	/* A calendar factory, can load and create calendars */
	interface CalFactory : Bonobo::Unknown {
		exception NilListener {};

		/* Open a calendar from an URI */
		void open (in string uri, in boolean only_if_exists, in Listener listener)
			raises (NilListener);
	};

	/* Interface to the alarm notification service */
	interface AlarmNotify : Bonobo::Unknown {
		exception InvalidURI {};
		exception BackendContactError {};
		exception NotFound {};

		/* Adds a calendar to the alarm notification system */
		void addCalendar (in string uri)
			raises (InvalidURI, BackendContactError);

		/* Removes a calendar from the alarm notification system */
		void removeCalendar (in string uri)
			raises (InvalidURI, NotFound);

		/* Makes the alarm notification daemon unconditionally exit */
		void die ();
	};
};

};
};

#endif