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 typedef enum _notmuch_status {
  45     NOTMUCH_STATUS_SUCCESS = 0,
  46     NOTMUCH_STATUS_XAPIAN_EXCEPTION
  47 } notmuch_status_t;
  48
  49 /* An opaque data structure representing a notmuch database. See
  50  * notmuch_database_open and other notmuch_database functions
  51  * below. */
  52 typedef struct _notmuch_database notmuch_database_t;
  53
  54 /* Create a new, empty notmuch database located at 'path'.
  55  *
  56  * The path should be a top-level directory to a collection of
  57  * plain-text email messages (one message per file). This call will
  58  * create a new ".notmuch" directory within 'path' where notmuch will
  59  * store its data.
  60  *
  61  * Passing a value of NULL for 'path' will cause notmuch to open the
  62  * default database. The default database path can be specified by the
  63  * NOTMUCH_BASE environment variable, and is equivalent to
  64  * ${HOME}/mail if NOTMUCH_BASE is not set.
  65  *
  66  * After a successful call to notmuch_database_create, the returned
  67  * database will be open so the caller should call
  68  * notmuch_database_close when finished with it.
  69  *
  70  * The database will not yet have any data in it
  71  * (notmuch_database_create itself is a very cheap function). Messages
  72  * contained within 'path' can be added to the database by calling
  73  * notmuch_database_add_message.
  74  *
  75  * In case of any failure, this function returns NULL, (after printing
  76  * an error message on stderr).
  77  */
  78 notmuch_database_t *
  79 notmuch_database_create (const char *path);
  80
  81 /* Open a an existing notmuch database located at 'path'.
  82  *
  83  * The database should have been created at some time in the past,
  84  * (not necessarily by this process), by calling
  85  * notmuch_database_create with 'path'.
  86  *
  87  * An existing notmuch database can be identified by the presence of a
  88  * directory named ".notmuch" below 'path'.
  89  *
  90  * Passing a value of NULL for 'path' will cause notmuch to open the
  91  * default database. The default database path can be specified by the
  92  * NOTMUCH_BASE environment variable, and is equivalent to
  93  * ${HOME}/mail if NOTMUCH_BASE is not set.
  94  *
  95  * The caller should call notmuch_database_close when finished with
  96  * this database.
  97  *
  98  * In case of any failure, this function returns NULL, (after printing
  99  * an error message on stderr).
 100  */
 101 notmuch_database_t *
 102 notmuch_database_open (const char *path);
 103
 104 /* Close the given notmuch database, freeing all associated
 105  * resources. See notmuch_database_open. */
 106 void
 107 notmuch_database_close (notmuch_database_t *database);
 108
 109 const char *
 110 notmuch_database_get_path (notmuch_database_t *database);
 111
 112 /* Add a new message to the given notmuch database.
 113  *
 114  * Here,'filename' should be a path relative to the the path of
 115  * 'database' (see notmuch_database_get_path). The file should be a
 116  * single mail message (not a multi-message mbox) that is expected to
 117  * remain at its current location, (since the notmuch database will
 118  * reference the filename, and will not copy the entire contents of
 119  * the file. */
 120 notmuch_status_t
 121 notmuch_database_add_message (notmuch_database_t *database,
 122                               const char *filename);
 123
 124 NOTMUCH_END_DECLS
 125
 126 #endif