--- name: "notmuch" section: "3" platform: "linux" package: "notmuch-runtime" version: "0.40-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/notmuch/3" --- # notmuch(3) The notmuch API - Not much of an email library, (just index and search). ## NAME notmuch - The notmuch API \- Not much of an email library, (just index and search). ## SYNOPSIS ### Macros \#define **LIBNOTMUCH\_CHECK\_VERSION**(major, minor, micro)\ Check the version of the notmuch library being compiled against. #define **NOTMUCH\_TAG\_MAX** 200\ The longest possible tag value. ### Typedefs typedef int **notmuch\_bool\_t**\ Notmuch boolean type. typedef void(\* **notmuch\_compact\_status\_cb\_t**) (const char \*message, void \*closure)\ A callback invoked by notmuch\_database\_compact to notify the user of the progress of the compaction process. ### Enumerations enum **notmuch\_status\_t** { **NOTMUCH\_STATUS\_SUCCESS** = 0, **NOTMUCH\_STATUS\_OUT\_OF\_MEMORY**, **NOTMUCH\_STATUS\_READ\_ONLY\_DATABASE**, **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION**, **NOTMUCH\_STATUS\_FILE\_ERROR**, **NOTMUCH\_STATUS\_FILE\_NOT\_EMAIL**, **NOTMUCH\_STATUS\_DUPLICATE\_MESSAGE\_ID**, **NOTMUCH\_STATUS\_NULL\_POINTER**, **NOTMUCH\_STATUS\_TAG\_TOO\_LONG**, **NOTMUCH\_STATUS\_UNBALANCED\_FREEZE\_THAW**, **NOTMUCH\_STATUS\_UNBALANCED\_ATOMIC**, **NOTMUCH\_STATUS\_UNSUPPORTED\_OPERATION**, **NOTMUCH\_STATUS\_UPGRADE\_REQUIRED**, **NOTMUCH\_STATUS\_PATH\_ERROR**, **NOTMUCH\_STATUS\_IGNORED**, **NOTMUCH\_STATUS\_ILLEGAL\_ARGUMENT**, **NOTMUCH\_STATUS\_MALFORMED\_CRYPTO\_PROTOCOL**, **NOTMUCH\_STATUS\_FAILED\_CRYPTO\_CONTEXT\_CREATION**, **NOTMUCH\_STATUS\_UNKNOWN\_CRYPTO\_PROTOCOL**, **NOTMUCH\_STATUS\_NO\_CONFIG**, **NOTMUCH\_STATUS\_NO\_DATABASE**, **NOTMUCH\_STATUS\_DATABASE\_EXISTS**, **NOTMUCH\_STATUS\_BAD\_QUERY\_SYNTAX**, **NOTMUCH\_STATUS\_NO\_MAIL\_ROOT**, **NOTMUCH\_STATUS\_CLOSED\_DATABASE**, **NOTMUCH\_STATUS\_ITERATOR\_EXHAUSTED**, **NOTMUCH\_STATUS\_OPERATION\_INVALIDATED**, **NOTMUCH\_STATUS\_LAST\_STATUS** }\ Status codes used for the return values of most functions. enum **notmuch\_database\_mode\_t** { **NOTMUCH\_DATABASE\_MODE\_READ\_ONLY** = 0, **NOTMUCH\_DATABASE\_MODE\_READ\_WRITE** }\ Database open mode for notmuch\_database\_open. enum **notmuch\_query\_syntax\_t** { **NOTMUCH\_QUERY\_SYNTAX\_XAPIAN**, **NOTMUCH\_QUERY\_SYNTAX\_SEXP** }\ enum **notmuch\_sort\_t** { **NOTMUCH\_SORT\_OLDEST\_FIRST**, **NOTMUCH\_SORT\_NEWEST\_FIRST**, **NOTMUCH\_SORT\_MESSAGE\_ID**, **NOTMUCH\_SORT\_UNSORTED** }\ Sort values for notmuch\_query\_set\_sort. enum **notmuch\_exclude\_t** { **NOTMUCH\_EXCLUDE\_FLAG**, **NOTMUCH\_EXCLUDE\_TRUE**, **NOTMUCH\_EXCLUDE\_FALSE**, **NOTMUCH\_EXCLUDE\_ALL** }\ Exclude values for notmuch\_query\_set\_omit\_excluded. enum **notmuch\_message\_flag\_t** { **NOTMUCH\_MESSAGE\_FLAG\_MATCH**, **NOTMUCH\_MESSAGE\_FLAG\_EXCLUDED**, **NOTMUCH\_MESSAGE\_FLAG\_GHOST** }\ Message flags. enum **notmuch\_config\_key\_t** { **NOTMUCH\_CONFIG\_FIRST**, **NOTMUCH\_CONFIG\_DATABASE\_PATH** = NOTMUCH\_CONFIG\_FIRST, **NOTMUCH\_CONFIG\_MAIL\_ROOT**, **NOTMUCH\_CONFIG\_HOOK\_DIR**, **NOTMUCH\_CONFIG\_BACKUP\_DIR**, **NOTMUCH\_CONFIG\_EXCLUDE\_TAGS**, **NOTMUCH\_CONFIG\_NEW\_TAGS**, **NOTMUCH\_CONFIG\_NEW\_IGNORE**, **NOTMUCH\_CONFIG\_SYNC\_MAILDIR\_FLAGS**, **NOTMUCH\_CONFIG\_PRIMARY\_EMAIL**, **NOTMUCH\_CONFIG\_OTHER\_EMAIL**, **NOTMUCH\_CONFIG\_USER\_NAME**, **NOTMUCH\_CONFIG\_AUTOCOMMIT**, **NOTMUCH\_CONFIG\_EXTRA\_HEADERS**, **NOTMUCH\_CONFIG\_INDEX\_AS\_TEXT**, **NOTMUCH\_CONFIG\_AUTHORS\_SEPARATOR**, **NOTMUCH\_CONFIG\_AUTHORS\_MATCHED\_SEPARATOR**, **NOTMUCH\_CONFIG\_LAST** }\ Configuration keys known to libnotmuch. enum **notmuch\_decryption\_policy\_t** { **NOTMUCH\_DECRYPT\_FALSE**, **NOTMUCH\_DECRYPT\_TRUE**, **NOTMUCH\_DECRYPT\_AUTO**, **NOTMUCH\_DECRYPT\_NOSTASH** }\ Stating a policy about how to decrypt messages. ### Functions const char \* **notmuch\_status\_to\_string** (**notmuch\_status\_t** status)\ Get a string representation of a **notmuch\_status\_t** value. **notmuch\_status\_t** **notmuch\_database\_create** (const char \*path, notmuch\_database\_t \*\*database)\ Create a new, empty notmuch database located at 'path'. **notmuch\_status\_t** **notmuch\_database\_create\_verbose** (const char \*path, notmuch\_database\_t \*\*database, char \*\*error\_message)\ Like notmuch\_database\_create, except optionally return an error message. **notmuch\_status\_t** **notmuch\_database\_open** (const char \*path, **notmuch\_database\_mode\_t** mode, notmuch\_database\_t \*\*database)\ Deprecated alias for notmuch\_database\_open\_with\_config with config\_path=" and error\_message=NULL. **notmuch\_status\_t** **notmuch\_database\_open\_verbose** (const char \*path, **notmuch\_database\_mode\_t** mode, notmuch\_database\_t \*\*database, char \*\*error\_message)\ Deprecated alias for notmuch\_database\_open\_with\_config with config\_path=". **notmuch\_status\_t** **notmuch\_database\_open\_with\_config** (const char \*database\_path, **notmuch\_database\_mode\_t** mode, const char \*config\_path, const char \*profile, notmuch\_database\_t \*\*database, char \*\*error\_message)\ Open an existing notmuch database located at 'database\_path', using configuration in 'config\_path'. **notmuch\_status\_t** **notmuch\_database\_load\_config** (const char \*database\_path, const char \*config\_path, const char \*profile, notmuch\_database\_t \*\*database, char \*\*error\_message)\ Loads configuration from config file, database, and/or defaults. **notmuch\_status\_t** **notmuch\_database\_create\_with\_config** (const char \*database\_path, const char \*config\_path, const char \*profile, notmuch\_database\_t \*\*database, char \*\*error\_message)\ Create a new notmuch database located at 'database\_path', using configuration in 'config\_path'. const char \* **notmuch\_database\_status\_string** (const notmuch\_database\_t \*notmuch)\ Retrieve last status string for given database. **notmuch\_status\_t** **notmuch\_database\_close** (notmuch\_database\_t \*database)\ Commit changes and close the given notmuch database. **notmuch\_status\_t** **notmuch\_database\_compact** (const char \*path, const char \*backup\_path, **notmuch\_compact\_status\_cb\_t** status\_cb, void \*closure)\ Compact a notmuch database, backing up the original database to the given path. **notmuch\_status\_t** **notmuch\_database\_compact\_db** (notmuch\_database\_t \*database, const char \*backup\_path, **notmuch\_compact\_status\_cb\_t** status\_cb, void \*closure)\ Like notmuch\_database\_compact, but take an open database as a parameter. **notmuch\_status\_t** **notmuch\_database\_destroy** (notmuch\_database\_t \*database)\ Destroy the notmuch database, closing it if necessary and freeing all associated resources. const char \* **notmuch\_database\_get\_path** (notmuch\_database\_t \*database)\ Return the database path of the given database. unsigned int **notmuch\_database\_get\_version** (notmuch\_database\_t \*database)\ Return the database format version of the given database. **notmuch\_bool\_t** **notmuch\_database\_needs\_upgrade** (notmuch\_database\_t \*database)\ Can the database be upgraded to a newer database version? **notmuch\_status\_t** **notmuch\_database\_upgrade** (notmuch\_database\_t \*database, void(\*progress\_notify)(void \*closure, double progress), void \*closure)\ Upgrade the current database to the latest supported version. **notmuch\_status\_t** **notmuch\_database\_begin\_atomic** (notmuch\_database\_t \*notmuch)\ Begin an atomic database operation. **notmuch\_status\_t** **notmuch\_database\_end\_atomic** (notmuch\_database\_t \*notmuch)\ Indicate the end of an atomic database operation. unsigned long **notmuch\_database\_get\_revision** (notmuch\_database\_t \*notmuch, const char \*\*uuid)\ Return the committed database revision and UUID. **notmuch\_status\_t** **notmuch\_database\_get\_directory** (notmuch\_database\_t \*database, const char \*path, notmuch\_directory\_t \*\*directory)\ Retrieve a directory object from the database for 'path'. **notmuch\_status\_t** **notmuch\_database\_index\_file** (notmuch\_database\_t \*database, const char \*filename, notmuch\_indexopts\_t \*indexopts, notmuch\_message\_t \*\*message)\ Add a message file to a database, indexing it for retrieval by future searches. **notmuch\_status\_t** **notmuch\_database\_add\_message** (notmuch\_database\_t \*database, const char \*filename, notmuch\_message\_t \*\*message)\ Deprecated alias for notmuch\_database\_index\_file called with NULL indexopts. **notmuch\_status\_t** **notmuch\_database\_remove\_message** (notmuch\_database\_t \*database, const char \*filename)\ Remove a message filename from the given notmuch database. **notmuch\_status\_t** **notmuch\_database\_find\_message** (notmuch\_database\_t \*database, const char \*message\_id, notmuch\_message\_t \*\*message)\ Find a message with the given message\_id. **notmuch\_status\_t** **notmuch\_database\_find\_message\_by\_filename** (notmuch\_database\_t \*notmuch, const char \*filename, notmuch\_message\_t \*\*message)\ Find a message with the given filename. notmuch\_tags\_t \* **notmuch\_database\_get\_all\_tags** (notmuch\_database\_t \*db)\ Return a list of all tags found in the database. **notmuch\_status\_t** **notmuch\_database\_reopen** (notmuch\_database\_t \*db, **notmuch\_database\_mode\_t** mode)\ Reopen an open notmuch database. notmuch\_query\_t \* **notmuch\_query\_create** (notmuch\_database\_t \*database, const char \*query\_string)\ Create a new query for 'database'. **notmuch\_status\_t** **notmuch\_query\_create\_with\_syntax** (notmuch\_database\_t \*database, const char \*query\_string, notmuch\_query\_syntax\_t syntax, notmuch\_query\_t \*\*output)\ const char \* **notmuch\_query\_get\_query\_string** (const notmuch\_query\_t \*query)\ Return the query\_string of this query. notmuch\_database\_t \* **notmuch\_query\_get\_database** (const notmuch\_query\_t \*query)\ Return the notmuch database of this query. void **notmuch\_query\_set\_omit\_excluded** (notmuch\_query\_t \*query, **notmuch\_exclude\_t** omit\_excluded)\ Specify whether to omit excluded results or simply flag them. void **notmuch\_query\_set\_sort** (notmuch\_query\_t \*query, **notmuch\_sort\_t** sort)\ Specify the sorting desired for this query. **notmuch\_sort\_t** **notmuch\_query\_get\_sort** (const notmuch\_query\_t \*query)\ Return the sort specified for this query. **notmuch\_status\_t** **notmuch\_query\_add\_tag\_exclude** (notmuch\_query\_t \*query, const char \*tag)\ Add a tag that will be excluded from the query results by default. **notmuch\_status\_t** **notmuch\_query\_search\_threads** (notmuch\_query\_t \*query, notmuch\_threads\_t \*\*out)\ Execute a query for threads, returning a notmuch\_threads\_t object which can be used to iterate over the results. **notmuch\_status\_t** **notmuch\_query\_search\_threads\_st** (notmuch\_query\_t \*query, notmuch\_threads\_t \*\*out)\ Deprecated alias for notmuch\_query\_search\_threads. **notmuch\_status\_t** **notmuch\_query\_search\_messages** (notmuch\_query\_t \*query, notmuch\_messages\_t \*\*out)\ Execute a query for messages, returning a notmuch\_messages\_t object which can be used to iterate over the results. **notmuch\_status\_t** **notmuch\_query\_search\_messages\_st** (notmuch\_query\_t \*query, notmuch\_messages\_t \*\*out)\ Deprecated alias for notmuch\_query\_search\_messages. void **notmuch\_query\_destroy** (notmuch\_query\_t \*query)\ Destroy a notmuch\_query\_t along with any associated resources. **notmuch\_bool\_t** **notmuch\_threads\_valid** (notmuch\_threads\_t \*threads)\ Is the given 'threads' iterator pointing at a valid thread. **notmuch\_status\_t** **notmuch\_threads\_status** (notmuch\_threads\_t \*threads)\ Get the status of the given 'threads' iterator. notmuch\_thread\_t \* **notmuch\_threads\_get** (notmuch\_threads\_t \*threads)\ Get the current thread from 'threads' as a notmuch\_thread\_t. void **notmuch\_threads\_move\_to\_next** (notmuch\_threads\_t \*threads)\ Move the 'threads' iterator to the next thread. void **notmuch\_threads\_destroy** (notmuch\_threads\_t \*threads)\ Destroy a notmuch\_threads\_t object. **notmuch\_status\_t** **notmuch\_query\_count\_messages** (notmuch\_query\_t \*query, unsigned int \*count)\ Return the number of messages matching a search. **notmuch\_status\_t** **notmuch\_query\_count\_messages\_st** (notmuch\_query\_t \*query, unsigned int \*count)\ Deprecated alias for notmuch\_query\_count\_messages. **notmuch\_status\_t** **notmuch\_query\_count\_threads** (notmuch\_query\_t \*query, unsigned \*count)\ Return the number of threads matching a search. **notmuch\_status\_t** **notmuch\_query\_count\_threads\_st** (notmuch\_query\_t \*query, unsigned \*count)\ Deprecated alias for notmuch\_query\_count\_threads. const char \* **notmuch\_thread\_get\_thread\_id** (notmuch\_thread\_t \*thread)\ Get the thread ID of 'thread'. int **notmuch\_thread\_get\_total\_messages** (notmuch\_thread\_t \*thread)\ Get the total number of messages in 'thread'. int **notmuch\_thread\_get\_total\_files** (notmuch\_thread\_t \*thread)\ Get the total number of files in 'thread'. notmuch\_messages\_t \* **notmuch\_thread\_get\_toplevel\_messages** (notmuch\_thread\_t \*thread)\ Get a notmuch\_messages\_t iterator for the top-level messages in 'thread' in oldest-first order. notmuch\_messages\_t \* **notmuch\_thread\_get\_messages** (notmuch\_thread\_t \*thread)\ Get a notmuch\_thread\_t iterator for all messages in 'thread' in oldest-first order. int **notmuch\_thread\_get\_matched\_messages** (notmuch\_thread\_t \*thread)\ Get the number of messages in 'thread' that matched the search. const char \* **notmuch\_thread\_get\_authors** (notmuch\_thread\_t \*thread)\ Get the authors of 'thread' as a UTF-8 string. const char \* **notmuch\_thread\_get\_subject** (notmuch\_thread\_t \*thread)\ Get the subject of 'thread' as a UTF-8 string. time\_t **notmuch\_thread\_get\_oldest\_date** (notmuch\_thread\_t \*thread)\ Get the date of the oldest message in 'thread' as a time\_t value. time\_t **notmuch\_thread\_get\_newest\_date** (notmuch\_thread\_t \*thread)\ Get the date of the newest message in 'thread' as a time\_t value. notmuch\_tags\_t \* **notmuch\_thread\_get\_tags** (notmuch\_thread\_t \*thread)\ Get the tags for 'thread', returning a notmuch\_tags\_t object which can be used to iterate over all tags. void **notmuch\_thread\_destroy** (notmuch\_thread\_t \*thread)\ Destroy a notmuch\_thread\_t object. **notmuch\_bool\_t** **notmuch\_messages\_valid** (notmuch\_messages\_t \*messages)\ Is the given 'messages' iterator pointing at a valid message. **notmuch\_status\_t** **notmuch\_messages\_status** (notmuch\_messages\_t \*messages)\ Get the status of the given 'messages' iterator. notmuch\_message\_t \* **notmuch\_messages\_get** (notmuch\_messages\_t \*messages)\ Get the current message from 'messages' as a notmuch\_message\_t. void **notmuch\_messages\_move\_to\_next** (notmuch\_messages\_t \*messages)\ Move the 'messages' iterator to the next message. void **notmuch\_messages\_destroy** (notmuch\_messages\_t \*messages)\ Destroy a notmuch\_messages\_t object. notmuch\_tags\_t \* **notmuch\_messages\_collect\_tags** (notmuch\_messages\_t \*messages)\ Return a list of tags from all messages. notmuch\_database\_t \* **notmuch\_message\_get\_database** (const notmuch\_message\_t \*message)\ Get the database associated with this message. const char \* **notmuch\_message\_get\_message\_id** (notmuch\_message\_t \*message)\ Get the message ID of 'message'. const char \* **notmuch\_message\_get\_thread\_id** (notmuch\_message\_t \*message)\ Get the thread ID of 'message'. notmuch\_messages\_t \* **notmuch\_message\_get\_replies** (notmuch\_message\_t \*message)\ Get a notmuch\_messages\_t iterator for all of the replies to 'message'. int **notmuch\_message\_count\_files** (notmuch\_message\_t \*message)\ Get the total number of files associated with a message. const char \* **notmuch\_message\_get\_filename** (notmuch\_message\_t \*message)\ Get a filename for the email corresponding to 'message'. notmuch\_filenames\_t \* **notmuch\_message\_get\_filenames** (notmuch\_message\_t \*message)\ Get all filenames for the email corresponding to 'message'. **notmuch\_status\_t** **notmuch\_message\_reindex** (notmuch\_message\_t \*message, notmuch\_indexopts\_t \*indexopts)\ Re-index the e-mail corresponding to 'message' using the supplied index options. **notmuch\_bool\_t** **notmuch\_message\_get\_flag** (notmuch\_message\_t \*message, **notmuch\_message\_flag\_t** flag)\ Get a value of a flag for the email corresponding to 'message'. **notmuch\_status\_t** **notmuch\_message\_get\_flag\_st** (notmuch\_message\_t \*message, **notmuch\_message\_flag\_t** flag, **notmuch\_bool\_t** \*is\_set)\ Get a value of a flag for the email corresponding to 'message'. void **notmuch\_message\_set\_flag** (notmuch\_message\_t \*message, **notmuch\_message\_flag\_t** flag, **notmuch\_bool\_t** value)\ Set a value of a flag for the email corresponding to 'message'. time\_t **notmuch\_message\_get\_date** (notmuch\_message\_t \*message)\ Get the date of 'message' as a time\_t value. const char \* **notmuch\_message\_get\_header** (notmuch\_message\_t \*message, const char \*header)\ Get the value of the specified header from 'message' as a UTF-8 string. notmuch\_tags\_t \* **notmuch\_message\_get\_tags** (notmuch\_message\_t \*message)\ Get the tags for 'message', returning a notmuch\_tags\_t object which can be used to iterate over all tags. **notmuch\_status\_t** **notmuch\_message\_add\_tag** (notmuch\_message\_t \*message, const char \*tag)\ Add a tag to the given message. **notmuch\_status\_t** **notmuch\_message\_remove\_tag** (notmuch\_message\_t \*message, const char \*tag)\ Remove a tag from the given message. **notmuch\_status\_t** **notmuch\_message\_remove\_all\_tags** (notmuch\_message\_t \*message)\ Remove all tags from the given message. **notmuch\_status\_t** **notmuch\_message\_maildir\_flags\_to\_tags** (notmuch\_message\_t \*message)\ Add/remove tags according to maildir flags in the message filename(s). **notmuch\_bool\_t** **notmuch\_message\_has\_maildir\_flag** (notmuch\_message\_t \*message, char flag)\ return TRUE if any filename of 'message' has maildir flag 'flag', FALSE otherwise. **notmuch\_status\_t** **notmuch\_message\_has\_maildir\_flag\_st** (notmuch\_message\_t \*message, char flag, **notmuch\_bool\_t** \*is\_set)\ check message for maildir flag **notmuch\_status\_t** **notmuch\_message\_tags\_to\_maildir\_flags** (notmuch\_message\_t \*message)\ Rename message filename(s) to encode tags as maildir flags. **notmuch\_status\_t** **notmuch\_message\_freeze** (notmuch\_message\_t \*message)\ Freeze the current state of 'message' within the database. **notmuch\_status\_t** **notmuch\_message\_thaw** (notmuch\_message\_t \*message)\ Thaw the current 'message', synchronizing any changes that may have occurred while 'message' was frozen into the notmuch database. void **notmuch\_message\_destroy** (notmuch\_message\_t \*message)\ Destroy a notmuch\_message\_t object. **notmuch\_bool\_t** **notmuch\_tags\_valid** (notmuch\_tags\_t \*tags)\ Is the given 'tags' iterator pointing at a valid tag. const char \* **notmuch\_tags\_get** (notmuch\_tags\_t \*tags)\ Get the current tag from 'tags' as a string. void **notmuch\_tags\_move\_to\_next** (notmuch\_tags\_t \*tags)\ Move the 'tags' iterator to the next tag. void **notmuch\_tags\_destroy** (notmuch\_tags\_t \*tags)\ Destroy a notmuch\_tags\_t object. **notmuch\_status\_t** **notmuch\_directory\_set\_mtime** (notmuch\_directory\_t \*directory, time\_t mtime)\ Store an mtime within the database for 'directory'. time\_t **notmuch\_directory\_get\_mtime** (notmuch\_directory\_t \*directory)\ Get the mtime of a directory, (as previously stored with notmuch\_directory\_set\_mtime). notmuch\_filenames\_t \* **notmuch\_directory\_get\_child\_files** (notmuch\_directory\_t \*directory)\ Get a notmuch\_filenames\_t iterator listing all the filenames of messages in the database within the given directory. notmuch\_filenames\_t \* **notmuch\_directory\_get\_child\_directories** (notmuch\_directory\_t \*directory)\ Get a notmuch\_filenames\_t iterator listing all the filenames of sub-directories in the database within the given directory. **notmuch\_status\_t** **notmuch\_directory\_delete** (notmuch\_directory\_t \*directory)\ Delete directory document from the database, and destroy the notmuch\_directory\_t object. void **notmuch\_directory\_destroy** (notmuch\_directory\_t \*directory)\ Destroy a notmuch\_directory\_t object. **notmuch\_bool\_t** **notmuch\_filenames\_valid** (notmuch\_filenames\_t \*filenames)\ Is the given 'filenames' iterator pointing at a valid filename. const char \* **notmuch\_filenames\_get** (notmuch\_filenames\_t \*filenames)\ Get the current filename from 'filenames' as a string. void **notmuch\_filenames\_move\_to\_next** (notmuch\_filenames\_t \*filenames)\ Move the 'filenames' iterator to the next filename. void **notmuch\_filenames\_destroy** (notmuch\_filenames\_t \*filenames)\ Destroy a notmuch\_filenames\_t object. **notmuch\_status\_t** **notmuch\_database\_set\_config** (notmuch\_database\_t \*db, const char \*key, const char \*value)\ set config 'key' to 'value' **notmuch\_status\_t** **notmuch\_database\_get\_config** (notmuch\_database\_t \*db, const char \*key, char \*\*value)\ retrieve config item 'key', assign to 'value' **notmuch\_status\_t** **notmuch\_database\_get\_config\_list** (notmuch\_database\_t \*db, const char \*prefix, notmuch\_config\_list\_t \*\*out)\ Create an iterator for all config items with keys matching a given prefix. **notmuch\_bool\_t** **notmuch\_config\_list\_valid** (notmuch\_config\_list\_t \*config\_list)\ Is 'config\_list' iterator valid (i.e. const char \* **notmuch\_config\_list\_key** (notmuch\_config\_list\_t \*config\_list)\ return key for current config pair const char \* **notmuch\_config\_list\_value** (notmuch\_config\_list\_t \*config\_list)\ return 'value' for current config pair void **notmuch\_config\_list\_move\_to\_next** (notmuch\_config\_list\_t \*config\_list)\ move 'config\_list' iterator to the next pair void **notmuch\_config\_list\_destroy** (notmuch\_config\_list\_t \*config\_list)\ free any resources held by 'config\_list' const char \* **notmuch\_config\_get** (notmuch\_database\_t \*notmuch, **notmuch\_config\_key\_t** key)\ get a configuration value from an open database. **notmuch\_status\_t** **notmuch\_config\_set** (notmuch\_database\_t \*notmuch, **notmuch\_config\_key\_t** key, const char \*val)\ set a configuration value from in an open database. notmuch\_config\_values\_t \* **notmuch\_config\_get\_values** (notmuch\_database\_t \*notmuch, **notmuch\_config\_key\_t** key)\ Returns an iterator for a ';'-delimited list of configuration values. notmuch\_config\_values\_t \* **notmuch\_config\_get\_values\_string** (notmuch\_database\_t \*notmuch, const char \*key)\ Returns an iterator for a ';'-delimited list of configuration values. **notmuch\_bool\_t** **notmuch\_config\_values\_valid** (notmuch\_config\_values\_t \*values)\ Is the given 'config\_values' iterator pointing at a valid element. const char \* **notmuch\_config\_values\_get** (notmuch\_config\_values\_t \*values)\ Get the current value from the 'values' iterator. void **notmuch\_config\_values\_move\_to\_next** (notmuch\_config\_values\_t \*values)\ Move the 'values' iterator to the next element. void **notmuch\_config\_values\_start** (notmuch\_config\_values\_t \*values)\ reset the 'values' iterator to the first element void **notmuch\_config\_values\_destroy** (notmuch\_config\_values\_t \*values)\ Destroy a config values iterator, along with any associated resources. notmuch\_config\_pairs\_t \* **notmuch\_config\_get\_pairs** (notmuch\_database\_t \*notmuch, const char \*prefix)\ Returns an iterator for a (key, value) configuration pairs. **notmuch\_bool\_t** **notmuch\_config\_pairs\_valid** (notmuch\_config\_pairs\_t \*pairs)\ Is the given 'config\_pairs' iterator pointing at a valid element. void **notmuch\_config\_pairs\_move\_to\_next** (notmuch\_config\_pairs\_t \*pairs)\ Move the 'config\_pairs' iterator to the next element. const char \* **notmuch\_config\_pairs\_key** (notmuch\_config\_pairs\_t \*pairs)\ Get the current key from the 'config\_pairs' iterator. const char \* **notmuch\_config\_pairs\_value** (notmuch\_config\_pairs\_t \*pairs)\ Get the current value from the 'config\_pairs' iterator. void **notmuch\_config\_pairs\_destroy** (notmuch\_config\_pairs\_t \*pairs)\ Destroy a config\_pairs iterator, along with any associated resources. **notmuch\_status\_t** **notmuch\_config\_get\_bool** (notmuch\_database\_t \*notmuch, **notmuch\_config\_key\_t** key, **notmuch\_bool\_t** \*val)\ get a configuration value from an open database as Boolean const char \* **notmuch\_config\_path** (notmuch\_database\_t \*notmuch)\ return the path of the config file loaded, if any notmuch\_indexopts\_t \* **notmuch\_database\_get\_default\_indexopts** (notmuch\_database\_t \*db)\ get the current default indexing options for a given database. **notmuch\_status\_t** **notmuch\_indexopts\_set\_decrypt\_policy** (notmuch\_indexopts\_t \*indexopts, **notmuch\_decryption\_policy\_t** decrypt\_policy)\ Specify whether to decrypt encrypted parts while indexing. **notmuch\_decryption\_policy\_t** **notmuch\_indexopts\_get\_decrypt\_policy** (const notmuch\_indexopts\_t \*indexopts)\ Return whether to decrypt encrypted parts while indexing. void **notmuch\_indexopts\_destroy** (notmuch\_indexopts\_t \*options)\ Destroy a notmuch\_indexopts\_t object. **notmuch\_bool\_t** **notmuch\_built\_with** (const char \*name)\ interrogate the library for compile time features ### Message Properties This interface provides the ability to attach arbitrary (key,value) string pairs to a message, to remove such pairs, and to iterate over them. The caller should take some care as to what keys they add or delete values for, as other subsystems or extensions may depend on these properties. Please see [notmuch-properties(7)](/notmuch-properties/7.md) for more details about specific properties and conventions around their use. typedef struct \_notmuch\_string\_map\_iterator **notmuch\_message\_properties\_t**\ Opaque message property iterator. **notmuch\_status\_t** **notmuch\_message\_get\_property** (notmuch\_message\_t \*message, const char \*key, const char \*\*value)\ Retrieve the value for a single property key. **notmuch\_status\_t** **notmuch\_message\_add\_property** (notmuch\_message\_t \*message, const char \*key, const char \*value)\ Add a (key,value) pair to a message. **notmuch\_status\_t** **notmuch\_message\_remove\_property** (notmuch\_message\_t \*message, const char \*key, const char \*value)\ Remove a (key,value) pair from a message. **notmuch\_status\_t** **notmuch\_message\_remove\_all\_properties** (notmuch\_message\_t \*message, const char \*key)\ Remove all (key,value) pairs from the given message. **notmuch\_status\_t** **notmuch\_message\_remove\_all\_properties\_with\_prefix** (notmuch\_message\_t \*message, const char \*prefix)\ Remove all (prefix\*,value) pairs from the given message. **notmuch\_message\_properties\_t** \* **notmuch\_message\_get\_properties** (notmuch\_message\_t \*message, const char \*key, **notmuch\_bool\_t** exact)\ Get the properties for *message*, returning a **notmuch\_message\_properties\_t** object which can be used to iterate over all properties. **notmuch\_status\_t** **notmuch\_message\_count\_properties** (notmuch\_message\_t \*message, const char \*key, unsigned int \*count)\ Return the number of properties named *key"*belonging*to*the*specific*message. **notmuch\_bool\_t** **notmuch\_message\_properties\_valid** (**notmuch\_message\_properties\_t** \*properties)\ Is the given *properties* iterator pointing at a valid (key,value) pair. void **notmuch\_message\_properties\_move\_to\_next** (**notmuch\_message\_properties\_t** \*properties)\ Move the *properties* iterator to the next (key,value) pair. const char \* **notmuch\_message\_properties\_key** (**notmuch\_message\_properties\_t** \*properties)\ Return the key from the current (key,value) pair. const char \* **notmuch\_message\_properties\_value** (**notmuch\_message\_properties\_t** \*properties)\ Return the value from the current (key,value) pair. void **notmuch\_message\_properties\_destroy** (**notmuch\_message\_properties\_t** \*properties)\ Destroy a **notmuch\_message\_properties\_t** object. ## Detailed Description Not much of an email library, (just index and search). ## Macro Definition Documentation ### #define LIBNOTMUCH\_CHECK\_VERSION( major, minor, micro) **Value:** ``` (LIBNOTMUCH_MAJOR_VERSION > (major) || \ (LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION > (minor)) || \ (LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION == (minor) && \ LIBNOTMUCH_MICRO_VERSION >= (micro))) ``` Check the version of the notmuch library being compiled against. Return true if the library being compiled against is of the specified version or above. For example: ``` #if LIBNOTMUCH_CHECK_VERSION(3, 1, 0) (code requiring libnotmuch 3.1.0 or above) #endif ``` LIBNOTMUCH\_CHECK\_VERSION has been defined since version 3.1.0; to check for versions prior to that, use: ``` #if !defined(NOTMUCH_CHECK_VERSION) (code requiring libnotmuch prior to 3.1.0) #endif ``` ## Enumeration Type Documentation ### enum notmuch\_status\_t Status codes used for the return values of most functions. A zero value (NOTMUCH\_STATUS\_SUCCESS) indicates that the function completed without error. Any other value indicates an error. **Enumerator** - ***NOTMUCH\_STATUS\_SUCCESS*** No error occurred. - ***NOTMUCH\_STATUS\_OUT\_OF\_MEMORY*** Out of memory. - ***NOTMUCH\_STATUS\_READ\_ONLY\_DATABASE*** An attempt was made to write to a database opened in read-only mode. - ***NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION*** A Xapian exception occurred. - ***NOTMUCH\_STATUS\_FILE\_ERROR*** An error occurred trying to read or write to a file (this could be file not found, permission denied, etc.). - ***NOTMUCH\_STATUS\_FILE\_NOT\_EMAIL*** A file was presented that doesn't appear to be an email message. - ***NOTMUCH\_STATUS\_DUPLICATE\_MESSAGE\_ID*** A file contains a message ID that is identical to a message already in the database. - ***NOTMUCH\_STATUS\_NULL\_POINTER*** The user erroneously passed a NULL pointer to a notmuch function. - ***NOTMUCH\_STATUS\_TAG\_TOO\_LONG*** A tag value is too long (exceeds NOTMUCH\_TAG\_MAX). - ***NOTMUCH\_STATUS\_UNBALANCED\_FREEZE\_THAW*** The notmuch\_message\_thaw function has been called more times than notmuch\_message\_freeze. - ***NOTMUCH\_STATUS\_UNBALANCED\_ATOMIC*** notmuch\_database\_end\_atomic has been called more times than notmuch\_database\_begin\_atomic. - ***NOTMUCH\_STATUS\_UNSUPPORTED\_OPERATION*** The operation is not supported. - ***NOTMUCH\_STATUS\_UPGRADE\_REQUIRED*** The operation requires a database upgrade. - ***NOTMUCH\_STATUS\_PATH\_ERROR*** There is a problem with the proposed path, e.g. a relative path passed to a function expecting an absolute path. - ***NOTMUCH\_STATUS\_IGNORED*** The requested operation was ignored. Depending on the function, this may not be an actual error. - ***NOTMUCH\_STATUS\_ILLEGAL\_ARGUMENT*** One of the arguments violates the preconditions for the function, in a way not covered by a more specific argument. - ***NOTMUCH\_STATUS\_MALFORMED\_CRYPTO\_PROTOCOL*** A MIME object claimed to have cryptographic protection which notmuch tried to handle, but the protocol was not specified in an intelligible way. - ***NOTMUCH\_STATUS\_FAILED\_CRYPTO\_CONTEXT\_CREATION*** Notmuch attempted to do crypto processing, but could not initialize the engine needed to do so. - ***NOTMUCH\_STATUS\_UNKNOWN\_CRYPTO\_PROTOCOL*** A MIME object claimed to have cryptographic protection, and notmuch attempted to process it, but the specific protocol was something that notmuch doesn't know how to handle. - ***NOTMUCH\_STATUS\_NO\_CONFIG*** Unable to load a config file. - ***NOTMUCH\_STATUS\_NO\_DATABASE*** Unable to load a database. - ***NOTMUCH\_STATUS\_DATABASE\_EXISTS*** Database exists, so not (re)-created. - ***NOTMUCH\_STATUS\_BAD\_QUERY\_SYNTAX*** Syntax error in query. - ***NOTMUCH\_STATUS\_NO\_MAIL\_ROOT*** No mail root could be deduced from parameters and environment. - ***NOTMUCH\_STATUS\_CLOSED\_DATABASE*** Database is not fully opened, or has been closed. - ***NOTMUCH\_STATUS\_ITERATOR\_EXHAUSTED*** The iterator being examined has been exhausted and contains no more items. - ***NOTMUCH\_STATUS\_OPERATION\_INVALIDATED*** An operation that was being performed on the database has been invalidated while in progress, and must be re-executed. This will typically happen while iterating over query results and the underlying Xapian database is modified by another process so that the currently open version cannot be read anymore. - ***NOTMUCH\_STATUS\_LAST\_STATUS*** Not an actual status value. Just a way to find out how many valid status values there are. ### enum notmuch\_database\_mode\_t Database open mode for notmuch\_database\_open. **Enumerator** - ***NOTMUCH\_DATABASE\_MODE\_READ\_ONLY*** Open database for reading only. - ***NOTMUCH\_DATABASE\_MODE\_READ\_WRITE*** Open database for reading and writing. ### enum notmuch\_sort\_t Sort values for notmuch\_query\_set\_sort. **Enumerator** - ***NOTMUCH\_SORT\_OLDEST\_FIRST*** Oldest first. - ***NOTMUCH\_SORT\_NEWEST\_FIRST*** Newest first. - ***NOTMUCH\_SORT\_MESSAGE\_ID*** Sort by message-id. - ***NOTMUCH\_SORT\_UNSORTED*** Do not sort. ### enum notmuch\_exclude\_t 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. ### enum notmuch\_decryption\_policy\_t Stating a policy about how to decrypt messages. See index.decrypt in [notmuch-config(1)](/notmuch-config/1.md) for more details. ## Function Documentation ### const char \* notmuch\_status\_to\_string (notmuch\_status\_t status) Get a string representation of a **notmuch\_status\_t** value. The result is read-only. ### notmuch\_status\_t notmuch\_database\_create (const char \* path, notmuch\_database\_t \*\* database) Create a new, empty notmuch database located at 'path'. The path should be a top-level directory to a collection of plain-text email messages (one message per file). This call will create a new ".notmuch" directory within 'path' where notmuch will store its data. After a successful call to notmuch\_database\_create, the returned database will be open so the caller should call notmuch\_database\_destroy when finished with it. 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\_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). Return value: NOTMUCH\_STATUS\_SUCCESS: Successfully created the database. NOTMUCH\_STATUS\_NULL\_POINTER: The given 'path' argument is NULL. NOTMUCH\_STATUS\_OUT\_OF\_MEMORY: Out of memory. NOTMUCH\_STATUS\_PATH\_ERROR: filename is too long NOTMUCH\_STATUS\_FILE\_ERROR: An error occurred trying to create the database file (such as permission denied, or file not found, etc.), or the database already exists. NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION: A Xapian exception occurred. ### notmuch\_status\_t notmuch\_database\_create\_verbose (const char \* path, notmuch\_database\_t \*\* database, char \*\* error\_message) Like notmuch\_database\_create, except optionally return an error message. This message is allocated by malloc and should be freed by the caller. ### notmuch\_status\_t notmuch\_database\_open (const char \* path, notmuch\_database\_mode\_t mode, notmuch\_database\_t \*\* database) Deprecated alias for notmuch\_database\_open\_with\_config with config\_path="" and error\_message=NULL. **Deprecated** Deprecated as of libnotmuch 5.4 (notmuch 0.32) ### notmuch\_status\_t notmuch\_database\_open\_verbose (const char \* path, notmuch\_database\_mode\_t mode, notmuch\_database\_t \*\* database, char \*\* error\_message) Deprecated alias for notmuch\_database\_open\_with\_config with config\_path="". **Deprecated** Deprecated as of libnotmuch 5.4 (notmuch 0.32) ### notmuch\_status\_t notmuch\_database\_open\_with\_config (const char \* database\_path, notmuch\_database\_mode\_t mode, const char \* config\_path, const char \* profile, notmuch\_database\_t \*\* database, char \*\* error\_message) Open an existing notmuch database located at 'database\_path', using configuration in 'config\_path'. **Parameters** *database\_path* Path to existing database. A notmuch database is a Xapian database containing appropriate metadata. The database should have been created at some time in the past, (not necessarily by this process), by calling notmuch\_database\_create. If 'database\_path' is NULL, use the location specified - • in the environment variable NOTMUCH\_DATABASE, if non-empty - • in a configuration file, located as described under 'config\_path' - • by $XDG\_DATA\_HOME/notmuch/$PROFILE where XDG\_DATA\_HOME defaults to "$HOME/.local/share" and PROFILE as as discussed in 'profile' If 'database\_path' is non-NULL, but does not appear to be a Xapian database, check for a directory '.notmuch/xapian' below 'database\_path' (this is the behavior of notmuch\_database\_open\_verbose pre-0.32). *mode* Mode to open database. Use one of **NOTMUCH\_DATABASE\_MODE\_READ\_WRITE** or **NOTMUCH\_DATABASE\_MODE\_READ\_ONLY** *config\_path* Path to config file. Config file is key-value, with mandatory sections. See *notmuch-config(5)* for more information. The key-value pair overrides the corresponding configuration data stored in the database (see *notmuch\_database\_get\_config*) If *config\_path* is NULL use the path specified - • in environment variable *NOTMUCH\_CONFIG*, if non-empty - • by *XDG\_CONFIG\_HOME*/notmuch/ where XDG\_CONFIG\_HOME defaults to "$HOME/.config". - • by $HOME/.notmuch-config If *config\_path* is "" (empty string) then do not open any configuration file. \ *profile* Name of profile (configuration/database variant). If non-NULL, append to the directory / file path determined for *config\_path* and *database\_path*. If NULL then use - • environment variable NOTMUCH\_PROFILE if defined, - • otherwise "default" for directories and "" (empty string) for paths. *database* Pointer to database object. May not be NULL. The caller should call notmuch\_database\_destroy when finished with this database. In case of any failure, this function returns an error status and sets \*database to NULL. *error\_message* If non-NULL, store error message from opening the database. Any such message is allocated by *[malloc(3)](/malloc/3.md)* and should be freed by the caller. **Return values** **NOTMUCH\_STATUS\_SUCCESS Successfully opened the database.**\ **NOTMUCH\_STATUS\_NULL\_POINTER The given** *database* **argument is NULL.**\ **NOTMUCH\_STATUS\_NO\_CONFIG No config file was found. Fatal.**\ **NOTMUCH\_STATUS\_OUT\_OF\_MEMORY Out of memory.**\ **NOTMUCH\_STATUS\_FILE\_ERROR An error occurred trying to open the database or config file (such as permission denied, or file not found, etc.), or the database version is unknown.**\ **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION A Xapian exception occurred.** **Since** **libnotmuch 5.4 (notmuch 0.32)** ### notmuch\_status\_t notmuch\_database\_load\_config (const char \* database\_path, const char \* config\_path, const char \* profile, notmuch\_database\_t \*\* database, char \*\* error\_message) **Loads configuration from config file, database, and/or defaults. For description of arguments,** **See also** **notmuch\_database\_open\_with\_config** **For errors other then NO\_DATABASE and NO\_CONFIG, \*database is set to NULL.** **Return values** **NOTMUCH\_STATUS\_SUCCESS Successfully loaded configuration.**\ **NOTMUCH\_STATUS\_NO\_CONFIG No config file was loaded. Not fatal.**\ **NOTMUCH\_STATUS\_NO\_DATABASE No config information was loaded from a database. Not fatal.**\ **NOTMUCH\_STATUS\_OUT\_OF\_MEMORY Out of memory.**\ **NOTMUCH\_STATUS\_FILE\_ERROR An error occurred trying to open the database or config file (such as permission denied, or file not found, etc.)**\ **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION A Xapian exception occurred.** **Since** **libnotmuch 5.4 (notmuch 0.32)** ### notmuch\_status\_t notmuch\_database\_create\_with\_config (const char \* database\_path, const char \* config\_path, const char \* profile, notmuch\_database\_t \*\* database, char \*\* error\_message) **Create a new notmuch database located at 'database\_path', using configuration in 'config\_path'. For description of arguments,** **See also** **notmuch\_database\_open\_with\_config** **In case of any failure, this function returns an error status and sets \*database to NULL.** **Return values** **NOTMUCH\_STATUS\_SUCCESS Successfully created the database.**\ **NOTMUCH\_STATUS\_DATABASE\_EXISTS Database already exists, not created**\ **NOTMUCH\_STATUS\_OUT\_OF\_MEMORY Out of memory.**\ **NOTMUCH\_STATUS\_FILE\_ERROR An error occurred trying to open the database or config file (such as permission denied, or file not found, etc.)**\ **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION A Xapian exception occurred.** **Since** **libnotmuch 5.4 (notmuch 0.32)** ### notmuch\_status\_t notmuch\_database\_close (notmuch\_database\_t \* database) **Commit changes and close the given notmuch database. After notmuch\_database\_close has been called, calls to other functions on objects derived from this database may either behave as if the database had not been closed (e.g., if the required data has been cached) or may fail with a NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION. The only further operation permitted on the database itself is to call notmuch\_database\_destroy.** **notmuch\_database\_close can be called multiple times. Later calls have no effect.** **For writable databases, notmuch\_database\_close commits all changes to disk before closing the database, unless the caller is currently in an atomic section (there was a notmuch\_database\_begin\_atomic without a matching notmuch\_database\_end\_atomic). In this case changes since the last commit are discarded.** **See also** **notmuch\_database\_end\_atomic for more information.** **Return value:** **NOTMUCH\_STATUS\_SUCCESS: Successfully closed the database.** **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION: A Xapian exception occurred; the database has been closed but there are no guarantees the changes to the database, if any, have been flushed to disk.** ### notmuch\_status\_t notmuch\_database\_compact (const char \* path, const char \* backup\_path, notmuch\_compact\_status\_cb\_t status\_cb, void \* closure) **Compact a notmuch database, backing up the original database to the given path. The database will be opened with NOTMUCH\_DATABASE\_MODE\_READ\_WRITE during the compaction process to ensure no writes are made.** **If the optional callback function 'status\_cb' is non-NULL, it will be called with diagnostic and informational messages. The argument 'closure' is passed verbatim to any callback invoked.** ### notmuch\_status\_t notmuch\_database\_compact\_db (notmuch\_database\_t \* database, const char \* backup\_path, notmuch\_compact\_status\_cb\_t status\_cb, void \* closure) **Like notmuch\_database\_compact, but take an open database as a parameter.** **Since** **libnnotmuch 5.4 (notmuch 0.32)** ### notmuch\_status\_t notmuch\_database\_destroy (notmuch\_database\_t \* database) **Destroy the notmuch database, closing it if necessary and freeing all associated resources. Return value as in notmuch\_database\_close if the database was open; notmuch\_database\_destroy itself has no failure modes.** ### const char \* notmuch\_database\_get\_path (notmuch\_database\_t \* database) **Return the database path of the given database. The return value is a string owned by notmuch so should not be modified nor freed by the caller.** ### unsigned int notmuch\_database\_get\_version (notmuch\_database\_t \* database) **Return the database format version of the given database.** **Return values** *0* **on error** ### notmuch\_bool\_t notmuch\_database\_needs\_upgrade (notmuch\_database\_t \* database) **Can the database be upgraded to a newer database version? If this function returns TRUE, then the caller may call notmuch\_database\_upgrade to upgrade the database. If the caller does not upgrade an out-of-date database, then some functions may fail with NOTMUCH\_STATUS\_UPGRADE\_REQUIRED. This always returns FALSE for a read-only database because there's no way to upgrade a read-only database.** **Also returns FALSE if an error occurs accessing the database.** ### notmuch\_status\_t notmuch\_database\_upgrade (notmuch\_database\_t \* database, void(\* progress\_notify )(void \*closure, double progress), void \* closure) **Upgrade the current database to the latest supported version. This ensures that all current notmuch functionality will be available on the database. After opening a database in read-write mode, it is recommended that clients check if an upgrade is needed (notmuch\_database\_needs\_upgrade) and if so, upgrade with this function before making any modifications. If notmuch\_database\_needs\_upgrade returns FALSE, this will be a no-op.** **The optional progress\_notify callback can be used by the caller to provide progress indication to the user. If non-NULL it will be called periodically with 'progress' as a floating-point value in the range of \[0.0 .. 1.0\] indicating the progress made so far in the upgrade process. The argument 'closure' is passed verbatim to any callback invoked.** ### notmuch\_status\_t notmuch\_database\_begin\_atomic (notmuch\_database\_t \* notmuch) **Begin an atomic database operation. Any modifications performed between a successful begin and a notmuch\_database\_end\_atomic will be applied to the database atomically. Note that, unlike a typical database transaction, this only ensures atomicity, not durability; neither begin nor end necessarily flush modifications to disk.** **Atomic sections may be nested. begin\_atomic and end\_atomic must always be called in pairs.** **Return value:** **NOTMUCH\_STATUS\_SUCCESS: Successfully entered atomic section.** **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION: A Xapian exception occurred; atomic section not entered.** ### notmuch\_status\_t notmuch\_database\_end\_atomic (notmuch\_database\_t \* notmuch) **Indicate the end of an atomic database operation. If repeated (with matching notmuch\_database\_begin\_atomic) "database.autocommit" times, commit the the transaction and all previous (non-cancelled) transactions to the database.** **Return value:** **NOTMUCH\_STATUS\_SUCCESS: Successfully completed atomic section.** **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION: A Xapian exception occurred; atomic section not ended.** **NOTMUCH\_STATUS\_UNBALANCED\_ATOMIC: The database is not currently in an atomic section.** ### unsigned long notmuch\_database\_get\_revision (notmuch\_database\_t \* notmuch, const char \*\* uuid) **Return the committed database revision and UUID. The database revision number increases monotonically with each commit to the database. Hence, all messages and message changes committed to the database (that is, visible to readers) have a last modification revision \<= the committed database revision. Any messages committed in the future will be assigned a modification revision \> the committed database revision.** **The UUID is a NUL-terminated opaque string that uniquely identifies this database. Two revision numbers are only comparable if they have the same database UUID. The string 'uuid' is owned by notmuch and should not be freed or modified by the user.** ### notmuch\_status\_t notmuch\_database\_get\_directory (notmuch\_database\_t \* database, const char \* path, notmuch\_directory\_t \*\* directory) **Retrieve a directory object from the database for 'path'. Here, 'path' should be a path relative to the path of 'database' (see notmuch\_database\_get\_path), or else should be an absolute path with initial components that match the path of 'database'.** **If this directory object does not exist in the database, this returns NOTMUCH\_STATUS\_SUCCESS and sets \*directory to NULL.** **Otherwise the returned directory object is owned by the database and as such, will only be valid until notmuch\_database\_destroy is called.** **Return value:** **NOTMUCH\_STATUS\_SUCCESS: Successfully retrieved directory.** **NOTMUCH\_STATUS\_NULL\_POINTER: The given 'directory' argument is NULL.** **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION: A Xapian exception occurred; directory not retrieved.** **NOTMUCH\_STATUS\_UPGRADE\_REQUIRED: The caller must upgrade the database to use this function.** ### notmuch\_status\_t notmuch\_database\_index\_file (notmuch\_database\_t \* database, const char \* filename, notmuch\_indexopts\_t \* indexopts, notmuch\_message\_t \*\* 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 absolute filename with initial components that match the path of 'database'.** **The file should be a single mail message (not a multi-message mbox) that is expected to remain at its current location, (since the notmuch database will reference the filename, and will not copy the 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 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' will be initialized to a message object that can be used for things such as adding tags to the just-added message. The user should call notmuch\_message\_destroy when done with the message. On any failure '\*message' will be set to NULL.** **Return value:** **NOTMUCH\_STATUS\_SUCCESS: Message successfully added to database.** **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION: A Xapian exception occurred, message not added.** **NOTMUCH\_STATUS\_DUPLICATE\_MESSAGE\_ID: Message has the same message ID as another message already in the database. The new filename was successfully added to the message in the database (if not already present) and the existing message is returned.** **NOTMUCH\_STATUS\_FILE\_ERROR: an error occurred trying to open the file, (such as permission denied, or file not found, etc.). Nothing added to the database.** **NOTMUCH\_STATUS\_FILE\_NOT\_EMAIL: the contents of filename don't look like an email message. Nothing added to the database.** **NOTMUCH\_STATUS\_READ\_ONLY\_DATABASE: Database was opened in read-only mode so no message can be added.** **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\_add\_message (notmuch\_database\_t \* database, const char \* filename, 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\_status\_t notmuch\_database\_remove\_message (notmuch\_database\_t \* database, const char \* filename) **Remove a message filename from the given notmuch database. If the message has no more filenames, remove the message.** **If the same message (as determined by the message ID) is still available via other filenames, then the message will persist in the database for those filenames. When the last filename is removed for a particular message, the database content for that message will be entirely removed.** **Return value:** **NOTMUCH\_STATUS\_SUCCESS: The last filename was removed and the message was removed from the database.** **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION: A Xapian exception occurred, message not removed.** **NOTMUCH\_STATUS\_DUPLICATE\_MESSAGE\_ID: This filename was removed but the message persists in the database with at least one other filename.** **NOTMUCH\_STATUS\_READ\_ONLY\_DATABASE: Database was opened in read-only mode so no message can be removed.** **NOTMUCH\_STATUS\_UPGRADE\_REQUIRED: The caller must upgrade the database to use this function.** ### notmuch\_status\_t notmuch\_database\_find\_message (notmuch\_database\_t \* database, const char \* message\_id, notmuch\_message\_t \*\* message) **Find a message with the given message\_id. If a message with the given message\_id is found then, on successful return (NOTMUCH\_STATUS\_SUCCESS) '\*message' will be initialized to a message object. The caller should call notmuch\_message\_destroy when done with the message.** **On any failure or when the message is not found, this function initializes '\*message' to NULL. This means, when NOTMUCH\_STATUS\_SUCCESS is returned, the caller is supposed to check '\*message' for NULL to find out whether the message with the given message\_id was found.** **Return value:** **NOTMUCH\_STATUS\_SUCCESS: Successful return, check '\*message'.** **NOTMUCH\_STATUS\_NULL\_POINTER: The given 'message' argument is NULL** **NOTMUCH\_STATUS\_OUT\_OF\_MEMORY: Out of memory, creating message object** **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION: A Xapian exception occurred** ### notmuch\_status\_t notmuch\_database\_find\_message\_by\_filename (notmuch\_database\_t \* notmuch, const char \* filename, notmuch\_message\_t \*\* message) **Find a message with the given filename. If the database contains a message with the given filename then, on successful return (NOTMUCH\_STATUS\_SUCCESS) '\*message' will be initialized to a message object. The caller should call notmuch\_message\_destroy when done with the message.** **On any failure or when the message is not found, this function initializes '\*message' to NULL. This means, when NOTMUCH\_STATUS\_SUCCESS is returned, the caller is supposed to check '\*message' for NULL to find out whether the message with the given filename is found.** **Return value:** **NOTMUCH\_STATUS\_SUCCESS: Successful return, check '\*message'** **NOTMUCH\_STATUS\_NULL\_POINTER: The given 'message' argument is NULL** **NOTMUCH\_STATUS\_OUT\_OF\_MEMORY: Out of memory, creating the message object** **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION: A Xapian exception occurred** **NOTMUCH\_STATUS\_UPGRADE\_REQUIRED: The caller must upgrade the database to use this function.** ### notmuch\_tags\_t \* notmuch\_database\_get\_all\_tags (notmuch\_database\_t \* db) **Return a list of all tags found in the database. This function creates a list of all tags found in the database. The resulting list contains all tags from all messages found in the database.** **On error this function returns NULL.** ### notmuch\_status\_t notmuch\_database\_reopen (notmuch\_database\_t \* db, notmuch\_database\_mode\_t mode) **Reopen an open notmuch database.** **Parameters** *db* **open notmuch database** \ *mode* **mode (read only or read-write) for reopened database.** **Return values** **NOTMUCH\_STATUS\_SUCCESS** \ **NOTMUCH\_STATUS\_ILLEGAL\_ARGUMENT The passed database was not open.** \ **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION A Xapian exception occured** ### notmuch\_query\_t \* notmuch\_query\_create (notmuch\_database\_t \* database, const char \* query\_string) **Create a new query for 'database'. Here, 'database' should be an open database, (see notmuch\_database\_open and notmuch\_database\_create).** **For the query string, we'll document the syntax here more completely in the future, but it's likely to be a specialized version of the general Xapian query syntax:** **https://xapian.org/docs/queryparser.html** **As a special case, passing either a length-zero string, (that is ""), or a string consisting of a single asterisk (that is "\*"), will result in a query that returns all messages in the database.** **See notmuch\_query\_set\_sort for controlling the order of results. See notmuch\_query\_search\_messages and notmuch\_query\_search\_threads to actually execute the query.** **User should call notmuch\_query\_destroy when finished with this query.** **Will return NULL if insufficient memory is available.** ### const char \* notmuch\_query\_get\_query\_string (const notmuch\_query\_t \* query) **Return the query\_string of this query. See notmuch\_query\_create.** ### notmuch\_database\_t \* notmuch\_query\_get\_database (const notmuch\_query\_t \* query) **Return the notmuch database of this query. See notmuch\_query\_create.** ### void notmuch\_query\_set\_omit\_excluded (notmuch\_query\_t \* query, notmuch\_exclude\_t omit\_excluded) **Specify whether to omit excluded results or simply flag them. By default, this is set to TRUE.** **If set to TRUE or ALL, notmuch\_query\_search\_messages will omit excluded messages from the results, and notmuch\_query\_search\_threads will omit threads that match only in excluded messages. If set to TRUE, notmuch\_query\_search\_threads will include all messages in threads that 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, notmuch\_query\_search\_threads is very much faster when omitting excluded messages as it does not need to construct the threads that only match in excluded messages.** ### notmuch\_sort\_t notmuch\_query\_get\_sort (const notmuch\_query\_t \* query) **Return the sort specified for this query. See notmuch\_query\_set\_sort.** ### notmuch\_status\_t notmuch\_query\_add\_tag\_exclude (notmuch\_query\_t \* query, const char \* tag) **Add a tag that will be excluded from the query results by default. This exclusion will be ignored if this tag appears explicitly in the query.** **Returns** **NOTMUCH\_STATUS\_SUCCESS: excluded was added successfully.** **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION: a Xapian exception occurred. Most likely a problem lazily parsing the query string.** **NOTMUCH\_STATUS\_IGNORED: tag is explicitly present in the query, so not excluded.** ### notmuch\_status\_t notmuch\_query\_search\_threads (notmuch\_query\_t \* query, notmuch\_threads\_t \*\* out) **Execute a query for threads, returning a notmuch\_threads\_t object which can be used to iterate over the results. The returned threads object is owned by the query and as such, will only be valid until notmuch\_query\_destroy.** **Typical usage might be:** ``` notmuch_query_t *query; notmuch_threads_t *threads; notmuch_thread_t *thread; notmuch_status_t stat; query = notmuch_query_create (database, query_string); for (stat = notmuch_query_search_threads (query, &threads); stat == NOTMUCH_STATUS_SUCCESS && ! notmuch_threads_status (threads); notmuch_threads_move_to_next (threads)) { thread = notmuch_threads_get (threads); .... notmuch_thread_destroy (thread); } notmuch_query_destroy (query); ``` **Note: If you are finished with a thread before its containing query, you can call notmuch\_thread\_destroy to clean up some memory sooner (as in the above example). Otherwise, if your thread objects are long-lived, then you don't need to call notmuch\_thread\_destroy and all the memory will still be reclaimed when the query is destroyed.** **Note that there's no explicit destructor needed for the notmuch\_threads\_t object. (For consistency, we do provide a notmuch\_threads\_destroy function, but there's no good reason to call it if the query is about to be destroyed).** **Since** **libnotmuch 5.0 (notmuch 0.25)** ### notmuch\_status\_t notmuch\_query\_search\_threads\_st (notmuch\_query\_t \* query, notmuch\_threads\_t \*\* out) **Deprecated alias for notmuch\_query\_search\_threads.** **Deprecated** **Deprecated as of libnotmuch 5 (notmuch 0.25). Please use notmuch\_query\_search\_threads instead.** ### notmuch\_status\_t notmuch\_query\_search\_messages (notmuch\_query\_t \* query, notmuch\_messages\_t \*\* out) **Execute a query for messages, returning a notmuch\_messages\_t object which can be used to iterate over the results. The returned messages object is owned by the query and as such, will only be valid until notmuch\_query\_destroy.** **Typical usage might be:** ``` notmuch_query_t *query; notmuch_messages_t *messages; notmuch_message_t *message; query = notmuch_query_create (database, query_string); if (notmuch_query_search_messages (query, &messages) != NOTMUCH_STATUS_SUCCESS) return EXIT_FAILURE; for (; ! notmuch_messages_status (messages); notmuch_messages_move_to_next (messages)) { message = notmuch_messages_get (messages); .... notmuch_message_destroy (message); } if (notmuch_messages_status (messages) != NOTMUCH_STATUS_ITERATOR_EXHAUSTED) return EXIT_FAILURE; notmuch_query_destroy (query); ``` **Note: If you are finished with a message before its containing query, you can call notmuch\_message\_destroy to clean up some memory sooner (as in the above example). Otherwise, if your message objects are long-lived, then you don't need to call notmuch\_message\_destroy and all the memory will still be reclaimed when the query is destroyed.** **Note that there's no explicit destructor needed for the notmuch\_messages\_t object. (For consistency, we do provide a notmuch\_messages\_destroy function, but there's no good reason to call it if the query is about to be destroyed).** **If a Xapian exception occurs this function will return NULL.** **Since** **libnotmuch 5 (notmuch 0.25)** ### notmuch\_status\_t notmuch\_query\_search\_messages\_st (notmuch\_query\_t \* query, notmuch\_messages\_t \*\* out) **Deprecated alias for notmuch\_query\_search\_messages.** **Deprecated** **Deprecated as of libnotmuch 5 (notmuch 0.25). Please use notmuch\_query\_search\_messages instead.** ### void notmuch\_query\_destroy (notmuch\_query\_t \* query) **Destroy a notmuch\_query\_t along with any associated resources. This will in turn destroy any notmuch\_threads\_t and notmuch\_messages\_t objects generated by this query, (and in turn any notmuch\_thread\_t and notmuch\_message\_t objects generated from those results, etc.), if such objects haven't already been destroyed.** ### notmuch\_bool\_t notmuch\_threads\_valid (notmuch\_threads\_t \* threads) **Is the given 'threads' iterator pointing at a valid thread. When this function returns TRUE, notmuch\_threads\_get will return a valid object. Whereas when this function returns FALSE, notmuch\_threads\_get will return NULL.** **If passed a NULL pointer, this function returns FALSE** **See the documentation of notmuch\_query\_search\_threads for example code showing how to iterate over a notmuch\_threads\_t object.** **Note that an iterator may become invalid either due to getting exhausted or due to a runtime error. Use notmuch\_threads\_status to distinguish between those cases.** ### notmuch\_status\_t notmuch\_threads\_status (notmuch\_threads\_t \* threads) **Get the status of the given 'threads' iterator. Return value:** **Return values** **NOTMUCH\_STATUS\_SUCCESS The iterator is valid; notmuch\_threads\_get may return a valid object**\ **NOTMUCH\_STATUS\_ITERATOR\_EXHAUSTED All items have been read**\ **NOTMUCH\_STATUS\_OUT\_OF\_MEMORY Iteration failed to allocate memory**\ **NOTMUCH\_STATUS\_OPERATION\_INVALIDATED Iteration was invalidated by the database. Re-open the database and try again.** **See the documentation of notmuch\_query\_search\_threads for example code showing how to iterate over a notmuch\_threads\_t object.** ### notmuch\_thread\_t \* notmuch\_threads\_get (notmuch\_threads\_t \* threads) **Get the current thread from 'threads' as a notmuch\_thread\_t. Note: The returned thread belongs to 'threads' and has a lifetime identical to it (and the query to which it belongs).** **See the documentation of notmuch\_query\_search\_threads for example code showing how to iterate over a notmuch\_threads\_t object.** **If an out-of-memory situation occurs, this function will return NULL.** ### void notmuch\_threads\_move\_to\_next (notmuch\_threads\_t \* threads) **Move the 'threads' iterator to the next thread. If 'threads' is already pointing at the last thread then the iterator will be moved to a point just beyond that last thread, (where notmuch\_threads\_status will return NOTMUCH\_STATUS\_ITERATOR\_EXHAUSTED and notmuch\_threads\_get will return NULL).** **See the documentation of notmuch\_query\_search\_threads for example code showing how to iterate over a notmuch\_threads\_t object.** ### void notmuch\_threads\_destroy (notmuch\_threads\_t \* threads) **Destroy a notmuch\_threads\_t object. It's not strictly necessary to call this function. All memory from the notmuch\_threads\_t object will be reclaimed when the containing query object is destroyed.** ### notmuch\_status\_t notmuch\_query\_count\_messages (notmuch\_query\_t \* query, unsigned int \* count) **Return the number of messages matching a search. This function performs a search and returns the number of matching messages.** **Returns** **NOTMUCH\_STATUS\_SUCCESS: query completed successfully.** **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION: a Xapian exception occurred. The value of \*count is not defined.** **Since** **libnotmuch 5 (notmuch 0.25)** ### notmuch\_status\_t notmuch\_query\_count\_messages\_st (notmuch\_query\_t \* query, unsigned int \* count) **Deprecated alias for notmuch\_query\_count\_messages.** **Deprecated** **Deprecated since libnotmuch 5.0 (notmuch 0.25). Please use notmuch\_query\_count\_messages instead.** ### notmuch\_status\_t notmuch\_query\_count\_threads (notmuch\_query\_t \* query, unsigned \* count) **Return the number of threads matching a search. This function performs a search and returns the number of unique thread IDs in the matching messages. This is the same as number of threads matching a search.** **Note that this is a significantly heavier operation than notmuch\_query\_count\_messages{\_st}().** **Returns** **NOTMUCH\_STATUS\_OUT\_OF\_MEMORY: Memory allocation failed. The value of \*count is not defined** **NOTMUCH\_STATUS\_SUCCESS: query completed successfully.** **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION: a Xapian exception occurred. The value of \*count is not defined.** **Since** **libnotmuch 5 (notmuch 0.25)** ### notmuch\_status\_t notmuch\_query\_count\_threads\_st (notmuch\_query\_t \* query, unsigned \* count) **Deprecated alias for notmuch\_query\_count\_threads.** **Deprecated** **Deprecated as of libnotmuch 5.0 (notmuch 0.25). Please use notmuch\_query\_count\_threads\_st instead.** ### const char \* notmuch\_thread\_get\_thread\_id (notmuch\_thread\_t \* thread) **Get the thread ID of 'thread'. The returned string belongs to 'thread' and as such, should not be modified by the caller and will only be valid for as long as the thread is valid, (which is until notmuch\_thread\_destroy or until the query from which it derived is destroyed).** ### int notmuch\_thread\_get\_total\_messages (notmuch\_thread\_t \* thread) **Get the total number of messages in 'thread'. This count consists of all messages in the database belonging to this thread. Contrast with notmuch\_thread\_get\_matched\_messages() .** ### int notmuch\_thread\_get\_total\_files (notmuch\_thread\_t \* thread) **Get the total number of files in 'thread'. This sums notmuch\_message\_count\_files over all messages in the thread** **Returns** **Non-negative integer** **Since** **libnotmuch 5.0 (notmuch 0.25)** ### notmuch\_messages\_t \* notmuch\_thread\_get\_toplevel\_messages (notmuch\_thread\_t \* thread) **Get a notmuch\_messages\_t iterator for the top-level messages in 'thread' in oldest-first order. This iterator will not necessarily iterate over all of the messages in the thread. It will only iterate over the messages in the thread which are not replies to other messages in the thread.** **The returned list will be destroyed when the thread is destroyed.** ### notmuch\_messages\_t \* notmuch\_thread\_get\_messages (notmuch\_thread\_t \* thread) **Get a notmuch\_thread\_t iterator for all messages in 'thread' in oldest-first order. The returned list will be destroyed when the thread is destroyed.** ### int notmuch\_thread\_get\_matched\_messages (notmuch\_thread\_t \* thread) **Get the number of messages in 'thread' that matched the search. This count includes only the messages in this thread that were matched by the search from which the thread was created and were not excluded by any exclude tags passed in with the query (see notmuch\_query\_add\_tag\_exclude). Contrast with notmuch\_thread\_get\_total\_messages() .** ### const char \* notmuch\_thread\_get\_authors (notmuch\_thread\_t \* thread) **Get the authors of 'thread' as a UTF-8 string. The returned string is a comma-separated list of the names of the authors of mail messages in the query results that belong to this thread.** **The string contains authors of messages matching the query first, then non-matched authors (with the two groups separated by '\|'). Within each group, authors are ordered by date.** **The returned string belongs to 'thread' and as such, should not be modified by the caller and will only be valid for as long as the thread is valid, (which is until notmuch\_thread\_destroy or until the query from which it derived is destroyed).** ### const char \* notmuch\_thread\_get\_subject (notmuch\_thread\_t \* thread) **Get the subject of 'thread' as a UTF-8 string. The subject is taken from the first message (according to the query order---see notmuch\_query\_set\_sort) in the query results that belongs to this thread.** **The returned string belongs to 'thread' and as such, should not be modified by the caller and will only be valid for as long as the thread is valid, (which is until notmuch\_thread\_destroy or until the query from which it derived is destroyed).** ### notmuch\_tags\_t \* notmuch\_thread\_get\_tags (notmuch\_thread\_t \* thread) **Get the tags for 'thread', returning a notmuch\_tags\_t object which can be used to iterate over all tags. Note: In the Notmuch database, tags are stored on individual messages, not on threads. So the tags returned here will be all tags of the messages which matched the search and which belong to this thread.** **The tags object is owned by the thread and as such, will only be valid for as long as the thread is valid, (for example, until notmuch\_thread\_destroy or until the query from which it derived is destroyed).** **Typical usage might be:** ``` notmuch_thread_t *thread; notmuch_tags_t *tags; const char *tag; thread = notmuch_threads_get (threads); for (tags = notmuch_thread_get_tags (thread); notmuch_tags_valid (tags); notmuch_tags_move_to_next (tags)) { tag = notmuch_tags_get (tags); .... } notmuch_thread_destroy (thread); ``` **Note that there's no explicit destructor needed for the notmuch\_tags\_t object. (For consistency, we do provide a notmuch\_tags\_destroy function, but there's no good reason to call it if the message is about to be destroyed).** ### notmuch\_bool\_t notmuch\_messages\_valid (notmuch\_messages\_t \* messages) **Is the given 'messages' iterator pointing at a valid message. When this function returns TRUE, notmuch\_messages\_get will return a valid object. Whereas when this function returns FALSE, notmuch\_messages\_get will return NULL.** **See the documentation of notmuch\_query\_search\_messages for example code showing how to iterate over a notmuch\_messages\_t object.** **Note that an iterator may become invalid either due to getting exhausted or due to a runtime error. Use notmuch\_messages\_status to distinguish between those cases.** ### notmuch\_status\_t notmuch\_messages\_status (notmuch\_messages\_t \* messages) **Get the status of the given 'messages' iterator. Return value:** **NOTMUCH\_STATUS\_SUCCESS: The iterator is valid; notmuch\_messages\_get will return a valid object** **NOTMUCH\_STATUS\_ITERATOR\_EXHAUSTED: All items have been read** **NOTMUCH\_STATUS\_OUT\_OF\_MEMORY: Iteration failed to allocate memory** **NOTMUCH\_STATUS\_OPERATION\_INVALIDATED: Iteration was invalidated by the database. Re-open the database and try again.** **See the documentation of notmuch\_query\_search\_messages for example code showing how to iterate over a notmuch\_messages\_t object.** ### notmuch\_message\_t \* notmuch\_messages\_get (notmuch\_messages\_t \* messages) **Get the current message from 'messages' as a notmuch\_message\_t. Note: The returned message belongs to 'messages' and has a lifetime identical to it (and the query to which it belongs).** **See the documentation of notmuch\_query\_search\_messages for example code showing how to iterate over a notmuch\_messages\_t object.** **If an out-of-memory situation occurs, this function will return NULL.** ### void notmuch\_messages\_move\_to\_next (notmuch\_messages\_t \* messages) **Move the 'messages' iterator to the next message. If 'messages' is already pointing at the last message then the iterator will be moved to a point just beyond that last message, (where notmuch\_messages\_status will return NOTMUCH\_STATUS\_ITERATOR\_EXHAUSTED and notmuch\_messages\_get will return NULL).** **See the documentation of notmuch\_query\_search\_messages for example code showing how to iterate over a notmuch\_messages\_t object.** ### void notmuch\_messages\_destroy (notmuch\_messages\_t \* messages) **Destroy a notmuch\_messages\_t object. It's not strictly necessary to call this function. All memory from the notmuch\_messages\_t object will be reclaimed when the containing query object is destroyed.** ### notmuch\_tags\_t \* notmuch\_messages\_collect\_tags (notmuch\_messages\_t \* messages) **Return a list of tags from all messages. The resulting list is guaranteed not to contain duplicated tags.** **WARNING: You can no longer iterate over messages after calling this function, because the iterator will point at the end of the list. We do not have a function to reset the iterator yet and the only way how you can iterate over the list again is to recreate the message list.** **The function returns NULL on error.** ### notmuch\_database\_t \* notmuch\_message\_get\_database (const notmuch\_message\_t \* message) **Get the database associated with this message.** **Since** **libnotmuch 5.2 (notmuch 0.27)** ### const char \* notmuch\_message\_get\_message\_id (notmuch\_message\_t \* message) **Get the message 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, (which is until the query from which it derived is destroyed).** **This function will return NULL if triggers an unhandled Xapian exception.** ### const char \* notmuch\_message\_get\_thread\_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 return NULL if triggers an unhandled Xapian exception.** ### notmuch\_messages\_t \* notmuch\_message\_get\_replies (notmuch\_message\_t \* message) **Get a notmuch\_messages\_t iterator for all of the replies to 'message'. Note: This call only makes sense if 'message' was ultimately obtained from a notmuch\_thread\_t object, (such as by coming directly from the result of calling notmuch\_thread\_get\_ toplevel\_messages or by any number of subsequent calls to notmuch\_message\_get\_replies).** **If 'message' was obtained through some non-thread means, (such as by a call to notmuch\_query\_search\_messages), then this function will return NULL.** **If there are no replies to 'message', this function will return NULL. (Note that notmuch\_messages\_status will accept that NULL value as legitimate, and simply return NOTMUCH\_STATUS\_ITERATOR\_EXHAUSTED for it.)** **This function also returns NULL if it triggers a Xapian exception.** **The returned list will be destroyed when the thread is destroyed.** ### int notmuch\_message\_count\_files (notmuch\_message\_t \* message) **Get the total number of files associated with a message.** **Returns** **Non-negative integer for file count.** **Negative integer for error.** **Since** **libnotmuch 5.0 (notmuch 0.25)** ### const char \* notmuch\_message\_get\_filename (notmuch\_message\_t \* message) **Get a filename for the email corresponding to 'message'. The returned filename is an absolute filename, (the initial component will match notmuch\_database\_get\_path() ).** **The returned string belongs to the message so should not be modified or freed by the caller (nor should it be referenced after the message is destroyed).** **Note: If this message corresponds to multiple files in the mail store, (that is, multiple files contain identical message IDs), this function will arbitrarily return a single one of those filenames. See notmuch\_message\_get\_filenames for returning the complete list of filenames.** **This function returns NULL if it triggers a Xapian exception.** ### notmuch\_filenames\_t \* notmuch\_message\_get\_filenames (notmuch\_message\_t \* message) **Get all filenames for the email corresponding to 'message'. Returns a notmuch\_filenames\_t iterator listing all the filenames associated with 'message'. These files may not have identical content, but each will have the identical Message-ID.** **Each filename in the iterator is an absolute filename, (the initial component will match notmuch\_database\_get\_path() ).** **This function returns NULL if it triggers a Xapian exception.** ### notmuch\_status\_t notmuch\_message\_reindex (notmuch\_message\_t \* message, notmuch\_indexopts\_t \* indexopts) **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\_index\_file)** **After reindexing, the user should discard the message object passed in here by calling notmuch\_message\_destroy, since it refers to the original message, not to the reindexed message.** ### notmuch\_bool\_t notmuch\_message\_get\_flag (notmuch\_message\_t \* message, notmuch\_message\_flag\_t flag) **Get a value of a flag for the email corresponding to 'message'. returns FALSE in case of errors.** **Deprecated** **Deprecated as of libnotmuch 5.3 (notmuch 0.31). Please use notmuch\_message\_get\_flag\_st instead.** ### notmuch\_status\_t notmuch\_message\_get\_flag\_st (notmuch\_message\_t \* message, notmuch\_message\_flag\_t flag, notmuch\_bool\_t \* is\_set) **Get a value of a flag for the email corresponding to 'message'.** **Parameters** *message* **a message object** \ *flag* **flag to check** \ *is\_set* **pointer to boolean to store flag value.** **Return values** **NOTMUCH\_STATUS\_SUCCESS** \ **NOTMUCH\_STATUS\_NULL\_POINTER is\_set is NULL** \ **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION Accessing the database triggered an exception.** **Since** **libnotmuch 5.3 (notmuch 0.31)** ### time\_t notmuch\_message\_get\_date (notmuch\_message\_t \* message) **Get the date of 'message' as a time\_t value. For the original textual representation of the Date header from the message call notmuch\_message\_get\_header() with a header value of "date".** **Returns 0 in case of error.** ### const char \* notmuch\_message\_get\_header (notmuch\_message\_t \* message, const char \* header) **Get the value of the specified header from 'message' as a UTF-8 string. 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 the message is destroyed).** **Returns an empty string ("") if the message does not contain a header line matching 'header'. Returns NULL if any error occurs.** ### notmuch\_tags\_t \* notmuch\_message\_get\_tags (notmuch\_message\_t \* message) **Get the tags for 'message', returning a notmuch\_tags\_t object which can be used to iterate over all tags. The tags 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_tags_t *tags; const char *tag; message = notmuch_database_find_message (database, message_id); for (tags = notmuch_message_get_tags (message); notmuch_tags_valid (tags); notmuch_tags_move_to_next (tags)) { tag = notmuch_tags_get (tags); .... } notmuch_message_destroy (message); ``` **Note that there's no explicit destructor needed for the notmuch\_tags\_t object. (For consistency, we do provide a notmuch\_tags\_destroy function, but there's no good reason to call it if the message is about to be destroyed).** ### notmuch\_status\_t notmuch\_message\_add\_tag (notmuch\_message\_t \* message, const char \* tag) **Add a tag to the given message. Return value:** **NOTMUCH\_STATUS\_SUCCESS: Tag successfully added to message** **NOTMUCH\_STATUS\_NULL\_POINTER: The 'tag' argument is NULL** **NOTMUCH\_STATUS\_TAG\_TOO\_LONG: The length of 'tag' is too long (exceeds NOTMUCH\_TAG\_MAX)** **NOTMUCH\_STATUS\_READ\_ONLY\_DATABASE: Database was opened in read-only mode so message cannot be modified.** ### notmuch\_status\_t notmuch\_message\_remove\_tag (notmuch\_message\_t \* message, const char \* tag) **Remove a tag from the given message. Return value:** **NOTMUCH\_STATUS\_SUCCESS: Tag successfully removed from message** **NOTMUCH\_STATUS\_NULL\_POINTER: The 'tag' argument is NULL** **NOTMUCH\_STATUS\_TAG\_TOO\_LONG: The length of 'tag' is too long (exceeds NOTMUCH\_TAG\_MAX)** **NOTMUCH\_STATUS\_READ\_ONLY\_DATABASE: Database was opened in read-only mode so message cannot be modified.** ### notmuch\_status\_t notmuch\_message\_remove\_all\_tags (notmuch\_message\_t \* message) **Remove all tags from the given message. See notmuch\_message\_freeze for an example showing how to safely replace tag values.** **Return values** **NOTMUCH\_STATUS\_READ\_ONLY\_DATABASE Database was opened in read-only mode so message cannot be modified.** \ **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION an exception was thrown accessing the database.** ### notmuch\_status\_t notmuch\_message\_maildir\_flags\_to\_tags (notmuch\_message\_t \* message) **Add/remove tags according to maildir flags in the message filename(s). This function examines the filenames of 'message' for maildir flags, and adds or removes tags on 'message' as follows when these flags are present:** ``` Flag Action if present ---- ----------------- 'D' Adds the "draft" tag to the message 'F' Adds the "flagged" tag to the message 'P' Adds the "passed" tag to the message 'R' Adds the "replied" tag to the message 'S' Removes the "unread" tag from the message ``` **For each flag that is not present, the opposite action (add/remove) is performed for the corresponding tags.** **Flags are identified as trailing components of the filename after a sequence of ":2,".** **If there are multiple filenames associated with this message, the flag is considered present if it appears in one or more filenames. (That is, the flags from the multiple filenames are combined with the logical OR operator.)** **A client can ensure that notmuch database tags remain synchronized with maildir flags by calling this function after each call to notmuch\_database\_index\_file. See also notmuch\_message\_tags\_to\_maildir\_flags for synchronizing tag changes back to maildir flags.** ### notmuch\_bool\_t notmuch\_message\_has\_maildir\_flag (notmuch\_message\_t \* message, char flag) **return TRUE if any filename of 'message' has maildir flag 'flag', FALSE otherwise. Deprecated wrapper for notmuch\_message\_has\_maildir\_flag\_st** **Returns** **FALSE in case of error** **Deprecated** **libnotmuch 5.3 (notmuch 0.31)** ### notmuch\_status\_t notmuch\_message\_has\_maildir\_flag\_st (notmuch\_message\_t \* message, char flag, notmuch\_bool\_t \* is\_set) **check message for maildir flag** **Parameters** *message* **message to check** \ *flag* **flag to check for** \ *is\_set* **pointer to boolean** **Return values** **NOTMUCH\_STATUS\_SUCCESS** \ **NOTMUCH\_STATUS\_NULL\_POINTER is\_set is NULL** \ **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION Accessing the database triggered an exception.** ### notmuch\_status\_t notmuch\_message\_tags\_to\_maildir\_flags (notmuch\_message\_t \* message) **Rename message filename(s) to encode tags as maildir flags. Specifically, for each filename corresponding to this message:** **If the filename is not in a maildir directory, do nothing. (A maildir directory is determined as a directory named "new" or "cur".) Similarly, if the filename has invalid maildir info, (repeated or outof-ASCII-order flag characters after ":2,"), then do nothing.** **If the filename is in a maildir directory, rename the file so that its filename ends with the sequence ":2," followed by zero or more of the following single-character flags (in ASCII order):** - • **flag 'D' iff the message has the "draft" tag** - • **flag 'F' iff the message has the "flagged" tag** - • **flag 'P' iff the message has the "passed" tag** - • **flag 'R' iff the message has the "replied" tag** - • **flag 'S' iff the message does not have the "unread" tag** **Any existing flags unmentioned in the list above will be preserved in the renaming.** **Also, if this filename is in a directory named "new", rename it to be within the neighboring directory named "cur".** **A client can ensure that maildir filename flags remain synchronized with notmuch database tags by calling this function after changing tags, (after calls to notmuch\_message\_add\_tag, notmuch\_message\_remove\_tag, or notmuch\_message\_freeze/ notmuch\_message\_thaw). See also notmuch\_message\_maildir\_flags\_to\_tags for synchronizing maildir flag changes back to tags.** ### notmuch\_status\_t notmuch\_message\_freeze (notmuch\_message\_t \* message) **Freeze the current state of 'message' within the database. This means that changes to the message state, (via notmuch\_message\_add\_tag, notmuch\_message\_remove\_tag, and notmuch\_message\_remove\_all\_tags), will not be committed to the database until the message is thawed with notmuch\_message\_thaw.** **Multiple calls to freeze/thaw are valid and these calls will "stack". That is there must be as many calls to thaw as to freeze before a message is actually thawed.** **The ability to do freeze/thaw allows for safe transactions to change tag values. For example, explicitly setting a message to have a given set of tags might look like this:** **notmuch\_message\_freeze (message);** **notmuch\_message\_remove\_all\_tags (message);** **for (i = 0; i \< NUM\_TAGS; i++) notmuch\_message\_add\_tag (message, tags\[i\]);** **notmuch\_message\_thaw (message);** **With freeze/thaw used like this, the message in the database is guaranteed to have either the full set of original tag values, or the full set of new tag values, but nothing in between.** **Imagine the example above without freeze/thaw and the operation somehow getting interrupted. This could result in the message being left with no tags if the interruption happened after notmuch\_message\_remove\_all\_tags but before notmuch\_message\_add\_tag.** **Return value:** **NOTMUCH\_STATUS\_SUCCESS: Message successfully frozen.** **NOTMUCH\_STATUS\_READ\_ONLY\_DATABASE: Database was opened in read-only mode so message cannot be modified.** ### notmuch\_status\_t notmuch\_message\_thaw (notmuch\_message\_t \* message) **Thaw the current 'message', synchronizing any changes that may have occurred while 'message' was frozen into the notmuch database. See notmuch\_message\_freeze for an example of how to use this function to safely provide tag changes.** **Multiple calls to freeze/thaw are valid and these calls with "stack". That is there must be as many calls to thaw as to freeze before a message is actually thawed.** **Return value:** **NOTMUCH\_STATUS\_SUCCESS: Message successfully thawed, (or at least its frozen count has successfully been reduced by 1).** **NOTMUCH\_STATUS\_UNBALANCED\_FREEZE\_THAW: An attempt was made to thaw an unfrozen message. That is, there have been an unbalanced number of calls to notmuch\_message\_freeze and notmuch\_message\_thaw.** ### void notmuch\_message\_destroy (notmuch\_message\_t \* message) **Destroy a notmuch\_message\_t object. It can be useful to call this function in the case of a single query object with many messages in the result, (such as iterating over the entire database). Otherwise, it's fine to never call this function and there will still be no memory leaks. (The memory from the messages get reclaimed when the containing query is destroyed.)** ### notmuch\_status\_t notmuch\_message\_get\_property (notmuch\_message\_t \* message, const char \* key, const char \*\* value) **Retrieve the value for a single property key.** *value* **is set to a string owned by the message or NULL if there is no such key. In the case of multiple values for the given key, the first one is retrieved.** **Returns** - • **NOTMUCH\_STATUS\_NULL\_POINTER:** *value* **may not be NULL.** - • **NOTMUCH\_STATUS\_SUCCESS: No error occurred.** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### notmuch\_status\_t notmuch\_message\_add\_property (notmuch\_message\_t \* message, const char \* key, const char \* value) **Add a (key,value) pair to a message.** **Returns** - • **NOTMUCH\_STATUS\_ILLEGAL\_ARGUMENT:** *key* **may not contain an '=' character.** - • **NOTMUCH\_STATUS\_NULL\_POINTER: Neither** *key* **nor** *value* **may be NULL.** - • **NOTMUCH\_STATUS\_SUCCESS: No error occurred.** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### notmuch\_status\_t notmuch\_message\_remove\_property (notmuch\_message\_t \* message, const char \* key, const char \* value) **Remove a (key,value) pair from a message. It is not an error to remove a non-existent (key,value) pair** **Returns** - • **NOTMUCH\_STATUS\_ILLEGAL\_ARGUMENT:** *key* **may not contain an '=' character.** - • **NOTMUCH\_STATUS\_NULL\_POINTER: Neither** *key* **nor** *value* **may be NULL.** - • **NOTMUCH\_STATUS\_SUCCESS: No error occurred.** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### notmuch\_status\_t notmuch\_message\_remove\_all\_properties (notmuch\_message\_t \* message, const char \* key) **Remove all (key,value) pairs from the given message.** **Parameters** *message* **message to operate on.** \ *key* **key to delete properties for. If NULL, delete properties for all keys** **Returns** - • **NOTMUCH\_STATUS\_READ\_ONLY\_DATABASE: Database was opened in read-only mode so message cannot be modified.** - • **NOTMUCH\_STATUS\_SUCCESS: No error occurred.** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### notmuch\_status\_t notmuch\_message\_remove\_all\_properties\_with\_prefix (notmuch\_message\_t \* message, const char \* prefix) **Remove all (prefix\*,value) pairs from the given message.** **Parameters** *message* **message to operate on.** \ *prefix* **delete properties with keys that start with prefix. If NULL, delete all properties** **Returns** - • **NOTMUCH\_STATUS\_READ\_ONLY\_DATABASE: Database was opened in read-only mode so message cannot be modified.** - • **NOTMUCH\_STATUS\_SUCCESS: No error occurred.** **Since** **libnotmuch 5.1 (notmuch 0.26)** ### notmuch\_message\_properties\_t \* notmuch\_message\_get\_properties (notmuch\_message\_t \* message, const char \* key, notmuch\_bool\_t exact) **Get the properties for** *message***, returning a notmuch\_message\_properties\_t object which can be used to iterate over all properties. The notmuch\_message\_properties\_t 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).** **Parameters** *message* **The message to examine** \ *key* **key or key prefix** \ *exact* **if TRUE, require exact match with key. Otherwise treat as prefix.** **Typical usage might be:** ``` notmuch_message_properties_t *list; for (list = notmuch_message_get_properties (message, "testkey1", TRUE); notmuch_message_properties_valid (list); notmuch_message_properties_move_to_next (list)) { printf("%s\n", notmuch_message_properties_value(list)); } notmuch_message_properties_destroy (list); ``` **Note that there's no explicit destructor needed for the notmuch\_message\_properties\_t object. (For consistency, we do provide a notmuch\_message\_properities\_destroy function, but there's no good reason to call it if the message is about to be destroyed).** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### notmuch\_status\_t notmuch\_message\_count\_properties (notmuch\_message\_t \* message, const char \* key, unsigned int \* count) **Return the number of properties named "key" belonging to the specific message.** **Parameters** *message* **The message to examine** \ *key* **key to count** \ *count* **The number of matching properties associated with this message.** **Returns** **NOTMUCH\_STATUS\_SUCCESS: successful count, possibly some other error.** **Since** **libnotmuch 5.2 (notmuch 0.27)** ### notmuch\_bool\_t notmuch\_message\_properties\_valid (notmuch\_message\_properties\_t \* properties) **Is the given** *properties* **iterator pointing at a valid (key,value) pair. When this function returns TRUE, notmuch\_message\_properties\_{key,value} will return a valid string, and notmuch\_message\_properties\_move\_to\_next will do what it says. Whereas when this function returns FALSE, calling any of these functions results in undefined behaviour.** **See the documentation of notmuch\_message\_get\_properties for example code showing how to iterate over a notmuch\_message\_properties\_t object.** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### void notmuch\_message\_properties\_move\_to\_next (notmuch\_message\_properties\_t \* properties) **Move the** *properties* **iterator to the next (key,value) pair. If** *properties* **is already pointing at the last pair then the iterator will be moved to a point just beyond that last pair, (where notmuch\_message\_properties\_valid will return FALSE).** **See the documentation of notmuch\_message\_get\_properties for example code showing how to iterate over a notmuch\_message\_properties\_t object.** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### const char \* notmuch\_message\_properties\_key (notmuch\_message\_properties\_t \* properties) **Return the key from the current (key,value) pair. this could be useful if iterating for a prefix** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### const char \* notmuch\_message\_properties\_value (notmuch\_message\_properties\_t \* properties) **Return the value from the current (key,value) pair. This could be useful if iterating for a prefix.** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### void notmuch\_message\_properties\_destroy (notmuch\_message\_properties\_t \* properties) **Destroy a notmuch\_message\_properties\_t object. It's not strictly necessary to call this function. All memory from the notmuch\_message\_properties\_t object will be reclaimed when the containing message object is destroyed.** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### notmuch\_bool\_t notmuch\_tags\_valid (notmuch\_tags\_t \* tags) **Is the given 'tags' iterator pointing at a valid tag. When this function returns TRUE, notmuch\_tags\_get will return a valid string. Whereas when this function returns FALSE, notmuch\_tags\_get will return NULL.** **It is acceptable to pass NULL for 'tags', in which case this function will always return FALSE.** **See the documentation of notmuch\_message\_get\_tags for example code showing how to iterate over a notmuch\_tags\_t object.** ### const char \* notmuch\_tags\_get (notmuch\_tags\_t \* tags) **Get the current tag from 'tags' as a string. Note: The returned string belongs to 'tags' and has a lifetime identical to it (and the query to which it ultimately belongs).** **See the documentation of notmuch\_message\_get\_tags for example code showing how to iterate over a notmuch\_tags\_t object.** ### void notmuch\_tags\_move\_to\_next (notmuch\_tags\_t \* tags) **Move the 'tags' iterator to the next tag. If 'tags' is already pointing at the last tag then the iterator will be moved to a point just beyond that last tag, (where notmuch\_tags\_valid will return FALSE and notmuch\_tags\_get will return NULL).** **See the documentation of notmuch\_message\_get\_tags for example code showing how to iterate over a notmuch\_tags\_t object.** ### void notmuch\_tags\_destroy (notmuch\_tags\_t \* tags) **Destroy a notmuch\_tags\_t object. It's not strictly necessary to call this function. All memory from the notmuch\_tags\_t object will be reclaimed when the containing message or query objects are destroyed.** ### notmuch\_status\_t notmuch\_directory\_set\_mtime (notmuch\_directory\_t \* directory, time\_t mtime) **Store an mtime within the database for 'directory'. The 'directory' should be an object retrieved from the database with notmuch\_database\_get\_directory for a particular path.** **The intention is for the caller to use the mtime to allow efficient identification of new messages to be added to the database. The recommended usage is as follows:** **o Read the mtime of a directory from the filesystem** **o Call index\_file for all mail files in the directory** **o Call notmuch\_directory\_set\_mtime with the mtime read from the filesystem.** **Then, when wanting to check for updates to the directory in the future, the client can call notmuch\_directory\_get\_mtime and know that it only needs to add files if the mtime of the directory and files are newer than the stored timestamp.** **Note: The notmuch\_directory\_get\_mtime function does not allow the caller to distinguish a timestamp of 0 from a non-existent timestamp. So don't store a timestamp of 0 unless you are comfortable with that.** **Return value:** **NOTMUCH\_STATUS\_SUCCESS: mtime successfully stored in database.** **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION: A Xapian exception occurred, mtime not stored.** **NOTMUCH\_STATUS\_READ\_ONLY\_DATABASE: Database was opened in read-only mode so directory mtime cannot be modified.** ### time\_t notmuch\_directory\_get\_mtime (notmuch\_directory\_t \* directory) **Get the mtime of a directory, (as previously stored with notmuch\_directory\_set\_mtime). Returns 0 if no mtime has previously been stored for this directory.** ### notmuch\_filenames\_t \* notmuch\_directory\_get\_child\_files (notmuch\_directory\_t \* directory) **Get a notmuch\_filenames\_t iterator listing all the filenames of messages in the database within the given directory. The returned filenames will be the basename-entries only (not complete paths).** **Returns NULL if it triggers a Xapian exception** ### notmuch\_filenames\_t \* notmuch\_directory\_get\_child\_directories (notmuch\_directory\_t \* directory) **Get a notmuch\_filenames\_t iterator listing all the filenames of sub-directories in the database within the given directory. The returned filenames will be the basename-entries only (not complete paths).** **Returns NULL if it triggers a Xapian exception** ### notmuch\_status\_t notmuch\_directory\_delete (notmuch\_directory\_t \* directory) **Delete directory document from the database, and destroy the notmuch\_directory\_t object. Assumes any child directories and files have been deleted by the caller.** **Since** **libnotmuch 4.3 (notmuch 0.21)** ### notmuch\_bool\_t notmuch\_filenames\_valid (notmuch\_filenames\_t \* filenames) **Is the given 'filenames' iterator pointing at a valid filename. When this function returns TRUE, notmuch\_filenames\_get will return a valid string. Whereas when this function returns FALSE, notmuch\_filenames\_get will return NULL.** **It is acceptable to pass NULL for 'filenames', in which case this function will always return FALSE.** ### const char \* notmuch\_filenames\_get (notmuch\_filenames\_t \* filenames) **Get the current filename from 'filenames' as a string. Note: The returned string belongs to 'filenames' and has a lifetime identical to it (and the directory to which it ultimately belongs).** **It is acceptable to pass NULL for 'filenames', in which case this function will always return NULL.** ### void notmuch\_filenames\_move\_to\_next (notmuch\_filenames\_t \* filenames) **Move the 'filenames' iterator to the next filename. If 'filenames' is already pointing at the last filename then the iterator will be moved to a point just beyond that last filename, (where notmuch\_filenames\_valid will return FALSE and notmuch\_filenames\_get will return NULL).** **It is acceptable to pass NULL for 'filenames', in which case this function will do nothing.** ### void notmuch\_filenames\_destroy (notmuch\_filenames\_t \* filenames) **Destroy a notmuch\_filenames\_t object. It's not strictly necessary to call this function. All memory from the notmuch\_filenames\_t object will be reclaimed when the containing directory object is destroyed.** **It is acceptable to pass NULL for 'filenames', in which case this function will do nothing.** ### notmuch\_status\_t notmuch\_database\_set\_config (notmuch\_database\_t \* db, const char \* key, const char \* value) **set config 'key' to 'value'** **Since** **libnotmuch 4.4 (notmuch 0.23)** **Return values** **NOTMUCH\_STATUS\_READ\_ONLY\_DATABASE Database was opened in read-only mode so message cannot be modified.** \ **NOTMUCH\_STATUS\_XAPIAN\_EXCEPTION an exception was thrown accessing the database.** \ **NOTMUCH\_STATUS\_SUCCESS** ### notmuch\_status\_t notmuch\_database\_get\_config (notmuch\_database\_t \* db, const char \* key, char \*\* value) **retrieve config item 'key', assign to 'value' keys which have not been previously set with n\_d\_set\_config will return an empty string.** **return value is allocated by malloc and should be freed by the caller.** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### notmuch\_status\_t notmuch\_database\_get\_config\_list (notmuch\_database\_t \* db, const char \* prefix, notmuch\_config\_list\_t \*\* out) **Create an iterator for all config items with keys matching a given prefix.** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### notmuch\_bool\_t notmuch\_config\_list\_valid (notmuch\_config\_list\_t \* config\_list) **Is 'config\_list' iterator valid (i.e. \_key, \_value, \_move\_to\_next can be called).** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### const char \* notmuch\_config\_list\_key (notmuch\_config\_list\_t \* config\_list) **return key for current config pair return value is owned by the iterator, and will be destroyed by the next call to notmuch\_config\_list\_key or notmuch\_config\_list\_destroy.** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### const char \* notmuch\_config\_list\_value (notmuch\_config\_list\_t \* config\_list) **return 'value' for current config pair return value is owned by the iterator, and will be destroyed by the next call to notmuch\_config\_list\_value or notmuch config\_list\_destroy** **Since** **libnotmuch 4.4 (notmuch 0.23)** **Return values** *NULL* **for errors** ### void notmuch\_config\_list\_move\_to\_next (notmuch\_config\_list\_t \* config\_list) **move 'config\_list' iterator to the next pair** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### void notmuch\_config\_list\_destroy (notmuch\_config\_list\_t \* config\_list) **free any resources held by 'config\_list'** **Since** **libnotmuch 4.4 (notmuch 0.23)** ### const char \* notmuch\_config\_get (notmuch\_database\_t \* notmuch, notmuch\_config\_key\_t key) **get a configuration value from an open database. This value reflects all configuration information given at the time the database was opened.** **Parameters** **The notmuch API database** \ *key* **configuration key** **Since** **libnotmuch 5.4 (notmuch 0.32)** **Return values** *NULL* **if 'key' unknown or if no value is known for 'key'. Otherwise returns a string owned by notmuch which should not be modified nor freed by the caller.** ### notmuch\_status\_t notmuch\_config\_set (notmuch\_database\_t \* notmuch, notmuch\_config\_key\_t key, const char \* val) **set a configuration value from in an open database. This value reflects all configuration information given at the time the database was opened.** **Parameters** **The notmuch API database open read/write** \ *key* **configuration key** \ *val* **configuration value** **Since** **libnotmuch 5.4 (notmuch 0.32)** **Return values** *returns* **any return value for notmuch\_database\_set\_config.** ### notmuch\_config\_values\_t \* notmuch\_config\_get\_values (notmuch\_database\_t \* notmuch, notmuch\_config\_key\_t key) **Returns an iterator for a ';'-delimited list of configuration values. These values reflect all configuration information given at the time the database was opened.** **Parameters** **The notmuch API database** \ *key* **configuration key** **Since** **libnotmuch 5.4 (notmuch 0.32)** **Return values** *NULL* **in case of error.** ### notmuch\_config\_values\_t \* notmuch\_config\_get\_values\_string (notmuch\_database\_t \* notmuch, const char \* key) **Returns an iterator for a ';'-delimited list of configuration values. These values reflect all configuration information given at the time the database was opened.** **Parameters** **The notmuch API database** \ *key* **configuration key** **Since** **libnotmuch 5.4 (notmuch 0.32)** **Return values** *NULL* **in case of error.** ### notmuch\_bool\_t notmuch\_config\_values\_valid (notmuch\_config\_values\_t \* values) **Is the given 'config\_values' iterator pointing at a valid element.** **Parameters** *values* **iterator** **Since** **libnotmuch 5.4 (notmuch 0.32)** **Return values** *FALSE* **if passed a NULL pointer, or the iterator is exhausted.** ### const char \* notmuch\_config\_values\_get (notmuch\_config\_values\_t \* values) **Get the current value from the 'values' iterator.** **Parameters** *values* **iterator** **Since** **libnotmuch 5.4 (notmuch 0.32)** **Return values** *a* **string with the same lifetime as the iterator** ### void notmuch\_config\_values\_move\_to\_next (notmuch\_config\_values\_t \* values) **Move the 'values' iterator to the next element.** **Parameters** *values* **iterator** **Since** **libnotmuch 5.4 (notmuch 0.32)** ### void notmuch\_config\_values\_start (notmuch\_config\_values\_t \* values) **reset the 'values' iterator to the first element** **Parameters** *values* **iterator. A NULL value is ignored.** **Since** **libnotmuch 5.4 (notmuch 0.32)** ### void notmuch\_config\_values\_destroy (notmuch\_config\_values\_t \* values) **Destroy a config values iterator, along with any associated resources.** **Parameters** *values* **iterator** **Since** **libnotmuch 5.4 (notmuch 0.32)** ### notmuch\_config\_pairs\_t \* notmuch\_config\_get\_pairs (notmuch\_database\_t \* notmuch, const char \* prefix) **Returns an iterator for a (key, value) configuration pairs.** **Parameters** **The notmuch API database** \ *prefix* **prefix for keys. Pass "" for all keys.** **Since** **libnotmuch 5.4 (notmuch 0.32)** **Return values** *NULL* **in case of error.** ### notmuch\_bool\_t notmuch\_config\_pairs\_valid (notmuch\_config\_pairs\_t \* pairs) **Is the given 'config\_pairs' iterator pointing at a valid element.** **Parameters** *pairs* **iterator** **Since** **libnotmuch 5.4 (notmuch 0.32)** **Return values** *FALSE* **if passed a NULL pointer, or the iterator is exhausted.** ### void notmuch\_config\_pairs\_move\_to\_next (notmuch\_config\_pairs\_t \* pairs) **Move the 'config\_pairs' iterator to the next element.** **Parameters** *pairs* **iterator** **Since** **libnotmuch 5.4 (notmuch 0.32)** ### const char \* notmuch\_config\_pairs\_key (notmuch\_config\_pairs\_t \* pairs) **Get the current key from the 'config\_pairs' iterator.** **Parameters** *pairs* **iterator** **Since** **libnotmuch 5.4 (notmuch 0.32)** **Return values** *a* **string with the same lifetime as the iterator** ### const char \* notmuch\_config\_pairs\_value (notmuch\_config\_pairs\_t \* pairs) **Get the current value from the 'config\_pairs' iterator.** **Parameters** *pairs* **iterator** **Since** **libnotmuch 5.4 (notmuch 0.32)** **Return values** *a* **string with the same lifetime as the iterator** ### void notmuch\_config\_pairs\_destroy (notmuch\_config\_pairs\_t \* pairs) **Destroy a config\_pairs iterator, along with any associated resources.** **Parameters** *pairs* **iterator** **Since** **libnotmuch 5.4 (notmuch 0.32)** ### notmuch\_status\_t notmuch\_config\_get\_bool (notmuch\_database\_t \* notmuch, notmuch\_config\_key\_t key, notmuch\_bool\_t \* val) **get a configuration value from an open database as Boolean This value reflects all configuration information given at the time the database was opened.** **Parameters** **The notmuch API database** \ *key* **configuration key** \ *val* **configuration value, converted to Boolean** **Since** **libnotmuch 5.4 (notmuch 0.32)** **Return values** **NOTMUCH\_STATUS\_ILLEGAL\_ARGUMENT if either key is unknown or the corresponding value does not convert to Boolean.** ### const char \* notmuch\_config\_path (notmuch\_database\_t \* notmuch) **return the path of the config file loaded, if any** **Return values** *NULL* **if no config file was loaded** ### notmuch\_indexopts\_t \* notmuch\_database\_get\_default\_indexopts (notmuch\_database\_t \* db) **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)** **Return values** *NULL* **in case of error** ### notmuch\_status\_t notmuch\_indexopts\_set\_decrypt\_policy (notmuch\_indexopts\_t \* indexopts, notmuch\_decryption\_policy\_t decrypt\_policy) **Specify whether to decrypt encrypted parts while indexing. Be aware that the index is likely sufficient to reconstruct the cleartext of the message itself, so please ensure that the notmuch message index is adequately protected. DO NOT SET THIS FLAG TO TRUE without considering the security of your index.** **Since** **libnotmuch 5.1 (notmuch 0.26)** ### notmuch\_decryption\_policy\_t notmuch\_indexopts\_get\_decrypt\_policy (const notmuch\_indexopts\_t \* indexopts) **Return whether to decrypt encrypted parts while indexing. see notmuch\_indexopts\_set\_decrypt\_policy.** **Since** **libnotmuch 5.1 (notmuch 0.26)** ### void notmuch\_indexopts\_destroy (notmuch\_indexopts\_t \* options) **Destroy a notmuch\_indexopts\_t object.** **Since** **libnotmuch 5.1 (notmuch 0.26)** ### notmuch\_bool\_t notmuch\_built\_with (const char \* name) **interrogate the library for compile time features** **Since** **libnotmuch 4.4 (notmuch 0.23)** ## Author **Generated automatically by Doxygen for Notmuch 0.40 from the source code.**