Engine for live queries to calendars. A query object watches a CalBackend

2001-03-29  Federico Mena Quintero  <federico@ximian.com>

	Engine for live queries to calendars.  A query object watches a
	CalBackend in the PCS and is otherwise completely separate from
	it; backends need to do nothing to support live queries.  Right
	now we have the following functions:

		(get-vtype)

			Returns a string indicating the type of component
			(VEVENT, VTODO, VJOURNAL, VFREEBUSY, VTIMEZONE,
			UNKNOWN).

		(occur-in-time-range? START END)

			START - int, time_t start of the time range
			END - int, time_t end of the time range

			Returns a boolean indicating whether the component
			has any occurrences in the specified time range.

	* idl/evolution-calendar.idl (Cal::getQuery): New method that
	initiates a live query.
	(Query): New interface for a handle to a live query.
	(QueryListener): New interface for a listener to changes in a live
	query.

	* pcs/query.[ch]: New files with the live query engine.

	* pcs/cal-backend.h (CalBackendClass): Added notification signals
	so that the query system can catch them.
	(CalBackendClass): New virtual method ::get_load_state().

	* pcs/cal-backend.c (cal_backend_opened):
	(cal_backend_obj_updated):
	(cal_backend_obj_updated): New functions to emit the notification
	signals; to be used only by backend implementations.
	(cal_backend_get_load_state): New function.

	* pcs/cal-backend-file.c (notify_update): Call
	cal_backend_obj_updated().
	(notify_remove): Call call_backend_obj_removed().
	(open_cal): Free the icalcomp if it is not of the correct type.
	(cal_backend_file_get_load_state): Implemented new method.

	* pcs/cal-backend-db.c (cal_backend_db_update_object): Call
	cal_backend_obj_updated().
	(cal_backend_db_remove_object): Call cal_backend_obj_removed().
	(cal_backend_db_get_load_state): Implemented new method.

	* pcs/cal.c (Cal_get_query): Implementation of the ::getQuery()
	method.

svn path=/trunk/; revision=9013

1 files changed, 50 insertions, 1 deletions

diff --git a/calendar/idl/evolution-calendar.idl b/calendar/idl/evolution-calendar.idl
index f8f727c196..e21f77fe2e 100644
--- a/calendar/idl/evolution-calendar.idl
+++ b/calendar/idl/evolution-calendar.idl
@@ -98,13 +98,18 @@ module Calendar {
 	/* Used to represent a list of components plus their triggers */
 	typedef sequence<CalComponentAlarms> CalComponentAlarmsSeq;
 
+	interface Query;
+
 	interface Listener;
 
+	interface QueryListener;
+
 	/* Calendar client interface */
 	interface Cal : Bonobo::Unknown {
 		exception NotFound {};
 		exception InvalidRange {};
 		exception InvalidObject {};
+		exception CouldNotCreate {};
 
 		/* A calendar is identified by its URI */
 		readonly attribute string uri;
@@ -117,7 +122,7 @@ module Calendar {
 			raises (NotFound);
 
 		/* Gets a list of UIDs based on component type */
-		CalObjUIDSeq getUIds (in CalObjType 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);
@@ -151,6 +156,13 @@ module Calendar {
 		/* Removes a component */
 		void removeObject (in CalObjUID uid)
 			raises (NotFound);
+
+		/* 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 */
@@ -177,6 +189,43 @@ module Calendar {
 		void notifyObjRemoved (in CalObjUID uid);
 	};
 
+	/* 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 a component is 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 CalObjUID uid, 
+				       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 {};