*
* NOTMUCH_STATUS_SUCCESS: No error occurred.
*
+ * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory
+ *
* XXX: We don't really want to expose this lame XAPIAN_EXCEPTION
* value. Instead we should map to things like DATABASE_LOCKED or
* whatever.
*/
typedef enum _notmuch_status {
NOTMUCH_STATUS_SUCCESS = 0,
+ NOTMUCH_STATUS_OUT_OF_MEMORY,
NOTMUCH_STATUS_XAPIAN_EXCEPTION,
NOTMUCH_STATUS_FILE_ERROR,
NOTMUCH_STATUS_FILE_NOT_EMAIL,
typedef struct _notmuch_results notmuch_results_t;
typedef struct _notmuch_message notmuch_message_t;
typedef struct _notmuch_tags notmuch_tags_t;
-typedef struct _notmuch_thread_ids notmuch_thread_ids_t;
+
+/* Lookup the default database path.
+ *
+ * This is the path that will be used by notmuch_database_create and
+ * notmuch_database_open if given a NULL path. Specifically it will be
+ * the value of the NOTMUCH_BASE environment variable if set,
+ * otherwise ${HOME}/mail
+ *
+ * Returns a newly allocated string which the caller should free()
+ * when finished with it.
+ */
+char *
+notmuch_database_default_path (void);
/* Create a new, empty notmuch database located at 'path'.
*
notmuch_database_t *
notmuch_database_create (const char *path);
+/* XXX: I think I'd like this to take an extra argument of
+ * notmuch_status_t* for returning a status value on failure. */
+
/* Open a an existing notmuch database located at 'path'.
*
* The database should have been created at some time in the past,
void
notmuch_database_close (notmuch_database_t *database);
-/* Lookup the default database path.
- *
- * This is the path that will be used by notmuch_database_create and
- * notmuch_database_open if given a NULL path. Specifically it will be
- * the value of the NOTMUCH_BASE environment variable if set,
- * otherwise ${HOME}/mail
- *
- * Returns a newly allocated string which the caller should free()
- * when finished with it.
- */
-char *
-notmuch_database_default_path (void);
-
/* Return the database path of the given database.
*
* The return value is a string owned by notmuch so should not be
* a new notmuch_message_t object is returned. The caller should call
* notmuch_message_destroy when done with the message.
*
- * If no message is found with the given message_id, this function
- * returns NULL.
+ * If no message is found with the given message_id or if an
+ * out-of-memory situation occurs, this function returns NULL.
*/
notmuch_message_t *
notmuch_database_find_message (notmuch_database_t *database,
*
* See the documentation of notmuch_query_search for example code
* showing how to iterate over a notmuch_results_t object.
+ *
+ * If an out-of-memory situation occurs, this function will return
+ * NULL.
*/
notmuch_message_t *
notmuch_results_get (notmuch_results_t *results);
const char *
notmuch_message_get_message_id (notmuch_message_t *message);
+
+/* Get the thread ID of 'message'.
+ *
+ * The returned string belongs to 'message' and as such, should not be
+ * modified by the caller and will only be valid for as long as the
+ * message is valid, (for example, until the user calls
+ * notmuch_message_destroy on 'message' or until a query from which it
+ * derived is destroyed).
+ *
+ * This function will not return NULL since Notmuch ensures that every
+ * message belongs to a single thread.
+ */
+const char *
+notmuch_message_get_thread_id (notmuch_message_t *message);
+
/* Get the filename for the email corresponding to 'message'.
*
* The returned filename is relative to the base of the database from
notmuch_tags_t *
notmuch_message_get_tags (notmuch_message_t *message);
-/* Get the thread IDs for 'message', returning a notmuch_thread_ids_t
- * object which can be used to iterate over all thread IDs.
- *
- * The thread_ids object is owned by the message and as such, will
- * only be valid for as long as the message is valid, (which is until
- * the query from which it derived is destroyed).
- *
- * Typical usage might be:
- *
- * notmuch_message_t *message;
- * notmuch_thread_ids_t *thread_ids;
- * const char *thread_id;
- *
- * message = notmuch_database_find_message (database, message_id);
- *
- * for (thread_ids = notmuch_message_get_thread_ids (message);
- * notmuch_thread_ids_has_more (thread_ids);
- * notmuch_thread_ids_advance (thread_ids))
- * {
- * thread_id = notmuch_thread_ids_get (thread_ids);
- * ....
- * }
- *
- * notmuch_message_destroy (message);
- *
- * Note that there's no explicit destructor needed for the
- * notmuch_thread_ids_t object. (For consistency, we do provide a
- * notmuch_thread_ids_destroy function, but there's no good reason to
- * call it if the message is about to be destroyed).
- */
-notmuch_thread_ids_t *
-notmuch_message_get_thread_ids (notmuch_message_t *message);
-
/* The longest possible tag value. */
#define NOTMUCH_TAG_MAX 200
void
notmuch_tags_destroy (notmuch_tags_t *tags);
-/* Does the given notmuch_thread_ids_t object contain any more thread IDs.
- *
- * When this function returns TRUE, notmuch_thread_ids_get will return a
- * valid string. Whereas when this function returns FALSE,
- * notmuch_thread_ids_get will return NULL.
- *
- * See the documentation of notmuch_message_get_thread_ids for example code
- * showing how to iterate over a notmuch_thread_ids_t object.
- */
-notmuch_bool_t
-notmuch_thread_ids_has_more (notmuch_thread_ids_t *thread_ids);
-
-/* Get the current thread ID from 'thread_ids' as a string.
- *
- * Note: The returned string belongs to 'thread_ids' and has a lifetime
- * identical to it (and the query to which it utlimately belongs).
- *
- * See the documentation of notmuch_message_get_thread_ids for example code
- * showing how to iterate over a notmuch_thread_ids_t object.
- */
-const char *
-notmuch_thread_ids_get (notmuch_thread_ids_t *thread_ids);
-
-/* Advance the 'thread_ids' iterator to the next tag.
- *
- * See the documentation of notmuch_message_get_thread_ids for example code
- * showing how to iterate over a notmuch_thread_ids_t object.
- */
-void
-notmuch_thread_ids_advance (notmuch_thread_ids_t *thread_ids);
-
-/* Destroy a notmuch_thread_ids_t object.
- *
- * It's not strictly necessary to call this function. All memory from
- * the notmuch_thread_ids_t object will be reclaimed when the containg
- * message or query objects are destroyed.
- */
-void
-notmuch_thread_ids_destroy (notmuch_thread_ids_t *thread_ids);
-
NOTMUCH_END_DECLS
#endif
projects / notmuch / blobdiff