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

	typedef sequence<string> stringlist;

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

	/* A unique identified for an event recurrence */
	typedef string CalRecurID;

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

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

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

	enum CallStatus {
		Success,
		RepositoryOffline,
		PermissionDenied,
		InvalidRange,
		ObjectNotFound,
		InvalidObject,
		CardIdAlreadyExists,
		AuthenticationFailed,
		AuthenticationRequired,
		UnsupportedField,
		UnsupportedMethod,
		UnsupportedAuthenticationMethod,
		TLSNotAvailable,
		NoSuchCal,

		/* These can be returned for successful searches, but
		   indicate the result set was truncated */
		SearchSizeLimitExceeded,
		SearchTimeLimitExceeded,

		InvalidQuery,
		QueryRefused,

		CouldNotCancel,
		
		OtherError
	};

	interface Query;

	interface Listener;

	interface QueryListener;

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

		oneway void open (in boolean only_if_exists);
		oneway void remove ();

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

		/* Return the cal address associated with this calendar, if any. */
		oneway void getCalAddress ();		

		oneway void getAlarmEmailAddress ();

		/* Returns the LDAP attribute to get attendees from */
		oneway void getLdapAttribute ();

		/* For going online/offline */
		void setMode (in CalMode mode);

		/* Get a default object of the backend's type */
		oneway void getDefaultObject ();
		
		/* Gets a component based on its URI */
		oneway void getObject (in CalObjUID uid, in CalRecurID rid);

		oneway void getObjectList (in string query);		

		/* Methods for manipulating timezones */
		oneway void getTimezone (in CalTimezoneObjUID tzid);
		oneway void addTimezone (in CalTimezoneObj tz);
		/* The timezone used to resolve DATE and floating DATE-TIME values. */
		oneway void setDefaultTimezone (in CalTimezoneObjUID tzid);

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

		/* Returns free/busy objects for the given interval */
		oneway void getFreeBusy (in UserList users, in Time_t start, in Time_t end);

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

		/* Methods for manipulating iCalendar objects */
		oneway void createObject (in CalObj calobj);
		oneway void modifyObject (in CalObj calobj, in CalObjModType mod);
		oneway void removeObject (in CalObjUID uid, in CalRecurID rid, in CalObjModType mod);

		/* Methods for getting/sending iCalendar VCALENDARS via iTip/iMip */
		oneway void receiveObjects (in CalObj calobj);
		oneway void sendObjects (in CalObj calobj);

		/* Query methods */
		oneway void getQuery (in string sexp, in QueryListener ql);
	};

	/* Listener for changes in a calendar */
	interface Listener : Bonobo::Unknown {
		/* Return status when setting calendar mode */
		enum SetModeStatus {
			MODE_SET,                    /* All OK */
			MODE_NOT_SET,                /* Generic error */
			MODE_NOT_SUPPORTED           /* Mode not supported */
		};

		oneway void notifyReadOnly (in CallStatus status, in boolean read_only);
		oneway void notifyCalAddress (in CallStatus status, in string address);
		oneway void notifyAlarmEmailAddress (in CallStatus status, in string address);
		oneway void notifyLDAPAttribute (in CallStatus status, in string ldap_attribute);
		oneway void notifyStaticCapabilities (in CallStatus status, in string capabilities);
		
		oneway void notifyCalOpened (in CallStatus status);
		oneway void notifyCalRemoved (in CallStatus status);

		oneway void notifyObjectCreated (in CallStatus status, in string uid);
		oneway void notifyObjectModified (in CallStatus status);
		oneway void notifyObjectRemoved (in CallStatus status);

		oneway void notifyAlarmDiscarded (in CallStatus status);
	
		oneway void notifyObjectsReceived (in CallStatus status);
		oneway void notifyObjectsSent (in CallStatus status);
		
		oneway void notifyDefaultObjectRequested (in CallStatus status, in CalObj object);
		oneway void notifyObjectRequested (in CallStatus status, in CalObj object);
		oneway void notifyObjectListRequested (in CallStatus status, in stringlist objects);
		oneway void notifyQuery (in CallStatus status, in Query query);

		oneway void notifyTimezoneRequested (in CallStatus status, in CalTimezoneObj tz);
		oneway void notifyTimezoneAdded (in CallStatus status, in CalTimezoneObjUID tzid);
		oneway void notifyDefaultTimezoneSet (in CallStatus status);

		oneway void notifyChanges (in CallStatus status, in CalObjChangeSeq changes);
		oneway void notifyFreeBusy (in CallStatus status, in CalObjSeq freebusy);

                /* Called from a Calendar when the mode is changed */
		oneway void notifyCalSetMode (in SetModeStatus status, in CalMode mode);		

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

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

	/* Handle to a live query on a calendar */
	interface Query : Bonobo::Unknown {
		oneway void start ();
	};

	/* Listener for changes in a query of a calendar */
	interface QueryListener : Bonobo::Unknown {
		oneway void notifyObjectsAdded (in stringlist objects);		
		oneway void notifyObjectsModified (in stringlist objects);		
		oneway void notifyObjectsRemoved (in CalObjUIDSeq uids);
		oneway void notifyQueryProgress (in string message, in short percent);
		oneway void notifyQueryDone (in CallStatus status);
	};

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

		Cal getCal (in string uri, in CalObjType type, in Listener listener)
			raises (NilListener, InvalidURI, UnsupportedMethod);
	};

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