/* 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_DATASERVER_CALENDAR_IDL_
#define _EVOLUTION_DATASERVER_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,
		ObjectIdAlreadyExists,
		AuthenticationFailed,
		AuthenticationRequired,
		UnsupportedField,
		UnsupportedMethod,
		UnsupportedAuthenticationMethod,
		TLSNotAvailable,
		NoSuchCal,
		UnknownUser,
		OfflineUnavailable,

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

		InvalidQuery,
		QueryRefused,

		CouldNotCancel,
		
		OtherError,
		InvalidServerVersion

	};

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

	/* Listener for changes in a query of a calendar */
	interface CalViewListener : 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);
	};

	/* 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, in string username, in string password);
		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 */
		oneway void getChanges (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);

		/* get attachment list for an object */
		oneway void getAttachmentList (in CalObjUID uid, in CalRecurID rid);		
		
		/* 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 CalViewListener ql);
	};

	/* Listener for changes in a calendar */
	interface CalListener : 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, in UserList users, in CalObj calobj);
		
		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 CalView 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);

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

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

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

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

#endif