typedef struct _notmuch_directory notmuch_directory_t;
typedef struct _notmuch_filenames notmuch_filenames_t;
typedef struct _notmuch_config_list notmuch_config_list_t;
-typedef struct _notmuch_param notmuch_param_t;
+typedef struct _notmuch_indexopts notmuch_indexopts_t;
#endif /* __DOXYGEN__ */
/**
* The database will not yet have any data in it
* (notmuch_database_create itself is a very cheap function). Messages
* contained within 'path' can be added to the database by calling
- * notmuch_database_add_message.
+ * notmuch_database_index_file.
*
* In case of any failure, this function returns an error status and
* sets *database to NULL (after printing an error message on stderr).
notmuch_directory_t **directory);
/**
- * Add a new message to the given notmuch database or associate an
- * additional filename with an existing message.
+ * Add a message file to a database, indexing it for retrieval by
+ * future searches. If a message already exists with the same message
+ * ID as the specified file, their indexes will be merged, and this
+ * new filename will also be associated with the existing message.
*
* Here, 'filename' should be a path relative to the path of
* 'database' (see notmuch_database_get_path), or else should be an
* entire contents of the file.
*
* If another message with the same message ID already exists in the
- * database, rather than creating a new message, this adds 'filename'
- * to the list of the filenames for the existing message.
+ * database, rather than creating a new message, this adds the search
+ * terms from the identified file to the existing message's index, and
+ * adds 'filename' to the list of filenames known for the message.
+ *
+ * The 'indexopts' parameter can be NULL (meaning, use the indexing
+ * defaults from the database), or can be an explicit choice of
+ * indexing options that should govern the indexing of this specific
+ * 'filename'.
*
* If 'message' is not NULL, then, on successful return
* (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message'
*
* NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
* database to use this function.
+ *
+ * @since libnotmuch 5.1 (notmuch 0.26)
*/
notmuch_status_t
+notmuch_database_index_file (notmuch_database_t *database,
+ const char *filename,
+ notmuch_indexopts_t *indexopts,
+ notmuch_message_t **message);
+
+/**
+ * Deprecated alias for notmuch_database_index_file called with
+ * NULL indexopts.
+ *
+ * @deprecated Deprecated as of libnotmuch 5.1 (notmuch 0.26). Please
+ * use notmuch_database_index_file instead.
+ *
+ */
+NOTMUCH_DEPRECATED(5,1)
+notmuch_status_t
notmuch_database_add_message (notmuch_database_t *database,
const char *filename,
notmuch_message_t **message);
* Re-index the e-mail corresponding to 'message' using the supplied index options
*
* Returns the status of the re-index operation. (see the return
- * codes documented in notmuch_database_add_message)
+ * codes documented in notmuch_database_index_file)
*
* After reindexing, the user should discard the message object passed
* in here by calling notmuch_message_destroy, since it refers to the
*/
notmuch_status_t
notmuch_message_reindex (notmuch_message_t *message,
- notmuch_param_t *indexopts);
+ notmuch_indexopts_t *indexopts);
/**
* Message flags.
*
* A client can ensure that notmuch database tags remain synchronized
* with maildir flags by calling this function after each call to
- * notmuch_database_add_message. See also
+ * notmuch_database_index_file. See also
* notmuch_message_tags_to_maildir_flags for synchronizing tag changes
* back to maildir flags.
*/
notmuch_status_t
notmuch_message_maildir_flags_to_tags (notmuch_message_t *message);
+/**
+ * return TRUE if any filename of 'message' has maildir flag 'flag',
+ * FALSE otherwise.
+ *
+ */
+notmuch_bool_t
+notmuch_message_has_maildir_flag (notmuch_message_t *message, char flag);
+
/**
* Rename message filename(s) to encode tags as maildir flags.
*
*
* o Read the mtime of a directory from the filesystem
*
- * o Call add_message for all mail files in the directory
+ * o Call index_file for all mail files in the directory
*
* o Call notmuch_directory_set_mtime with the mtime read from the
* filesystem.
void
notmuch_config_list_destroy (notmuch_config_list_t *config_list);
+
+/**
+ * get the current default indexing options for a given database.
+ *
+ * This object will survive until the database itself is destroyed,
+ * but the caller may also release it earlier with
+ * notmuch_indexopts_destroy.
+ *
+ * This object represents a set of options on how a message can be
+ * added to the index. At the moment it is a featureless stub.
+ *
+ * @since libnotmuch 5.1 (notmuch 0.26)
+ */
+notmuch_indexopts_t *
+notmuch_database_get_default_indexopts (notmuch_database_t *db);
+
+/**
+ * Destroy a notmuch_indexopts_t object.
+ *
+ * @since libnotmuch 5.1 (notmuch 0.26)
+ */
+void
+notmuch_indexopts_destroy (notmuch_indexopts_t *options);
+
+
/**
* interrogate the library for compile time features
*