* mu-store-xapian: add _foreach func, document all public functions

src/mu-store-xapian.cc

@@ -333,3 +333,44 @@ mu_store_xapian_set_timestamp (MuStoreXapian *store, const char* msgpath,
 		g_warning ("%s: caught exception", __FUNCTION__);		
 	}
 }
+
+
+MuResult
+mu_store_xapian_foreach (MuStoreXapian *self, 
+			 MuStoreXapianForeachFunc func, void *user_data)  
+{
+	g_return_val_if_fail (self, MU_ERROR);
+	g_return_val_if_fail (func, MU_ERROR);
+	
+	try {
+		Xapian::Enquire enq (*self->_db);		
+		
+		enq.set_query  (Xapian::Query::MatchAll);
+		enq.set_cutoff (0,0);
+		
+		Xapian::MSet matches
+			(enq.get_mset (0, self->_db->get_doccount()));
+		if (matches.empty())
+			return MU_OK; /* database is empty */
+		
+		for (Xapian::MSet::iterator iter = matches.begin();
+		     iter != matches.end(); ++iter) {
+			Xapian::Document doc (iter.get_document());
+			const std::string path(
+				doc.get_value(MU_MSG_FIELD_ID_PATH));
+
+			MuResult res = func (path.c_str(), user_data);
+			if (res != MU_OK)
+				return res;
+		}
+		
+	} catch (const Xapian::Error &err) {
+		g_warning ("%s: caught xapian exception '%s' (%s)", 
+			   __FUNCTION__, err.get_msg().c_str(),
+			   err.get_error_string());
+	} catch (...) {
+		g_warning ("%s: caught exception", __FUNCTION__);
+	}
+
+	return MU_OK;
+}

src/mu-store-xapian.h

@@ -31,19 +31,72 @@ G_BEGIN_DECLS
 struct _MuStoreXapian;
 typedef struct _MuStoreXapian MuStoreXapian;
 
+
+/** 
+ * create a new Xapian store, a place to store documents
+ * 
+ * @param path the path to the database
+ * 
+ * @return a new MuStoreXapian object, or NULL in case of error
+ */
 MuStoreXapian*    mu_store_xapian_new     (const char* path);
 
+/** 
+ * destroy the MuStoreXapian object and free resources
+ * 
+ * @param store a valid store, or NULL
+ */
 void              mu_store_xapian_destroy (MuStoreXapian *store);
+
+
+/** 
+ * store an email message in the XapianStore
+ * 
+ * @param store a valid store
+ * @param msg a valid message
+ * 
+ * @return TRUE if it succeeded, FALSE otherwise
+ */
 MuResult	  mu_store_xapian_store   (MuStoreXapian *store,
 					   MuMsgGMime *msg);
-MuResult          mu_store_xapian_cleanup (MuStoreXapian *store, 
-					   const char* msgpath);
 
+/** 
+ * store a timestamp for a directory
+ * 
+ * @param store a valid store
+ * @param msgpath path to a maildir
+ * @param stamp a timestamp
+ */
 void              mu_store_xapian_set_timestamp (MuStoreXapian *store,
-						   const char* msgpath, 
-						   time_t stamp);
+						 const char* msgpath, 
+						 time_t stamp);
+
+/** 
+ * get the timestamp for a directory
+ * 
+ * @param store a valid store
+ * @param msgpath path to a maildir
+ * 
+ * @return the timestamp, or 0 in case of error
+ */
 time_t            mu_store_xapian_get_timestamp (MuStoreXapian *store,
-						   const char* msgpath);
+						 const char* msgpath);
+
+/** 
+ * call a function for each document in the database
+ * 
+ * @param self a valid store
+ * @param func a callback function to to call for each document
+ * @param user_data a user pointer passed to the callback function
+ * 
+ * @return MU_OK if all went well, MU_STOP if the foreach was interrupted,
+ * MU_ERROR in case of error
+ */
+typedef MuResult (*MuStoreXapianForeachFunc) (const char* path,
+					      void *user_data);
+MuResult         mu_store_xapian_foreach (MuStoreXapian *self,
+					  MuStoreXapianForeachFunc func,
+					  void *user_data);
 
 G_END_DECLS