const char *
notmuch_query_get_query_string (notmuch_query_t *query);
-/* Exclude values for notmuch_query_set_omit_excluded */
+/* Exclude values for notmuch_query_set_omit_excluded. The strange
+ * order is to maintain backward compatibility: the old FALSE/TRUE
+ * options correspond to the new
+ * NOTMUCH_EXCLUDE_FLAG/NOTMUCH_EXCLUDE_TRUE options.
+ */
typedef enum {
- NOTMUCH_EXCLUDE_FALSE,
+ NOTMUCH_EXCLUDE_FLAG,
NOTMUCH_EXCLUDE_TRUE,
+ NOTMUCH_EXCLUDE_FALSE,
NOTMUCH_EXCLUDE_ALL
} notmuch_exclude_t;
* match in at least one non-excluded message. Otherwise, if set to ALL,
* notmuch_query_search_threads will omit excluded messages from all threads.
*
+ * If set to FALSE or FLAG then both notmuch_query_search_messages and
+ * notmuch_query_search_threads will return all matching
+ * messages/threads regardless of exclude status. If set to FLAG then
+ * the exclude flag will be set for any excluded message that is
+ * returned by notmuch_query_search_messages, and the thread counts
+ * for threads returned by notmuch_query_search_threads will be the
+ * number of non-excluded messages/matches. Otherwise, if set to
+ * FALSE, then the exclude status is completely ignored.
+ *
* The performance difference when calling
* notmuch_query_search_messages should be relatively small (and both
* should be very fast). However, in some cases,
/* Get the value of the specified header from 'message'.
*
- * The value will be read from the actual message file, not from the
- * notmuch database. The header name is case insensitive.
+ * Common headers are stored in the database when the message is
+ * indexed and will be returned from the database. Other headers will
+ * be read from the actual message file.
+ *
+ * The header name is case insensitive.
*
* The returned string belongs to the message so should not be
* modified or freed by the caller (nor should it be referenced after