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

#ifndef _EVOLUTION_CALENDAR_IDL_
#define _EVOLUTION_CALENDAR_IDL_

#include <Bonobo.idl>

module GNOME {
module Evolution {

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

	/* An unique identifier for a calendar object */
	typedef string CalObjUID;

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

	/* 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 object 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;
	};

	typedef sequence<CalObjInstance> CalObjInstanceSeq;

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

	typedef sequence<CalObjChange> CalObjChangeSeq;

	/* An alarm trigger instance */
	struct CalAlarmInstance {
		CalObjUID uid;
		AlarmType type;
		Time_t trigger;
		Time_t occur;
	};

	typedef sequence<CalAlarmInstance> CalAlarmInstanceSeq;

	interface Listener;

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

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

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

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

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

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

		/* Gets a list of objects 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 the objects whose alarms trigger in the specified time
		 * range.
		 */
		CalAlarmInstanceSeq getAlarmsInRange (in Time_t start, in Time_t end)
			raises (InvalidRange);

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


		/*
		 * Updates an object 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 an object */
		void removeObject (in CalObjUID uid)
			raises (NotFound);
	};

	/* Listener for changes in a calendar */
	interface Listener : Bonobo::Unknown {
		/* Return status when loading a calendar; we need better error reporting */
		enum LoadStatus {
			SUCCESS,		/* All OK */
			ERROR,			/* Generic error */
			IN_USE,			/* Requested create while a calendar
						 * with the same URI was in use.
						 */
			METHOD_NOT_SUPPORTED	/* A method handler is not registered */
		};

		/* Called from a CalFactory when a calendar is initially loaded
		 * or created.  The listener must remember the cal object.
		 */
		void notifyCalLoaded (in LoadStatus status, in Cal cal);

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

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

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

		/* Load a calendar from an URI */
		void load (in string uri, in Listener listener)
			raises (NilListener);

		/* Create a new calendar at the specified URI */
		void create (in string uri, in Listener listener)
			raises (NilListener);
	};
};

};
};

#endif