git.notmuchmail.org Git - notmuch/blob - notmuch.h

   1 /* notmuch - Not much of an email library, (just index and search)
   2  *
   3  * Copyright © 2009 Carl Worth
   4  *
   5  * This program is free software: you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation, either version 3 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program.  If not, see http://www.gnu.org/licenses/ .
  17  *
  18  * Author: Carl Worth <cworth@cworth.org>
  19  */
  20
  21 #ifndef NOTMUCH_H
  22 #define NOTMUCH_H
  23
  24 #ifdef  __cplusplus
  25 # define NOTMUCH_BEGIN_DECLS  extern "C" {
  26 # define NOTMUCH_END_DECLS    }
  27 #else
  28 # define NOTMUCH_BEGIN_DECLS
  29 # define NOTMUCH_END_DECLS
  30 #endif
  31
  32 NOTMUCH_BEGIN_DECLS
  33
  34 /* Status codes used for the return values of most functions.
  35  *
  36  * A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function
  37  * completed without error. Any other value indicates an error as
  38  * follows:
  39  *
  40  * NOTMUCH_STATUS_SUCCESS: No error occurred.
  41  *
  42  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
  43  *
  44  * NOTMUCH_STATUS_FILE_NOT_EMAIL: A file was presented that doesn't
  45  *      appear to be an email message.
  46  */
  47 typedef enum _notmuch_status {
  48     NOTMUCH_STATUS_SUCCESS = 0,
  49     NOTMUCH_STATUS_XAPIAN_EXCEPTION,
  50     NOTMUCH_STATUS_FILE_NOT_EMAIL
  51 } notmuch_status_t;
  52
  53 /* An opaque data structure representing a notmuch database. See
  54  * notmuch_database_open and other notmuch_database functions
  55  * below. */
  56 typedef struct _notmuch_database notmuch_database_t;
  57
  58 /* Create a new, empty notmuch database located at 'path'.
  59  *
  60  * The path should be a top-level directory to a collection of
  61  * plain-text email messages (one message per file). This call will
  62  * create a new ".notmuch" directory within 'path' where notmuch will
  63  * store its data.
  64  *
  65  * Passing a value of NULL for 'path' will cause notmuch to open the
  66  * default database. The default database path can be specified by the
  67  * NOTMUCH_BASE environment variable, and is equivalent to
  68  * ${HOME}/mail if NOTMUCH_BASE is not set.
  69  *
  70  * After a successful call to notmuch_database_create, the returned
  71  * database will be open so the caller should call
  72  * notmuch_database_close when finished with it.
  73  *
  74  * The database will not yet have any data in it
  75  * (notmuch_database_create itself is a very cheap function). Messages
  76  * contained within 'path' can be added to the database by calling
  77  * notmuch_database_add_message.
  78  *
  79  * In case of any failure, this function returns NULL, (after printing
  80  * an error message on stderr).
  81  */
  82 notmuch_database_t *
  83 notmuch_database_create (const char *path);
  84
  85 /* Open a an existing notmuch database located at 'path'.
  86  *
  87  * The database should have been created at some time in the past,
  88  * (not necessarily by this process), by calling
  89  * notmuch_database_create with 'path'.
  90  *
  91  * An existing notmuch database can be identified by the presence of a
  92  * directory named ".notmuch" below 'path'.
  93  *
  94  * Passing a value of NULL for 'path' will cause notmuch to open the
  95  * default database. The default database path can be specified by the
  96  * NOTMUCH_BASE environment variable, and is equivalent to
  97  * ${HOME}/mail if NOTMUCH_BASE is not set.
  98  *
  99  * The caller should call notmuch_database_close when finished with
 100  * this database.
 101  *
 102  * In case of any failure, this function returns NULL, (after printing
 103  * an error message on stderr).
 104  */
 105 notmuch_database_t *
 106 notmuch_database_open (const char *path);
 107
 108 /* Close the given notmuch database, freeing all associated
 109  * resources. See notmuch_database_open. */
 110 void
 111 notmuch_database_close (notmuch_database_t *database);
 112
 113 /* Lookup the default database path.
 114  *
 115  * This is the path that will be used by notmuch_database_create and
 116  * notmuch_database_open if given a NULL path. Specifically it will be
 117  * the value of the NOTMUCH_BASE environment variable if set,
 118  * otherwise ${HOME}/mail
 119  *
 120  * Returns a newly allocated string which the caller should free()
 121  * when finished with it.
 122  */
 123 char *
 124 notmuch_database_default_path (void);
 125
 126 /* Return the database path of the given database.
 127  *
 128  * The return value is a string owned by notmuch so should not be
 129  * modified nor freed by the caller. */
 130 const char *
 131 notmuch_database_get_path (notmuch_database_t *database);
 132
 133 /* Add a new message to the given notmuch database.
 134  *
 135  * Here,'filename' should be a path relative to the the path of
 136  * 'database' (see notmuch_database_get_path). The file should be a
 137  * single mail message (not a multi-message mbox) that is expected to
 138  * remain at its current location, (since the notmuch database will
 139  * reference the filename, and will not copy the entire contents of
 140  * the file.
 141  *
 142  * Return value:
 143  *
 144  * NOTMUCH_STATUS_SUCCESS: Message successfully added to database.
 145  *
 146  * NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look
 147  *      like an email message. Nothing added to the database.
 148  */
 149 notmuch_status_t
 150 notmuch_database_add_message (notmuch_database_t *database,
 151                               const char *filename);
 152
 153 NOTMUCH_END_DECLS
 154
 155 #endif