/* Evolution calendar interface
 *
 * Copyright (C) 2000 Eskil Heyn Olsen
 * Copyright (C) 2000 Ximian, 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;
	typedef sequence<CalObj> CalObjSeq;

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

	/* Simple sequence of strings */
	typedef sequence<string> StringSeq;

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

	/* A VTIMEZONE component, represented as an iCalendar string. */
	typedef string CalTimezoneObj;

	/* A unique identifier for a VTIMEZONE component, i.e. its TZID. */
	typedef string CalTimezoneObjUID;

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

	/* Flags for getting UID sequences */
	typedef long CalObjModType;
	const CalObjModType MOD_THIS          = 1 << 0;
	const CalObjModType MOD_THISANDPRIOR  = 1 << 1;
	const CalObjModType MOD_THISANDFUTURE = 1 << 2;
	const CalObjModType MOD_ALL           = 0x07;

	/* Flags for getting URI sequences */
	typedef long CalMode;
	const CalMode MODE_LOCAL   = 1 << 0;
	const CalMode MODE_REMOTE  = 1 << 1;
	const CalMode MODE_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_start;
		Time_t occur_end;
	};

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

	/* Used to represent users and lists of users */
	typedef string User;
	typedef sequence<User> UserList;

	interface Query;

	interface Listener;

	interface QueryListener;

	/* Calendar client interface */
	interface Cal : Bonobo::Unknown {
		exception NotFound {};
		exception InvalidRange {};
		exception InvalidObject {};
		exception CouldNotCreate {};
		exception PermissionDenied {};
		exception Busy {string errorMsg;};
		
		/* A calendar is identified by its URI */
		readonly attribute string uri;

		/* Check write permissions for calendar */
		boolean isReadOnly ();
		
		/* Information on the backend's capabilities */
		string getStaticCapabilities ();

		/* Return the cal address associated with this calendar,
		   if any. */
		string getCalAddress ()
			raises (NotFound);

		string getAlarmEmailAddress ()
			raises (NotFound);

		/* Returns the LDAP attribute to get attendees from */
		string getLdapAttribute ()
			raises (NotFound);

		/* For going online/offline */
		void setMode (in CalMode mode);
		
		/* Gets the number of components of the specified types */
		long countObjects (in CalObjType type);

		/* Get a default object of a given type */
		CalObj getDefaultObject (in CalObjType type);
		
		/* Gets a component based on its URI */
		CalObj getObject (in CalObjUID uid)
			raises (NotFound);

		/* Sets the default timezone to be used for resolving DATE
		   and floating DATE-TIME values. */
		void setDefaultTimezone (in CalTimezoneObjUID tzid)
			raises (NotFound);

		/* Gets a VTIMEZONE component based on its TZID */
		CalTimezoneObj getTimezoneObject (in CalTimezoneObjUID tzid)
			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 (NotFound, InvalidRange);

		/* Returns free/busy objects for the given interval */
		CalObjSeq getFreeBusy (in UserList users, in Time_t start, in Time_t end)
			raises (NotFound, 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);


		/* Discards an alarm from a given component */
		void discardAlarm (in CalObjUID uid, in CalAlarmUID auid)
			raises (NotFound);

		/* Adds or updates one or more VEVENT/VTODO/VTIMEZONE
		 * components. The calobj should be a string representation of
		 * a complete VCALENDAR object (we also support single
		 * VEVENT/VTODO strings, but that is deprecated).
		 *
		 * The VTIMEZONE data will be merged into the calendar,
		 * possibly by renaming TZIDs (though not for builtin
		 * VTIMEZONEs, which have unique TZIDs), so don't rely on the
		 * TZIDs being the same in the new object on the server.
		 *
		 * The client should probably immediately free its copy of the
		 * object after this call, and call getObject to get the
		 * updated version.
		 */
		void updateObjects (in CalObj calobj, in CalObjModType mod)
			raises (NotFound, InvalidObject, PermissionDenied);

		/* Removes a component */
		void removeObject (in CalObjUID uid, in CalObjModType mod)
			raises (NotFound, PermissionDenied);

		/* Sends a component */
		CalObj sendObject (in CalObj calobj, out UserList users)
			raises (InvalidObject, PermissionDenied, Busy);

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

		/* Return status when setting calendar mode */
		enum SetModeStatus {
			MODE_SET,                    /* All OK */
			MODE_NOT_SET,                /* Generic error */
			MODE_NOT_SUPPORTED           /* Mode not supported */
		};

		/* 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 the mode is changed */
		void notifyCalSetMode (in SetModeStatus status, in CalMode mode);
		
		/* 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);

		/* Called from a Calendar when the list of categories changes */
		void notifyCategoriesChanged (in StringSeq categories);

		/* Called from a Calendar when there is an error not notified otherwise */
		void notifyErrorOccurred (in string message);
	};

	/* 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 components are 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 CalObjUIDSeq uids, 
				       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 {};
		exception InvalidURI {};
		exception UnsupportedMethod {};
		exception PermissionDenied {};

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

		/* List of open URI's */
		StringSeq uriList (in CalMode mode);
	};

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

		/* Adds a calendar to the alarm notification system so that
		 * alarms will be triggered for it.  The calendar will be loaded
		 * automatically whenever the alarm daemon starts up.  
		 */
		void addCalendar (in string uri)
			raises (InvalidURI, BackendContactError);

		/* Removes a calendar from the alarm notification system and
		 * alarms will no longer be triggered for it.  The calendar will
		 * no longer be loaded when the alarm daemon starts up. 
		 */
		void removeCalendar (in string uri)
			raises (InvalidURI, NotFound);
	};

	/* Factory to centralize calendar component editor dialogs */
	interface CompEditorFactory : Bonobo::Unknown {
		exception InvalidURI {};
		exception BackendContactError {};
		exception UnsupportedType {};

		typedef long CompEditorMode;
		const CompEditorMode EDITOR_MODE_EVENT        = 1 << 0;
		const CompEditorMode EDITOR_MODE_ALLDAY_EVENT = 1 << 1;
		const CompEditorMode EDITOR_MODE_MEETING      = 1 << 2;
		const CompEditorMode EDITOR_MODE_TODO         = 1 << 3;

		/* Loads a calendar and opens an editor for the specified object */
		void editExisting (in string uri, in CalObjUID uid)
			raises (InvalidURI, BackendContactError);

		/* Loads a calendar and creates a new component of the specified type */
		void editNew (in string uri, in CompEditorMode mode)
			raises (InvalidURI, BackendContactError, UnsupportedType);
	};
};

};
};

#endif
