/* 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 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_OTHER   = 1 << 3;
	const CalObjType TYPE_ANY     = 0x0f;

	/* 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;
		CalObj calobj;
		Time_t start;
		Time_t end;
	};

	typedef sequence<CalObjInstance> CalObjInstanceSeq;

	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 an object based on its URI */
		CalObj get_object (in CalObjUID uid)
			raises (NotFound);

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

		/* Gets the events that occur or recur in the specified time range */
		CalObjInstanceSeq get_events_in_range (in Time_t start, in Time_t end)
			raises (InvalidRange);

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

		/* Removes an object */
		void remove_object (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.
					 */
		};

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

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

		/* Called from a Calendar when an object is removed */
		void obj_removed (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