2010-09-26 14:52:42 +02:00
|
|
|
/*
|
|
|
|
** Copyright (C) 2008-2010 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
|
2009-11-25 21:55:06 +01:00
|
|
|
**
|
|
|
|
** This program is free software; you can redistribute it and/or modify
|
|
|
|
** it under the terms of the GNU General Public License as published by
|
|
|
|
** the Free Software Foundation; either version 3 of the License, or
|
|
|
|
** (at your option) any later version.
|
|
|
|
**
|
|
|
|
** This program is distributed in the hope that it will be useful,
|
|
|
|
** but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
** GNU General Public License for more details.
|
|
|
|
**
|
|
|
|
** You should have received a copy of the GNU General Public License
|
|
|
|
** along with this program; if not, write to the Free Software Foundation,
|
|
|
|
** Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
|
|
**
|
|
|
|
*/
|
|
|
|
|
|
|
|
#ifndef __MU_INDEX_H__
|
|
|
|
#define __MU_INDEX_H__
|
|
|
|
|
2010-01-31 11:13:06 +01:00
|
|
|
#include <stdlib.h>
|
|
|
|
#include <glib.h>
|
|
|
|
|
2009-11-25 21:55:06 +01:00
|
|
|
#include "mu-result.h" /* for MuResult */
|
|
|
|
|
|
|
|
/* opaque structure */
|
|
|
|
struct _MuIndex;
|
|
|
|
typedef struct _MuIndex MuIndex;
|
|
|
|
|
|
|
|
struct _MuIndexStats {
|
2010-09-12 20:19:02 +02:00
|
|
|
unsigned _processed; /* number of msgs processed or counted */
|
|
|
|
unsigned _updated; /* number of msgs new or updated */
|
|
|
|
unsigned _cleaned_up; /* number of msgs cleaned up */
|
|
|
|
unsigned _uptodate; /* number of msgs already uptodate */
|
2009-11-25 21:55:06 +01:00
|
|
|
};
|
|
|
|
typedef struct _MuIndexStats MuIndexStats;
|
|
|
|
|
2010-09-26 14:52:42 +02:00
|
|
|
/**
|
|
|
|
* create a new MuIndex instance. NOTE(1): the database does not have
|
|
|
|
* to exist yet, but the directory must already exist; NOTE(2): before
|
|
|
|
* doing anything with the returned Index object, make sure you haved
|
|
|
|
* called g_type_init, and mu_msg_init somewhere in your code.
|
2009-11-25 21:55:06 +01:00
|
|
|
*
|
2009-12-02 22:16:57 +01:00
|
|
|
* @param xpath path to the 'homedir'; the xapian directory will be
|
|
|
|
* this homedir/xapian
|
2009-11-25 21:55:06 +01:00
|
|
|
*
|
|
|
|
* @return a new MuIndex instance, or NULL in case of error
|
|
|
|
*/
|
2009-12-02 22:16:57 +01:00
|
|
|
MuIndex* mu_index_new (const char* muhome);
|
2009-11-25 21:55:06 +01:00
|
|
|
|
|
|
|
|
2010-09-26 14:52:42 +02:00
|
|
|
/**
|
2009-11-25 21:55:06 +01:00
|
|
|
* destroy the index instance
|
|
|
|
*
|
|
|
|
* @param index a MuIndex instance, or NULL
|
|
|
|
*/
|
|
|
|
void mu_index_destroy (MuIndex *index);
|
|
|
|
|
|
|
|
|
2010-09-26 14:52:42 +02:00
|
|
|
/**
|
2009-11-25 21:55:06 +01:00
|
|
|
* callback function for mu_index_(run|stats|cleanup), for each message
|
|
|
|
*
|
|
|
|
* @param stats pointer to structure to receive statistics data
|
|
|
|
* @param user_data pointer to user data
|
|
|
|
*
|
|
|
|
* @return MU_OK to continue, MU_STOP to stop, or MU_ERROR in
|
|
|
|
* case of some error.
|
|
|
|
*/
|
|
|
|
typedef MuResult (*MuIndexMsgCallback) (MuIndexStats* stats, void *user_data);
|
|
|
|
|
|
|
|
|
2010-09-26 14:52:42 +02:00
|
|
|
/**
|
2009-11-25 21:55:06 +01:00
|
|
|
* callback function for mu_index_(run|stats|cleanup), for each dir enter/leave
|
|
|
|
*
|
|
|
|
* @param path dirpath we just entered / left
|
|
|
|
* @param enter did we enter (TRUE) or leave(FALSE) the dir?
|
|
|
|
* @param user_data pointer to user data
|
|
|
|
*
|
|
|
|
* @return MU_OK to contiue, MU_STOP to stopd or MU_ERROR in
|
|
|
|
* case of some error.
|
|
|
|
*/
|
|
|
|
typedef MuResult (*MuIndexDirCallback) (const char* path, gboolean enter,
|
|
|
|
void *user_data);
|
|
|
|
|
2010-09-26 14:52:42 +02:00
|
|
|
/**
|
2009-11-25 21:55:06 +01:00
|
|
|
* start the indexing process
|
|
|
|
*
|
|
|
|
* @param index a valid MuIndex instance
|
2010-02-04 22:00:34 +01:00
|
|
|
* @param path the path to index. This must be an absolute path
|
2009-11-25 21:55:06 +01:00
|
|
|
* @param force if != 0, force re-indexing already index messages; this is
|
|
|
|
* obviously a lot slower than only indexing new/changed messages
|
2010-01-04 19:19:32 +01:00
|
|
|
* @param stats a structure with some statistics about the results;
|
|
|
|
* note that this function does *not* reset the struct values to allow
|
|
|
|
* for cumulative stats from multiple calls. If needed, you can use
|
|
|
|
* @mu_index_stats_clear before calling this function
|
2009-11-25 21:55:06 +01:00
|
|
|
* @param cb_msg a callback function called for every msg indexed;
|
2010-01-25 08:28:08 +01:00
|
|
|
* @param cb_dir a callback function called for every dir entered/left or NULL
|
2009-11-25 21:55:06 +01:00
|
|
|
* @param user_data a user pointer that will be passed to the callback function
|
|
|
|
*
|
|
|
|
* @return MU_OK if the stats gathering was completed succesfully,
|
|
|
|
* MU_STOP if the user stopped or MU_ERROR in
|
|
|
|
* case of some error.
|
|
|
|
*/
|
|
|
|
MuResult mu_index_run (MuIndex *index, const char* path, gboolean force,
|
2010-01-04 19:19:32 +01:00
|
|
|
MuIndexStats *stats, MuIndexMsgCallback msg_cb,
|
2009-11-25 21:55:06 +01:00
|
|
|
MuIndexDirCallback dir_cb, void *user_data);
|
|
|
|
|
2010-09-26 14:52:42 +02:00
|
|
|
/**
|
2009-11-25 21:55:06 +01:00
|
|
|
* gather some statistics about the Maildir; this is usually much faster
|
|
|
|
* than mu_index_run, and can thus be used to provide some information to the user
|
|
|
|
* note though that the statistics may be different from the reality that
|
|
|
|
* mu_index_run sees, when there are updates in the Maildir
|
|
|
|
*
|
|
|
|
* @param index a valid MuIndex instance
|
2010-02-04 22:00:34 +01:00
|
|
|
* @param path the path to get stats for; this must be an absolute path
|
|
|
|
* @param stats a structure with some statistics about the results;
|
2010-01-04 19:19:32 +01:00
|
|
|
* note that this function does *not* reset the struct values to allow
|
|
|
|
* for cumulative stats from multiple calls. If needed, you can use
|
|
|
|
* @mu_index_stats_clear before calling this function
|
2010-01-25 08:28:08 +01:00
|
|
|
* @param msg_cb a callback function which will be called for every msg;
|
|
|
|
* @param dir_cb a callback function which will be called for every dir or NULL
|
2009-11-25 21:55:06 +01:00
|
|
|
* @param user_data a user pointer that will be passed to the callback function
|
|
|
|
* xb
|
|
|
|
* @return MU_OK if the stats gathering was completed succesfully,
|
|
|
|
* MU_STOP if the user stopped or MU_ERROR in
|
|
|
|
* case of some error.
|
|
|
|
*/
|
2010-01-04 19:19:32 +01:00
|
|
|
MuResult mu_index_stats (MuIndex *index, const char* path, MuIndexStats *stats,
|
2009-11-25 21:55:06 +01:00
|
|
|
MuIndexMsgCallback msg_cb, MuIndexDirCallback dir_cb,
|
|
|
|
void *user_data);
|
|
|
|
|
2010-01-03 12:41:32 +01:00
|
|
|
|
|
|
|
|
2010-09-26 14:52:42 +02:00
|
|
|
/**
|
2010-01-03 12:41:32 +01:00
|
|
|
* callback function to determine if a message should be delete from
|
|
|
|
* the database; if it returs MU_OK it will be delete, if returns
|
|
|
|
* MU_IGNORE, the message will be ignored. In other cases, stop the callback
|
|
|
|
*
|
|
|
|
* @param MuIndexCleanupCallback
|
|
|
|
*
|
|
|
|
* @return
|
|
|
|
*/
|
2010-01-04 19:19:32 +01:00
|
|
|
typedef MuResult (*MuIndexCleanupDeleteCallback) (MuIndexStats *stats,
|
|
|
|
void *user_data);
|
2009-11-25 21:55:06 +01:00
|
|
|
|
2010-09-26 14:52:42 +02:00
|
|
|
/**
|
2009-11-25 21:55:06 +01:00
|
|
|
* cleanup the database; ie. remove entries for which no longer a corresponding
|
|
|
|
* file exists in the maildir
|
|
|
|
*
|
|
|
|
* @param index a valid MuIndex instance
|
2010-01-04 19:19:32 +01:00
|
|
|
* @param stats a structure with some statistics about the results;
|
|
|
|
* note that this function does *not* reset the struct values to allow
|
|
|
|
* for cumulative stats from multiple calls. If needed, you can use
|
|
|
|
* @mu_index_stats_clear before calling this function
|
2009-11-25 21:55:06 +01:00
|
|
|
* @param cb a callback function which will be called for every msg;
|
|
|
|
* @param user_data a user pointer that will be passed to the callback function
|
|
|
|
*
|
|
|
|
* @return MU_OK if the stats gathering was completed succesfully,
|
|
|
|
* MU_STOP if the user stopped or MU_ERROR in
|
|
|
|
* case of some error.
|
|
|
|
*/
|
2010-01-04 19:19:32 +01:00
|
|
|
MuResult mu_index_cleanup (MuIndex *index, MuIndexStats *stats,
|
2010-01-03 12:41:32 +01:00
|
|
|
MuIndexCleanupDeleteCallback cb,
|
2009-11-25 21:55:06 +01:00
|
|
|
void *user_data);
|
|
|
|
|
2010-09-26 14:52:42 +02:00
|
|
|
/**
|
2010-01-04 19:19:32 +01:00
|
|
|
* clear the stats structure
|
|
|
|
*
|
|
|
|
* @param stats a MuIndexStats object
|
|
|
|
*
|
|
|
|
* @return TRUE if stats != NULL, FALSE otherwise
|
|
|
|
*/
|
|
|
|
gboolean mu_index_stats_clear (MuIndexStats *stats);
|
|
|
|
|
2009-11-25 21:55:06 +01:00
|
|
|
#endif /*__MU_INDEX_H__*/
|