evolution/calendar/idl/evolution-calendar.idl

/* 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_ANY     = 0x07;

	/* Types of alarms */
	enum AlarmType {
		MAIL,
		PROGRAM,
		DISPLAY,
		AUDIO
	};

	/* Used to store a time_t */
	typedef unsigned long Time_t;

	/* Used to store pilot IDs */
	typedef unsigned long PilotID;

	/* 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 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 get_n_objects (in CalObjType type);

		/* 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 a list of objects that occur or recur in the specified time range */
		CalObjUIDSeq get_objects_in_range (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 get_alarms_in_range (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 get_alarms_for_object (in CalObjUID uid,
							   in Time_t start, in Time_t end)
			raises (NotFound, InvalidRange);


	        /* something
		 *
		 */
		CalObjUID get_uid_by_pilot_id (in PilotID pilotid)
			raises (NotFound);


			/*
			 * update_pilot_id:
			 * @uid: Unique identifier for the event we want to update
			 * @pilot_id: new ID assigned by the pilot
			 * @pilot_status: Status to flag the event with
			 */
			void update_pilot_id (in CalObjUID uid, in PilotID pilot_id, in unsigned long pilot_status)
				raises (NotFound);

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