1 /* notmuch - Not much of an email library, (just index and search) 2 * 3 * Copyright © 2009 Carl Worth 4 * 5 * This program is free software: you can redistribute it and/or modify 6 * it under the terms of the GNU General Public License as published by 7 * the Free Software Foundation, either version 3 of the License, or 8 * (at your option) any later version. 9 * 10 * This program is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU General Public License for more details. 14 * 15 * You should have received a copy of the GNU General Public License 16 * along with this program. If not, see https://www.gnu.org/licenses/ . 17 * 18 * Author: Carl Worth <cworth@cworth.org> 19 */ 20 21 /** 22 * @defgroup notmuch The notmuch API 23 * 24 * Not much of an email library, (just index and search) 25 * 26 * @{ 27 */ 28 29 #ifndef NOTMUCH_H 30 #define NOTMUCH_H 31 32 #ifndef __DOXYGEN__ 33 34 #ifdef __cplusplus 35 # define NOTMUCH_BEGIN_DECLS extern "C" { 36 # define NOTMUCH_END_DECLS } 37 #else 38 # define NOTMUCH_BEGIN_DECLS 39 # define NOTMUCH_END_DECLS 40 #endif 41 42 NOTMUCH_BEGIN_DECLS 43 44 #include <time.h> 45 46 #pragma GCC visibility push(default) 47 48 #ifndef FALSE 49 #define FALSE 0 50 #endif 51 52 #ifndef TRUE 53 #define TRUE 1 54 #endif 55 56 /* 57 * The library version number. This must agree with the soname 58 * version in Makefile.local. 59 */ 60 #define LIBNOTMUCH_MAJOR_VERSION 5 61 #define LIBNOTMUCH_MINOR_VERSION 5 62 #define LIBNOTMUCH_MICRO_VERSION 0 63 64 65 #if defined (__clang_major__) && __clang_major__ >= 3 \ 66 || defined (__GNUC__) && __GNUC__ >= 5 \ 67 || defined (__GNUC__) && __GNUC__ == 4 && __GNUC_MINOR__ >= 5 68 #define NOTMUCH_DEPRECATED(major, minor) \ 69 __attribute__ ((deprecated ("function deprecated as of libnotmuch " #major "." #minor))) 70 #else 71 #define NOTMUCH_DEPRECATED(major, minor) __attribute__ ((deprecated)) 72 #endif 73 74 75 #endif /* __DOXYGEN__ */ 76 77 /** 78 * Check the version of the notmuch library being compiled against. 79 * 80 * Return true if the library being compiled against is of the 81 * specified version or above. For example: 82 * 83 * @code 84 * #if LIBNOTMUCH_CHECK_VERSION(3, 1, 0) 85 * (code requiring libnotmuch 3.1.0 or above) 86 * #endif 87 * @endcode 88 * 89 * LIBNOTMUCH_CHECK_VERSION has been defined since version 3.1.0; to 90 * check for versions prior to that, use: 91 * 92 * @code 93 * #if !defined(NOTMUCH_CHECK_VERSION) 94 * (code requiring libnotmuch prior to 3.1.0) 95 * #endif 96 * @endcode 97 */ 98 #define LIBNOTMUCH_CHECK_VERSION(major, minor, micro) \ 99 (LIBNOTMUCH_MAJOR_VERSION > (major) || \ 100 (LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION > (minor)) || \ 101 (LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION == (minor) && \ 102 LIBNOTMUCH_MICRO_VERSION >= (micro))) 103 104 /** 105 * Notmuch boolean type. 106 */ 107 typedef int notmuch_bool_t; 108 109 /** 110 * Status codes used for the return values of most functions. 111 * 112 * A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function 113 * completed without error. Any other value indicates an error. 114 */ 115 typedef enum _notmuch_status { 116 /** 117 * No error occurred. 118 */ 119 NOTMUCH_STATUS_SUCCESS = 0, 120 /** 121 * Out of memory. 122 */ 123 NOTMUCH_STATUS_OUT_OF_MEMORY, 124 /** 125 * An attempt was made to write to a database opened in read-only 126 * mode. 127 */ 128 NOTMUCH_STATUS_READ_ONLY_DATABASE, 129 /** 130 * A Xapian exception occurred. 131 * 132 * @todo We don't really want to expose this lame XAPIAN_EXCEPTION 133 * value. Instead we should map to things like DATABASE_LOCKED or 134 * whatever. 135 */ 136 NOTMUCH_STATUS_XAPIAN_EXCEPTION, 137 /** 138 * An error occurred trying to read or write to a file (this could 139 * be file not found, permission denied, etc.) 140 */ 141 NOTMUCH_STATUS_FILE_ERROR, 142 /** 143 * A file was presented that doesn't appear to be an email 144 * message. 145 */ 146 NOTMUCH_STATUS_FILE_NOT_EMAIL, 147 /** 148 * A file contains a message ID that is identical to a message 149 * already in the database. 150 */ 151 NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID, 152 /** 153 * The user erroneously passed a NULL pointer to a notmuch 154 * function. 155 */ 156 NOTMUCH_STATUS_NULL_POINTER, 157 /** 158 * A tag value is too long (exceeds NOTMUCH_TAG_MAX). 159 */ 160 NOTMUCH_STATUS_TAG_TOO_LONG, 161 /** 162 * The notmuch_message_thaw function has been called more times 163 * than notmuch_message_freeze. 164 */ 165 NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW, 166 /** 167 * notmuch_database_end_atomic has been called more times than 168 * notmuch_database_begin_atomic. 169 */ 170 NOTMUCH_STATUS_UNBALANCED_ATOMIC, 171 /** 172 * The operation is not supported. 173 */ 174 NOTMUCH_STATUS_UNSUPPORTED_OPERATION, 175 /** 176 * The operation requires a database upgrade. 177 */ 178 NOTMUCH_STATUS_UPGRADE_REQUIRED, 179 /** 180 * There is a problem with the proposed path, e.g. a relative path 181 * passed to a function expecting an absolute path. 182 */ 183 NOTMUCH_STATUS_PATH_ERROR, 184 /** 185 * The requested operation was ignored. Depending on the function, 186 * this may not be an actual error. 187 */ 188 NOTMUCH_STATUS_IGNORED, 189 /** 190 * One of the arguments violates the preconditions for the 191 * function, in a way not covered by a more specific argument. 192 */ 193 NOTMUCH_STATUS_ILLEGAL_ARGUMENT, 194 /** 195 * A MIME object claimed to have cryptographic protection which 196 * notmuch tried to handle, but the protocol was not specified in 197 * an intelligible way. 198 */ 199 NOTMUCH_STATUS_MALFORMED_CRYPTO_PROTOCOL, 200 /** 201 * Notmuch attempted to do crypto processing, but could not 202 * initialize the engine needed to do so. 203 */ 204 NOTMUCH_STATUS_FAILED_CRYPTO_CONTEXT_CREATION, 205 /** 206 * A MIME object claimed to have cryptographic protection, and 207 * notmuch attempted to process it, but the specific protocol was 208 * something that notmuch doesn't know how to handle. 209 */ 210 NOTMUCH_STATUS_UNKNOWN_CRYPTO_PROTOCOL, 211 /** 212 * Unable to load a config file 213 */ 214 NOTMUCH_STATUS_NO_CONFIG, 215 /** 216 * Unable to load a database 217 */ 218 NOTMUCH_STATUS_NO_DATABASE, 219 /** 220 * Database exists, so not (re)-created 221 */ 222 NOTMUCH_STATUS_DATABASE_EXISTS, 223 /** 224 * Syntax error in query 225 */ 226 NOTMUCH_STATUS_BAD_QUERY_SYNTAX, 227 /** 228 * Not an actual status value. Just a way to find out how many 229 * valid status values there are. 230 */ 231 NOTMUCH_STATUS_LAST_STATUS 232 } notmuch_status_t; 233 234 /** 235 * Get a string representation of a notmuch_status_t value. 236 * 237 * The result is read-only. 238 */ 239 const char * 240 notmuch_status_to_string (notmuch_status_t status); 241 242 /* Various opaque data types. For each notmuch_<foo>_t see the various 243 * notmuch_<foo> functions below. */ 244 #ifndef __DOXYGEN__ 245 typedef struct _notmuch_database notmuch_database_t; 246 typedef struct _notmuch_query notmuch_query_t; 247 typedef struct _notmuch_threads notmuch_threads_t; 248 typedef struct _notmuch_thread notmuch_thread_t; 249 typedef struct _notmuch_messages notmuch_messages_t; 250 typedef struct _notmuch_message notmuch_message_t; 251 typedef struct _notmuch_tags notmuch_tags_t; 252 typedef struct _notmuch_directory notmuch_directory_t; 253 typedef struct _notmuch_filenames notmuch_filenames_t; 254 typedef struct _notmuch_config_list notmuch_config_list_t; 255 typedef struct _notmuch_config_values notmuch_config_values_t; 256 typedef struct _notmuch_config_pairs notmuch_config_pairs_t; 257 typedef struct _notmuch_indexopts notmuch_indexopts_t; 258 #endif /* __DOXYGEN__ */ 259 260 /** 261 * Create a new, empty notmuch database located at 'path'. 262 * 263 * The path should be a top-level directory to a collection of 264 * plain-text email messages (one message per file). This call will 265 * create a new ".notmuch" directory within 'path' where notmuch will 266 * store its data. 267 * 268 * After a successful call to notmuch_database_create, the returned 269 * database will be open so the caller should call 270 * notmuch_database_destroy when finished with it. 271 * 272 * The database will not yet have any data in it 273 * (notmuch_database_create itself is a very cheap function). Messages 274 * contained within 'path' can be added to the database by calling 275 * notmuch_database_index_file. 276 * 277 * In case of any failure, this function returns an error status and 278 * sets *database to NULL (after printing an error message on stderr). 279 * 280 * Return value: 281 * 282 * NOTMUCH_STATUS_SUCCESS: Successfully created the database. 283 * 284 * NOTMUCH_STATUS_NULL_POINTER: The given 'path' argument is NULL. 285 * 286 * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. 287 * 288 * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to create the 289 * database file (such as permission denied, or file not found, 290 * etc.), or the database already exists. 291 * 292 * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. 293 */ 294 notmuch_status_t 295 notmuch_database_create (const char *path, notmuch_database_t **database); 296 297 /** 298 * Like notmuch_database_create, except optionally return an error 299 * message. This message is allocated by malloc and should be freed by 300 * the caller. 301 */ 302 notmuch_status_t 303 notmuch_database_create_verbose (const char *path, 304 notmuch_database_t **database, 305 char **error_message); 306 307 /** 308 * Database open mode for notmuch_database_open. 309 */ 310 typedef enum { 311 /** 312 * Open database for reading only. 313 */ 314 NOTMUCH_DATABASE_MODE_READ_ONLY = 0, 315 /** 316 * Open database for reading and writing. 317 */ 318 NOTMUCH_DATABASE_MODE_READ_WRITE 319 } notmuch_database_mode_t; 320 321 /** 322 * Deprecated alias for notmuch_database_open_with_config with 323 * config_path="" and error_message=NULL 324 * @deprecated Deprecated as of libnotmuch 5.4 (notmuch 0.32) 325 */ 326 /* NOTMUCH_DEPRECATED(5, 4) */ 327 notmuch_status_t 328 notmuch_database_open (const char *path, 329 notmuch_database_mode_t mode, 330 notmuch_database_t **database); 331 /** 332 * Deprecated alias for notmuch_database_open_with_config with 333 * config_path="" 334 * 335 * @deprecated Deprecated as of libnotmuch 5.4 (notmuch 0.32) 336 * 337 */ 338 /* NOTMUCH_DEPRECATED(5, 4) */ 339 notmuch_status_t 340 notmuch_database_open_verbose (const char *path, 341 notmuch_database_mode_t mode, 342 notmuch_database_t **database, 343 char **error_message); 344 345 /** 346 * Open an existing notmuch database located at 'database_path', using 347 * configuration in 'config_path'. 348 * 349 * @param[in] database_path 350 * @parblock 351 * Path to existing database. 352 * 353 * A notmuch database is a Xapian database containing appropriate 354 * metadata. 355 * 356 * The database should have been created at some time in the past, 357 * (not necessarily by this process), by calling 358 * notmuch_database_create. 359 * 360 * If 'database_path' is NULL, use the location specified 361 * 362 * - in the environment variable NOTMUCH_DATABASE, if non-empty 363 * 364 * - in a configuration file, located as described under 'config_path' 365 * 366 * - by $XDG_DATA_HOME/notmuch/$PROFILE where XDG_DATA_HOME defaults 367 * to "$HOME/.local/share" and PROFILE as as discussed in 368 * 'profile' 369 * 370 * If 'database_path' is non-NULL, but does not appear to be a Xapian 371 * database, check for a directory '.notmuch/xapian' below 372 * 'database_path' (this is the behavior of 373 * notmuch_database_open_verbose pre-0.32). 374 * 375 * @endparblock 376 * @param[in] mode 377 * @parblock 378 * Mode to open database. Use one of #NOTMUCH_DATABASE_MODE_READ_WRITE 379 * or #NOTMUCH_DATABASE_MODE_READ_ONLY 380 * 381 * @endparblock 382 * @param[in] config_path 383 * @parblock 384 * Path to config file. 385 * 386 * Config file is key-value, with mandatory sections. See 387 * <em>notmuch-config(5)</em> for more information. The key-value pair 388 * overrides the corresponding configuration data stored in the 389 * database (see <em>notmuch_database_get_config</em>) 390 * 391 * If <em>config_path</em> is NULL use the path specified 392 * 393 * - in environment variable <em>NOTMUCH_CONFIG</em>, if non-empty 394 * 395 * - by <em>XDG_CONFIG_HOME</em>/notmuch/ where 396 * XDG_CONFIG_HOME defaults to "$HOME/.config". 397 * 398 * - by $HOME/.notmuch-config 399 * 400 * If <em>config_path</em> is "" (empty string) then do not 401 * open any configuration file. 402 * @endparblock 403 * @param[in] profile: 404 * @parblock 405 * Name of profile (configuration/database variant). 406 * 407 * If non-NULL, append to the directory / file path determined for 408 * <em>config_path</em> and <em>database_path</em>. 409 * 410 * If NULL then use 411 * - environment variable NOTMUCH_PROFILE if defined, 412 * - otherwise "default" for directories and "" (empty string) for paths. 413 * 414 * @endparblock 415 * @param[out] database 416 * @parblock 417 * Pointer to database object. May not be NULL. 418 * 419 * The caller should call notmuch_database_destroy when finished with 420 * this database. 421 * 422 * In case of any failure, this function returns an error status and 423 * sets *database to NULL. 424 * 425 * @endparblock 426 * @param[out] error_message 427 * If non-NULL, store error message from opening the database. 428 * Any such message is allocated by \a malloc(3) and should be freed 429 * by the caller. 430 * 431 * @retval NOTMUCH_STATUS_SUCCESS: Successfully opened the database. 432 * 433 * @retval NOTMUCH_STATUS_NULL_POINTER: The given \a database 434 * argument is NULL. 435 * 436 * @retval NOTMUCH_STATUS_NO_CONFIG: No config file was found. Fatal. 437 * 438 * @retval NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. 439 * 440 * @retval NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the 441 * database or config file (such as permission denied, or file not found, 442 * etc.), or the database version is unknown. 443 * 444 * @retval NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. 445 * 446 * @since libnotmuch 5.4 (notmuch 0.32) 447 */ 448 449 notmuch_status_t 450 notmuch_database_open_with_config (const char *database_path, 451 notmuch_database_mode_t mode, 452 const char *config_path, 453 const char *profile, 454 notmuch_database_t **database, 455 char **error_message); 456 457 458 /** 459 * Loads configuration from config file, database, and/or defaults 460 * 461 * For description of arguments, @see notmuch_database_open_with_config 462 * 463 * For errors other then NO_DATABASE and NO_CONFIG, *database is set to 464 * NULL. 465 * 466 * @retval NOTMUCH_STATUS_SUCCESS: Successfully loaded configuration. 467 * 468 * @retval NOTMUCH_STATUS_NO_CONFIG: No config file was loaded. Not fatal. 469 * 470 * @retval NOTMUCH_STATUS_NO_DATABASE: No config information was 471 * loaded from a database. Not fatal. 472 * 473 * @retval NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. 474 * 475 * @retval NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the 476 * database or config file (such as permission denied, or file not found, 477 * etc.) 478 * 479 * @retval NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. 480 * 481 * @since libnotmuch 5.4 (notmuch 0.32) 482 */ 483 484 notmuch_status_t 485 notmuch_database_load_config (const char *database_path, 486 const char *config_path, 487 const char *profile, 488 notmuch_database_t **database, 489 char **error_message); 490 491 /** 492 * Create a new notmuch database located at 'database_path', using 493 * configuration in 'config_path'. 494 * 495 * For description of arguments, @see notmuch_database_open_with_config 496 * 497 * In case of any failure, this function returns an error status and 498 * sets *database to NULL. 499 * 500 * @retval NOTMUCH_STATUS_SUCCESS: Successfully created the database. 501 * 502 * @retval NOTMUCH_STATUS_DATABASE_EXISTS: Database already exists, not created 503 * 504 * @retval NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. 505 * 506 * @retval NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the 507 * database or config file (such as permission denied, or file not found, 508 * etc.) 509 * 510 * @retval NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. 511 * 512 * @since libnotmuch 5.4 (notmuch 0.32) 513 */ 514 515 notmuch_status_t 516 notmuch_database_create_with_config (const char *database_path, 517 const char *config_path, 518 const char *profile, 519 notmuch_database_t **database, 520 char **error_message); 521 522 /** 523 * Retrieve last status string for given database. 524 * 525 */ 526 const char * 527 notmuch_database_status_string (const notmuch_database_t *notmuch); 528 529 /** 530 * Commit changes and close the given notmuch database. 531 * 532 * After notmuch_database_close has been called, calls to other 533 * functions on objects derived from this database may either behave 534 * as if the database had not been closed (e.g., if the required data 535 * has been cached) or may fail with a 536 * NOTMUCH_STATUS_XAPIAN_EXCEPTION. The only further operation 537 * permitted on the database itself is to call 538 * notmuch_database_destroy. 539 * 540 * notmuch_database_close can be called multiple times. Later calls 541 * have no effect. 542 * 543 * For writable databases, notmuch_database_close commits all changes 544 * to disk before closing the database, unless the caller is currently 545 * in an atomic section (there was a notmuch_database_begin_atomic 546 * without a matching notmuch_database_end_atomic). In this case 547 * changes since the last commit are discarded. @see 548 * notmuch_database_end_atomic for more information. 549 * 550 * Return value: 551 * 552 * NOTMUCH_STATUS_SUCCESS: Successfully closed the database. 553 * 554 * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; the 555 * database has been closed but there are no guarantees the 556 * changes to the database, if any, have been flushed to disk. 557 */ 558 notmuch_status_t 559 notmuch_database_close (notmuch_database_t *database); 560 561 /** 562 * A callback invoked by notmuch_database_compact to notify the user 563 * of the progress of the compaction process. 564 */ 565 typedef void (*notmuch_compact_status_cb_t)(const char *message, void *closure); 566 567 /** 568 * Compact a notmuch database, backing up the original database to the 569 * given path. 570 * 571 * The database will be opened with NOTMUCH_DATABASE_MODE_READ_WRITE 572 * during the compaction process to ensure no writes are made. 573 * 574 * If the optional callback function 'status_cb' is non-NULL, it will 575 * be called with diagnostic and informational messages. The argument 576 * 'closure' is passed verbatim to any callback invoked. 577 */ 578 notmuch_status_t 579 notmuch_database_compact (const char *path, 580 const char *backup_path, 581 notmuch_compact_status_cb_t status_cb, 582 void *closure); 583 584 /** 585 * Like notmuch_database_compact, but take an open database as a 586 * parameter. 587 * 588 * @since libnnotmuch 5.4 (notmuch 0.32) 589 */ 590 notmuch_status_t 591 notmuch_database_compact_db (notmuch_database_t *database, 592 const char *backup_path, 593 notmuch_compact_status_cb_t status_cb, 594 void *closure); 595 596 /** 597 * Destroy the notmuch database, closing it if necessary and freeing 598 * all associated resources. 599 * 600 * Return value as in notmuch_database_close if the database was open; 601 * notmuch_database_destroy itself has no failure modes. 602 */ 603 notmuch_status_t 604 notmuch_database_destroy (notmuch_database_t *database); 605 606 /** 607 * Return the database path of the given database. 608 * 609 * The return value is a string owned by notmuch so should not be 610 * modified nor freed by the caller. 611 */ 612 const char * 613 notmuch_database_get_path (notmuch_database_t *database); 614 615 /** 616 * Return the database format version of the given database. 617 * 618 * @retval 0 on error 619 */ 620 unsigned int 621 notmuch_database_get_version (notmuch_database_t *database); 622 623 /** 624 * Can the database be upgraded to a newer database version? 625 * 626 * If this function returns TRUE, then the caller may call 627 * notmuch_database_upgrade to upgrade the database. If the caller 628 * does not upgrade an out-of-date database, then some functions may 629 * fail with NOTMUCH_STATUS_UPGRADE_REQUIRED. This always returns 630 * FALSE for a read-only database because there's no way to upgrade a 631 * read-only database. 632 * 633 * Also returns FALSE if an error occurs accessing the database. 634 * 635 */ 636 notmuch_bool_t 637 notmuch_database_needs_upgrade (notmuch_database_t *database); 638 639 /** 640 * Upgrade the current database to the latest supported version. 641 * 642 * This ensures that all current notmuch functionality will be 643 * available on the database. After opening a database in read-write 644 * mode, it is recommended that clients check if an upgrade is needed 645 * (notmuch_database_needs_upgrade) and if so, upgrade with this 646 * function before making any modifications. If 647 * notmuch_database_needs_upgrade returns FALSE, this will be a no-op. 648 * 649 * The optional progress_notify callback can be used by the caller to 650 * provide progress indication to the user. If non-NULL it will be 651 * called periodically with 'progress' as a floating-point value in 652 * the range of [0.0 .. 1.0] indicating the progress made so far in 653 * the upgrade process. The argument 'closure' is passed verbatim to 654 * any callback invoked. 655 */ 656 notmuch_status_t 657 notmuch_database_upgrade (notmuch_database_t *database, 658 void (*progress_notify)(void *closure, 659 double progress), 660 void *closure); 661 662 /** 663 * Begin an atomic database operation. 664 * 665 * Any modifications performed between a successful begin and a 666 * notmuch_database_end_atomic will be applied to the database 667 * atomically. Note that, unlike a typical database transaction, this 668 * only ensures atomicity, not durability; neither begin nor end 669 * necessarily flush modifications to disk. 670 * 671 * Atomic sections may be nested. begin_atomic and end_atomic must 672 * always be called in pairs. 673 * 674 * Return value: 675 * 676 * NOTMUCH_STATUS_SUCCESS: Successfully entered atomic section. 677 * 678 * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; 679 * atomic section not entered. 680 */ 681 notmuch_status_t 682 notmuch_database_begin_atomic (notmuch_database_t *notmuch); 683 684 /** 685 * Indicate the end of an atomic database operation. If repeated 686 * (with matching notmuch_database_begin_atomic) "database.autocommit" 687 * times, commit the the transaction and all previous (non-cancelled) 688 * transactions to the database. 689 * 690 * Return value: 691 * 692 * NOTMUCH_STATUS_SUCCESS: Successfully completed atomic section. 693 * 694 * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; 695 * atomic section not ended. 696 * 697 * NOTMUCH_STATUS_UNBALANCED_ATOMIC: The database is not currently in 698 * an atomic section. 699 */ 700 notmuch_status_t 701 notmuch_database_end_atomic (notmuch_database_t *notmuch); 702 703 /** 704 * Return the committed database revision and UUID. 705 * 706 * The database revision number increases monotonically with each 707 * commit to the database. Hence, all messages and message changes 708 * committed to the database (that is, visible to readers) have a last 709 * modification revision <= the committed database revision. Any 710 * messages committed in the future will be assigned a modification 711 * revision > the committed database revision. 712 * 713 * The UUID is a NUL-terminated opaque string that uniquely identifies 714 * this database. Two revision numbers are only comparable if they 715 * have the same database UUID. 716 */ 717 unsigned long 718 notmuch_database_get_revision (notmuch_database_t *notmuch, 719 const char **uuid); 720 721 /** 722 * Retrieve a directory object from the database for 'path'. 723 * 724 * Here, 'path' should be a path relative to the path of 'database' 725 * (see notmuch_database_get_path), or else should be an absolute path 726 * with initial components that match the path of 'database'. 727 * 728 * If this directory object does not exist in the database, this 729 * returns NOTMUCH_STATUS_SUCCESS and sets *directory to NULL. 730 * 731 * Otherwise the returned directory object is owned by the database 732 * and as such, will only be valid until notmuch_database_destroy is 733 * called. 734 * 735 * Return value: 736 * 737 * NOTMUCH_STATUS_SUCCESS: Successfully retrieved directory. 738 * 739 * NOTMUCH_STATUS_NULL_POINTER: The given 'directory' argument is NULL. 740 * 741 * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; 742 * directory not retrieved. 743 * 744 * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the 745 * database to use this function. 746 */ 747 notmuch_status_t 748 notmuch_database_get_directory (notmuch_database_t *database, 749 const char *path, 750 notmuch_directory_t **directory); 751 752 /** 753 * Add a message file to a database, indexing it for retrieval by 754 * future searches. If a message already exists with the same message 755 * ID as the specified file, their indexes will be merged, and this 756 * new filename will also be associated with the existing message. 757 * 758 * Here, 'filename' should be a path relative to the path of 759 * 'database' (see notmuch_database_get_path), or else should be an 760 * absolute filename with initial components that match the path of 761 * 'database'. 762 * 763 * The file should be a single mail message (not a multi-message mbox) 764 * that is expected to remain at its current location, (since the 765 * notmuch database will reference the filename, and will not copy the 766 * entire contents of the file. 767 * 768 * If another message with the same message ID already exists in the 769 * database, rather than creating a new message, this adds the search 770 * terms from the identified file to the existing message's index, and 771 * adds 'filename' to the list of filenames known for the message. 772 * 773 * The 'indexopts' parameter can be NULL (meaning, use the indexing 774 * defaults from the database), or can be an explicit choice of 775 * indexing options that should govern the indexing of this specific 776 * 'filename'. 777 * 778 * If 'message' is not NULL, then, on successful return 779 * (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message' 780 * will be initialized to a message object that can be used for things 781 * such as adding tags to the just-added message. The user should call 782 * notmuch_message_destroy when done with the message. On any failure 783 * '*message' will be set to NULL. 784 * 785 * Return value: 786 * 787 * NOTMUCH_STATUS_SUCCESS: Message successfully added to database. 788 * 789 * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred, 790 * message not added. 791 * 792 * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message 793 * ID as another message already in the database. The new 794 * filename was successfully added to the message in the database 795 * (if not already present) and the existing message is returned. 796 * 797 * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the 798 * file, (such as permission denied, or file not found, 799 * etc.). Nothing added to the database. 800 * 801 * NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look 802 * like an email message. Nothing added to the database. 803 * 804 * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only 805 * mode so no message can be added. 806 * 807 * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the 808 * database to use this function. 809 * 810 * @since libnotmuch 5.1 (notmuch 0.26) 811 */ 812 notmuch_status_t 813 notmuch_database_index_file (notmuch_database_t *database, 814 const char *filename, 815 notmuch_indexopts_t *indexopts, 816 notmuch_message_t **message); 817 818 /** 819 * Deprecated alias for notmuch_database_index_file called with 820 * NULL indexopts. 821 * 822 * @deprecated Deprecated as of libnotmuch 5.1 (notmuch 0.26). Please 823 * use notmuch_database_index_file instead. 824 * 825 */ 826 NOTMUCH_DEPRECATED (5, 1) 827 notmuch_status_t 828 notmuch_database_add_message (notmuch_database_t *database, 829 const char *filename, 830 notmuch_message_t **message); 831 832 /** 833 * Remove a message filename from the given notmuch database. If the 834 * message has no more filenames, remove the message. 835 * 836 * If the same message (as determined by the message ID) is still 837 * available via other filenames, then the message will persist in the 838 * database for those filenames. When the last filename is removed for 839 * a particular message, the database content for that message will be 840 * entirely removed. 841 * 842 * Return value: 843 * 844 * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the 845 * message was removed from the database. 846 * 847 * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred, 848 * message not removed. 849 * 850 * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but 851 * the message persists in the database with at least one other 852 * filename. 853 * 854 * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only 855 * mode so no message can be removed. 856 * 857 * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the 858 * database to use this function. 859 */ 860 notmuch_status_t 861 notmuch_database_remove_message (notmuch_database_t *database, 862 const char *filename); 863 864 /** 865 * Find a message with the given message_id. 866 * 867 * If a message with the given message_id is found then, on successful return 868 * (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to a message 869 * object. The caller should call notmuch_message_destroy when done with the 870 * message. 871 * 872 * On any failure or when the message is not found, this function initializes 873 * '*message' to NULL. This means, when NOTMUCH_STATUS_SUCCESS is returned, the 874 * caller is supposed to check '*message' for NULL to find out whether the 875 * message with the given message_id was found. 876 * 877 * Return value: 878 * 879 * NOTMUCH_STATUS_SUCCESS: Successful return, check '*message'. 880 * 881 * NOTMUCH_STATUS_NULL_POINTER: The given 'message' argument is NULL 882 * 883 * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating message object 884 * 885 * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred 886 */ 887 notmuch_status_t 888 notmuch_database_find_message (notmuch_database_t *database, 889 const char *message_id, 890 notmuch_message_t **message); 891 892 /** 893 * Find a message with the given filename. 894 * 895 * If the database contains a message with the given filename then, on 896 * successful return (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to 897 * a message object. The caller should call notmuch_message_destroy when done 898 * with the message. 899 * 900 * On any failure or when the message is not found, this function initializes 901 * '*message' to NULL. This means, when NOTMUCH_STATUS_SUCCESS is returned, the 902 * caller is supposed to check '*message' for NULL to find out whether the 903 * message with the given filename is found. 904 * 905 * Return value: 906 * 907 * NOTMUCH_STATUS_SUCCESS: Successful return, check '*message' 908 * 909 * NOTMUCH_STATUS_NULL_POINTER: The given 'message' argument is NULL 910 * 911 * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating the message object 912 * 913 * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred 914 * 915 * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the 916 * database to use this function. 917 */ 918 notmuch_status_t 919 notmuch_database_find_message_by_filename (notmuch_database_t *notmuch, 920 const char *filename, 921 notmuch_message_t **message); 922 923 /** 924 * Return a list of all tags found in the database. 925 * 926 * This function creates a list of all tags found in the database. The 927 * resulting list contains all tags from all messages found in the database. 928 * 929 * On error this function returns NULL. 930 */ 931 notmuch_tags_t * 932 notmuch_database_get_all_tags (notmuch_database_t *db); 933 934 /** 935 * Reopen an open notmuch database. 936 * 937 * @param [in] db open notmuch database 938 * @param [in] mode mode (read only or read-write) for reopened database. 939 * 940 * @retval #NOTMUCH_STATUS_SUCCESS 941 * @retval #NOTMUCH_STATUS_ILLEGAL_ARGUMENT The passed database was not open. 942 * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION A Xapian exception occured 943 */ 944 notmuch_status_t 945 notmuch_database_reopen (notmuch_database_t *db, notmuch_database_mode_t mode); 946 947 /** 948 * Create a new query for 'database'. 949 * 950 * Here, 'database' should be an open database, (see 951 * notmuch_database_open and notmuch_database_create). 952 * 953 * For the query string, we'll document the syntax here more 954 * completely in the future, but it's likely to be a specialized 955 * version of the general Xapian query syntax: 956 * 957 * https://xapian.org/docs/queryparser.html 958 * 959 * As a special case, passing either a length-zero string, (that is ""), 960 * or a string consisting of a single asterisk (that is "*"), will 961 * result in a query that returns all messages in the database. 962 * 963 * See notmuch_query_set_sort for controlling the order of results. 964 * See notmuch_query_search_messages and notmuch_query_search_threads 965 * to actually execute the query. 966 * 967 * User should call notmuch_query_destroy when finished with this 968 * query. 969 * 970 * Will return NULL if insufficient memory is available. 971 */ 972 notmuch_query_t * 973 notmuch_query_create (notmuch_database_t *database, 974 const char *query_string); 975 976 typedef enum { 977 NOTMUCH_QUERY_SYNTAX_XAPIAN, 978 NOTMUCH_QUERY_SYNTAX_SEXP 979 } notmuch_query_syntax_t; 980 981 notmuch_status_t 982 notmuch_query_create_with_syntax (notmuch_database_t *database, 983 const char *query_string, 984 notmuch_query_syntax_t syntax, 985 notmuch_query_t **output); 986 /** 987 * Sort values for notmuch_query_set_sort. 988 */ 989 typedef enum { 990 /** 991 * Oldest first. 992 */ 993 NOTMUCH_SORT_OLDEST_FIRST, 994 /** 995 * Newest first. 996 */ 997 NOTMUCH_SORT_NEWEST_FIRST, 998 /** 999 * Sort by message-id. 1000 */ 1001 NOTMUCH_SORT_MESSAGE_ID, 1002 /** 1003 * Do not sort. 1004 */ 1005 NOTMUCH_SORT_UNSORTED 1006 } notmuch_sort_t; 1007 1008 /** 1009 * Return the query_string of this query. See notmuch_query_create. 1010 */ 1011 const char * 1012 notmuch_query_get_query_string (const notmuch_query_t *query); 1013 1014 /** 1015 * Return the notmuch database of this query. See notmuch_query_create. 1016 */ 1017 notmuch_database_t * 1018 notmuch_query_get_database (const notmuch_query_t *query); 1019 1020 /** 1021 * Exclude values for notmuch_query_set_omit_excluded. The strange 1022 * order is to maintain backward compatibility: the old FALSE/TRUE 1023 * options correspond to the new 1024 * NOTMUCH_EXCLUDE_FLAG/NOTMUCH_EXCLUDE_TRUE options. 1025 */ 1026 typedef enum { 1027 NOTMUCH_EXCLUDE_FLAG, 1028 NOTMUCH_EXCLUDE_TRUE, 1029 NOTMUCH_EXCLUDE_FALSE, 1030 NOTMUCH_EXCLUDE_ALL 1031 } notmuch_exclude_t; 1032 1033 /** 1034 * Specify whether to omit excluded results or simply flag them. By 1035 * default, this is set to TRUE. 1036 * 1037 * If set to TRUE or ALL, notmuch_query_search_messages will omit excluded 1038 * messages from the results, and notmuch_query_search_threads will omit 1039 * threads that match only in excluded messages. If set to TRUE, 1040 * notmuch_query_search_threads will include all messages in threads that 1041 * match in at least one non-excluded message. Otherwise, if set to ALL, 1042 * notmuch_query_search_threads will omit excluded messages from all threads. 1043 * 1044 * If set to FALSE or FLAG then both notmuch_query_search_messages and 1045 * notmuch_query_search_threads will return all matching 1046 * messages/threads regardless of exclude status. If set to FLAG then 1047 * the exclude flag will be set for any excluded message that is 1048 * returned by notmuch_query_search_messages, and the thread counts 1049 * for threads returned by notmuch_query_search_threads will be the 1050 * number of non-excluded messages/matches. Otherwise, if set to 1051 * FALSE, then the exclude status is completely ignored. 1052 * 1053 * The performance difference when calling 1054 * notmuch_query_search_messages should be relatively small (and both 1055 * should be very fast). However, in some cases, 1056 * notmuch_query_search_threads is very much faster when omitting 1057 * excluded messages as it does not need to construct the threads that 1058 * only match in excluded messages. 1059 */ 1060 void 1061 notmuch_query_set_omit_excluded (notmuch_query_t *query, 1062 notmuch_exclude_t omit_excluded); 1063 1064 /** 1065 * Specify the sorting desired for this query. 1066 */ 1067 void 1068 notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort); 1069 1070 /** 1071 * Return the sort specified for this query. See 1072 * notmuch_query_set_sort. 1073 */ 1074 notmuch_sort_t 1075 notmuch_query_get_sort (const notmuch_query_t *query); 1076 1077 /** 1078 * Add a tag that will be excluded from the query results by default. 1079 * This exclusion will be ignored if this tag appears explicitly in 1080 * the query. 1081 * 1082 * @returns 1083 * 1084 * NOTMUCH_STATUS_SUCCESS: excluded was added successfully. 1085 * 1086 * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. 1087 * Most likely a problem lazily parsing the query string. 1088 * 1089 * NOTMUCH_STATUS_IGNORED: tag is explicitly present in the query, so 1090 * not excluded. 1091 */ 1092 notmuch_status_t 1093 notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag); 1094 1095 /** 1096 * Execute a query for threads, returning a notmuch_threads_t object 1097 * which can be used to iterate over the results. The returned threads 1098 * object is owned by the query and as such, will only be valid until 1099 * notmuch_query_destroy. 1100 * 1101 * Typical usage might be: 1102 * 1103 * notmuch_query_t *query; 1104 * notmuch_threads_t *threads; 1105 * notmuch_thread_t *thread; 1106 * notmuch_status_t stat; 1107 * 1108 * query = notmuch_query_create (database, query_string); 1109 * 1110 * for (stat = notmuch_query_search_threads (query, &threads); 1111 * stat == NOTMUCH_STATUS_SUCCESS && 1112 * notmuch_threads_valid (threads); 1113 * notmuch_threads_move_to_next (threads)) 1114 * { 1115 * thread = notmuch_threads_get (threads); 1116 * .... 1117 * notmuch_thread_destroy (thread); 1118 * } 1119 * 1120 * notmuch_query_destroy (query); 1121 * 1122 * Note: If you are finished with a thread before its containing 1123 * query, you can call notmuch_thread_destroy to clean up some memory 1124 * sooner (as in the above example). Otherwise, if your thread objects 1125 * are long-lived, then you don't need to call notmuch_thread_destroy 1126 * and all the memory will still be reclaimed when the query is 1127 * destroyed. 1128 * 1129 * Note that there's no explicit destructor needed for the 1130 * notmuch_threads_t object. (For consistency, we do provide a 1131 * notmuch_threads_destroy function, but there's no good reason 1132 * to call it if the query is about to be destroyed). 1133 * 1134 * @since libnotmuch 5.0 (notmuch 0.25) 1135 */ 1136 notmuch_status_t 1137 notmuch_query_search_threads (notmuch_query_t *query, 1138 notmuch_threads_t **out); 1139 1140 /** 1141 * Deprecated alias for notmuch_query_search_threads. 1142 * 1143 * @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please 1144 * use notmuch_query_search_threads instead. 1145 * 1146 */ 1147 NOTMUCH_DEPRECATED (5, 0) 1148 notmuch_status_t 1149 notmuch_query_search_threads_st (notmuch_query_t *query, notmuch_threads_t **out); 1150 1151 /** 1152 * Execute a query for messages, returning a notmuch_messages_t object 1153 * which can be used to iterate over the results. The returned 1154 * messages object is owned by the query and as such, will only be 1155 * valid until notmuch_query_destroy. 1156 * 1157 * Typical usage might be: 1158 * 1159 * notmuch_query_t *query; 1160 * notmuch_messages_t *messages; 1161 * notmuch_message_t *message; 1162 * 1163 * query = notmuch_query_create (database, query_string); 1164 * 1165 * for (messages = notmuch_query_search_messages (query); 1166 * notmuch_messages_valid (messages); 1167 * notmuch_messages_move_to_next (messages)) 1168 * { 1169 * message = notmuch_messages_get (messages); 1170 * .... 1171 * notmuch_message_destroy (message); 1172 * } 1173 * 1174 * notmuch_query_destroy (query); 1175 * 1176 * Note: If you are finished with a message before its containing 1177 * query, you can call notmuch_message_destroy to clean up some memory 1178 * sooner (as in the above example). Otherwise, if your message 1179 * objects are long-lived, then you don't need to call 1180 * notmuch_message_destroy and all the memory will still be reclaimed 1181 * when the query is destroyed. 1182 * 1183 * Note that there's no explicit destructor needed for the 1184 * notmuch_messages_t object. (For consistency, we do provide a 1185 * notmuch_messages_destroy function, but there's no good 1186 * reason to call it if the query is about to be destroyed). 1187 * 1188 * If a Xapian exception occurs this function will return NULL. 1189 * 1190 * @since libnotmuch 5 (notmuch 0.25) 1191 */ 1192 notmuch_status_t 1193 notmuch_query_search_messages (notmuch_query_t *query, 1194 notmuch_messages_t **out); 1195 /** 1196 * Deprecated alias for notmuch_query_search_messages 1197 * 1198 * @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please use 1199 * notmuch_query_search_messages instead. 1200 * 1201 */ 1202 1203 NOTMUCH_DEPRECATED (5, 0) 1204 notmuch_status_t 1205 notmuch_query_search_messages_st (notmuch_query_t *query, 1206 notmuch_messages_t **out); 1207 1208 /** 1209 * Destroy a notmuch_query_t along with any associated resources. 1210 * 1211 * This will in turn destroy any notmuch_threads_t and 1212 * notmuch_messages_t objects generated by this query, (and in 1213 * turn any notmuch_thread_t and notmuch_message_t objects generated 1214 * from those results, etc.), if such objects haven't already been 1215 * destroyed. 1216 */ 1217 void 1218 notmuch_query_destroy (notmuch_query_t *query); 1219 1220 /** 1221 * Is the given 'threads' iterator pointing at a valid thread. 1222 * 1223 * When this function returns TRUE, notmuch_threads_get will return a 1224 * valid object. Whereas when this function returns FALSE, 1225 * notmuch_threads_get will return NULL. 1226 * 1227 * If passed a NULL pointer, this function returns FALSE 1228 * 1229 * See the documentation of notmuch_query_search_threads for example 1230 * code showing how to iterate over a notmuch_threads_t object. 1231 */ 1232 notmuch_bool_t 1233 notmuch_threads_valid (notmuch_threads_t *threads); 1234 1235 /** 1236 * Get the current thread from 'threads' as a notmuch_thread_t. 1237 * 1238 * Note: The returned thread belongs to 'threads' and has a lifetime 1239 * identical to it (and the query to which it belongs). 1240 * 1241 * See the documentation of notmuch_query_search_threads for example 1242 * code showing how to iterate over a notmuch_threads_t object. 1243 * 1244 * If an out-of-memory situation occurs, this function will return 1245 * NULL. 1246 */ 1247 notmuch_thread_t * 1248 notmuch_threads_get (notmuch_threads_t *threads); 1249 1250 /** 1251 * Move the 'threads' iterator to the next thread. 1252 * 1253 * If 'threads' is already pointing at the last thread then the 1254 * iterator will be moved to a point just beyond that last thread, 1255 * (where notmuch_threads_valid will return FALSE and 1256 * notmuch_threads_get will return NULL). 1257 * 1258 * See the documentation of notmuch_query_search_threads for example 1259 * code showing how to iterate over a notmuch_threads_t object. 1260 */ 1261 void 1262 notmuch_threads_move_to_next (notmuch_threads_t *threads); 1263 1264 /** 1265 * Destroy a notmuch_threads_t object. 1266 * 1267 * It's not strictly necessary to call this function. All memory from 1268 * the notmuch_threads_t object will be reclaimed when the 1269 * containing query object is destroyed. 1270 */ 1271 void 1272 notmuch_threads_destroy (notmuch_threads_t *threads); 1273 1274 /** 1275 * Return the number of messages matching a search. 1276 * 1277 * This function performs a search and returns the number of matching 1278 * messages. 1279 * 1280 * @returns 1281 * 1282 * NOTMUCH_STATUS_SUCCESS: query completed successfully. 1283 * 1284 * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The 1285 * value of *count is not defined. 1286 * 1287 * @since libnotmuch 5 (notmuch 0.25) 1288 */ 1289 notmuch_status_t 1290 notmuch_query_count_messages (notmuch_query_t *query, unsigned int *count); 1291 1292 /** 1293 * Deprecated alias for notmuch_query_count_messages 1294 * 1295 * 1296 * @deprecated Deprecated since libnotmuch 5.0 (notmuch 0.25). Please 1297 * use notmuch_query_count_messages instead. 1298 */ 1299 NOTMUCH_DEPRECATED (5, 0) 1300 notmuch_status_t 1301 notmuch_query_count_messages_st (notmuch_query_t *query, unsigned int *count); 1302 1303 /** 1304 * Return the number of threads matching a search. 1305 * 1306 * This function performs a search and returns the number of unique thread IDs 1307 * in the matching messages. This is the same as number of threads matching a 1308 * search. 1309 * 1310 * Note that this is a significantly heavier operation than 1311 * notmuch_query_count_messages{_st}(). 1312 * 1313 * @returns 1314 * 1315 * NOTMUCH_STATUS_OUT_OF_MEMORY: Memory allocation failed. The value 1316 * of *count is not defined 1317 * 1318 * NOTMUCH_STATUS_SUCCESS: query completed successfully. 1319 * 1320 * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The 1321 * value of *count is not defined. 1322 * 1323 * @since libnotmuch 5 (notmuch 0.25) 1324 */ 1325 notmuch_status_t 1326 notmuch_query_count_threads (notmuch_query_t *query, unsigned *count); 1327 1328 /** 1329 * Deprecated alias for notmuch_query_count_threads 1330 * 1331 * @deprecated Deprecated as of libnotmuch 5.0 (notmuch 0.25). Please 1332 * use notmuch_query_count_threads_st instead. 1333 */ 1334 NOTMUCH_DEPRECATED (5, 0) 1335 notmuch_status_t 1336 notmuch_query_count_threads_st (notmuch_query_t *query, unsigned *count); 1337 1338 /** 1339 * Get the thread ID of 'thread'. 1340 * 1341 * The returned string belongs to 'thread' and as such, should not be 1342 * modified by the caller and will only be valid for as long as the 1343 * thread is valid, (which is until notmuch_thread_destroy or until 1344 * the query from which it derived is destroyed). 1345 */ 1346 const char * 1347 notmuch_thread_get_thread_id (notmuch_thread_t *thread); 1348 1349 /** 1350 * Get the total number of messages in 'thread'. 1351 * 1352 * This count consists of all messages in the database belonging to 1353 * this thread. Contrast with notmuch_thread_get_matched_messages() . 1354 */ 1355 int 1356 notmuch_thread_get_total_messages (notmuch_thread_t *thread); 1357 1358 /** 1359 * Get the total number of files in 'thread'. 1360 * 1361 * This sums notmuch_message_count_files over all messages in the 1362 * thread 1363 * @returns Non-negative integer 1364 * @since libnotmuch 5.0 (notmuch 0.25) 1365 */ 1366 1367 int 1368 notmuch_thread_get_total_files (notmuch_thread_t *thread); 1369 1370 /** 1371 * Get a notmuch_messages_t iterator for the top-level messages in 1372 * 'thread' in oldest-first order. 1373 * 1374 * This iterator will not necessarily iterate over all of the messages 1375 * in the thread. It will only iterate over the messages in the thread 1376 * which are not replies to other messages in the thread. 1377 * 1378 * The returned list will be destroyed when the thread is destroyed. 1379 */ 1380 notmuch_messages_t * 1381 notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread); 1382 1383 /** 1384 * Get a notmuch_thread_t iterator for all messages in 'thread' in 1385 * oldest-first order. 1386 * 1387 * The returned list will be destroyed when the thread is destroyed. 1388 */ 1389 notmuch_messages_t * 1390 notmuch_thread_get_messages (notmuch_thread_t *thread); 1391 1392 /** 1393 * Get the number of messages in 'thread' that matched the search. 1394 * 1395 * This count includes only the messages in this thread that were 1396 * matched by the search from which the thread was created and were 1397 * not excluded by any exclude tags passed in with the query (see 1398 * notmuch_query_add_tag_exclude). Contrast with 1399 * notmuch_thread_get_total_messages() . 1400 */ 1401 int 1402 notmuch_thread_get_matched_messages (notmuch_thread_t *thread); 1403 1404 /** 1405 * Get the authors of 'thread' as a UTF-8 string. 1406 * 1407 * The returned string is a comma-separated list of the names of the 1408 * authors of mail messages in the query results that belong to this 1409 * thread. 1410 * 1411 * The string contains authors of messages matching the query first, then 1412 * non-matched authors (with the two groups separated by '|'). Within 1413 * each group, authors are ordered by date. 1414 * 1415 * The returned string belongs to 'thread' and as such, should not be 1416 * modified by the caller and will only be valid for as long as the 1417 * thread is valid, (which is until notmuch_thread_destroy or until 1418 * the query from which it derived is destroyed). 1419 */ 1420 const char * 1421 notmuch_thread_get_authors (notmuch_thread_t *thread); 1422 1423 /** 1424 * Get the subject of 'thread' as a UTF-8 string. 1425 * 1426 * The subject is taken from the first message (according to the query 1427 * order---see notmuch_query_set_sort) in the query results that 1428 * belongs to this thread. 1429 * 1430 * The returned string belongs to 'thread' and as such, should not be 1431 * modified by the caller and will only be valid for as long as the 1432 * thread is valid, (which is until notmuch_thread_destroy or until 1433 * the query from which it derived is destroyed). 1434 */ 1435 const char * 1436 notmuch_thread_get_subject (notmuch_thread_t *thread); 1437 1438 /** 1439 * Get the date of the oldest message in 'thread' as a time_t value. 1440 */ 1441 time_t 1442 notmuch_thread_get_oldest_date (notmuch_thread_t *thread); 1443 1444 /** 1445 * Get the date of the newest message in 'thread' as a time_t value. 1446 */ 1447 time_t 1448 notmuch_thread_get_newest_date (notmuch_thread_t *thread); 1449 1450 /** 1451 * Get the tags for 'thread', returning a notmuch_tags_t object which 1452 * can be used to iterate over all tags. 1453 * 1454 * Note: In the Notmuch database, tags are stored on individual 1455 * messages, not on threads. So the tags returned here will be all 1456 * tags of the messages which matched the search and which belong to 1457 * this thread. 1458 * 1459 * The tags object is owned by the thread and as such, will only be 1460 * valid for as long as the thread is valid, (for example, until 1461 * notmuch_thread_destroy or until the query from which it derived is 1462 * destroyed). 1463 * 1464 * Typical usage might be: 1465 * 1466 * notmuch_thread_t *thread; 1467 * notmuch_tags_t *tags; 1468 * const char *tag; 1469 * 1470 * thread = notmuch_threads_get (threads); 1471 * 1472 * for (tags = notmuch_thread_get_tags (thread); 1473 * notmuch_tags_valid (tags); 1474 * notmuch_tags_move_to_next (tags)) 1475 * { 1476 * tag = notmuch_tags_get (tags); 1477 * .... 1478 * } 1479 * 1480 * notmuch_thread_destroy (thread); 1481 * 1482 * Note that there's no explicit destructor needed for the 1483 * notmuch_tags_t object. (For consistency, we do provide a 1484 * notmuch_tags_destroy function, but there's no good reason to call 1485 * it if the message is about to be destroyed). 1486 */ 1487 notmuch_tags_t * 1488 notmuch_thread_get_tags (notmuch_thread_t *thread); 1489 1490 /** 1491 * Destroy a notmuch_thread_t object. 1492 */ 1493 void 1494 notmuch_thread_destroy (notmuch_thread_t *thread); 1495 1496 /** 1497 * Is the given 'messages' iterator pointing at a valid message. 1498 * 1499 * When this function returns TRUE, notmuch_messages_get will return a 1500 * valid object. Whereas when this function returns FALSE, 1501 * notmuch_messages_get will return NULL. 1502 * 1503 * See the documentation of notmuch_query_search_messages for example 1504 * code showing how to iterate over a notmuch_messages_t object. 1505 */ 1506 notmuch_bool_t 1507 notmuch_messages_valid (notmuch_messages_t *messages); 1508 1509 /** 1510 * Get the current message from 'messages' as a notmuch_message_t. 1511 * 1512 * Note: The returned message belongs to 'messages' and has a lifetime 1513 * identical to it (and the query to which it belongs). 1514 * 1515 * See the documentation of notmuch_query_search_messages for example 1516 * code showing how to iterate over a notmuch_messages_t object. 1517 * 1518 * If an out-of-memory situation occurs, this function will return 1519 * NULL. 1520 */ 1521 notmuch_message_t * 1522 notmuch_messages_get (notmuch_messages_t *messages); 1523 1524 /** 1525 * Move the 'messages' iterator to the next message. 1526 * 1527 * If 'messages' is already pointing at the last message then the 1528 * iterator will be moved to a point just beyond that last message, 1529 * (where notmuch_messages_valid will return FALSE and 1530 * notmuch_messages_get will return NULL). 1531 * 1532 * See the documentation of notmuch_query_search_messages for example 1533 * code showing how to iterate over a notmuch_messages_t object. 1534 */ 1535 void 1536 notmuch_messages_move_to_next (notmuch_messages_t *messages); 1537 1538 /** 1539 * Destroy a notmuch_messages_t object. 1540 * 1541 * It's not strictly necessary to call this function. All memory from 1542 * the notmuch_messages_t object will be reclaimed when the containing 1543 * query object is destroyed. 1544 */ 1545 void 1546 notmuch_messages_destroy (notmuch_messages_t *messages); 1547 1548 /** 1549 * Return a list of tags from all messages. 1550 * 1551 * The resulting list is guaranteed not to contain duplicated tags. 1552 * 1553 * WARNING: You can no longer iterate over messages after calling this 1554 * function, because the iterator will point at the end of the list. 1555 * We do not have a function to reset the iterator yet and the only 1556 * way how you can iterate over the list again is to recreate the 1557 * message list. 1558 * 1559 * The function returns NULL on error. 1560 */ 1561 notmuch_tags_t * 1562 notmuch_messages_collect_tags (notmuch_messages_t *messages); 1563 1564 /** 1565 * Get the database associated with this message. 1566 * 1567 * @since libnotmuch 5.2 (notmuch 0.27) 1568 */ 1569 notmuch_database_t * 1570 notmuch_message_get_database (const notmuch_message_t *message); 1571 1572 /** 1573 * Get the message ID of 'message'. 1574 * 1575 * The returned string belongs to 'message' and as such, should not be 1576 * modified by the caller and will only be valid for as long as the 1577 * message is valid, (which is until the query from which it derived 1578 * is destroyed). 1579 * 1580 * This function will return NULL if triggers an unhandled Xapian 1581 * exception. 1582 */ 1583 const char * 1584 notmuch_message_get_message_id (notmuch_message_t *message); 1585 1586 /** 1587 * Get the thread ID of 'message'. 1588 * 1589 * The returned string belongs to 'message' and as such, should not be 1590 * modified by the caller and will only be valid for as long as the 1591 * message is valid, (for example, until the user calls 1592 * notmuch_message_destroy on 'message' or until a query from which it 1593 * derived is destroyed). 1594 * 1595 * This function will return NULL if triggers an unhandled Xapian 1596 * exception. 1597 */ 1598 const char * 1599 notmuch_message_get_thread_id (notmuch_message_t *message); 1600 1601 /** 1602 * Get a notmuch_messages_t iterator for all of the replies to 1603 * 'message'. 1604 * 1605 * Note: This call only makes sense if 'message' was ultimately 1606 * obtained from a notmuch_thread_t object, (such as by coming 1607 * directly from the result of calling notmuch_thread_get_ 1608 * toplevel_messages or by any number of subsequent 1609 * calls to notmuch_message_get_replies). 1610 * 1611 * If 'message' was obtained through some non-thread means, (such as 1612 * by a call to notmuch_query_search_messages), then this function 1613 * will return NULL. 1614 * 1615 * If there are no replies to 'message', this function will return 1616 * NULL. (Note that notmuch_messages_valid will accept that NULL 1617 * value as legitimate, and simply return FALSE for it.) 1618 * 1619 * This function also returns NULL if it triggers a Xapian exception. 1620 * 1621 * The returned list will be destroyed when the thread is 1622 * destroyed. 1623 */ 1624 notmuch_messages_t * 1625 notmuch_message_get_replies (notmuch_message_t *message); 1626 1627 /** 1628 * Get the total number of files associated with a message. 1629 * @returns Non-negative integer for file count. 1630 * @returns Negative integer for error. 1631 * @since libnotmuch 5.0 (notmuch 0.25) 1632 */ 1633 int 1634 notmuch_message_count_files (notmuch_message_t *message); 1635 1636 /** 1637 * Get a filename for the email corresponding to 'message'. 1638 * 1639 * The returned filename is an absolute filename, (the initial 1640 * component will match notmuch_database_get_path() ). 1641 * 1642 * The returned string belongs to the message so should not be 1643 * modified or freed by the caller (nor should it be referenced after 1644 * the message is destroyed). 1645 * 1646 * Note: If this message corresponds to multiple files in the mail 1647 * store, (that is, multiple files contain identical message IDs), 1648 * this function will arbitrarily return a single one of those 1649 * filenames. See notmuch_message_get_filenames for returning the 1650 * complete list of filenames. 1651 * 1652 * This function returns NULL if it triggers a Xapian exception. 1653 */ 1654 const char * 1655 notmuch_message_get_filename (notmuch_message_t *message); 1656 1657 /** 1658 * Get all filenames for the email corresponding to 'message'. 1659 * 1660 * Returns a notmuch_filenames_t iterator listing all the filenames 1661 * associated with 'message'. These files may not have identical 1662 * content, but each will have the identical Message-ID. 1663 * 1664 * Each filename in the iterator is an absolute filename, (the initial 1665 * component will match notmuch_database_get_path() ). 1666 * 1667 * This function returns NULL if it triggers a Xapian exception. 1668 */ 1669 notmuch_filenames_t * 1670 notmuch_message_get_filenames (notmuch_message_t *message); 1671 1672 /** 1673 * Re-index the e-mail corresponding to 'message' using the supplied index options 1674 * 1675 * Returns the status of the re-index operation. (see the return 1676 * codes documented in notmuch_database_index_file) 1677 * 1678 * After reindexing, the user should discard the message object passed 1679 * in here by calling notmuch_message_destroy, since it refers to the 1680 * original message, not to the reindexed message. 1681 */ 1682 notmuch_status_t 1683 notmuch_message_reindex (notmuch_message_t *message, 1684 notmuch_indexopts_t *indexopts); 1685 1686 /** 1687 * Message flags. 1688 */ 1689 typedef enum _notmuch_message_flag { 1690 NOTMUCH_MESSAGE_FLAG_MATCH, 1691 NOTMUCH_MESSAGE_FLAG_EXCLUDED, 1692 1693 /* This message is a "ghost message", meaning it has no filenames 1694 * or content, but we know it exists because it was referenced by 1695 * some other message. A ghost message has only a message ID and 1696 * thread ID. 1697 */ 1698 NOTMUCH_MESSAGE_FLAG_GHOST, 1699 } notmuch_message_flag_t; 1700 1701 /** 1702 * Get a value of a flag for the email corresponding to 'message'. 1703 * 1704 * returns FALSE in case of errors. 1705 * 1706 * @deprecated Deprecated as of libnotmuch 5.3 (notmuch 0.31). Please 1707 * use notmuch_message_get_flag_st instead. 1708 */ 1709 NOTMUCH_DEPRECATED (5, 3) 1710 notmuch_bool_t 1711 notmuch_message_get_flag (notmuch_message_t *message, 1712 notmuch_message_flag_t flag); 1713 1714 /** 1715 * Get a value of a flag for the email corresponding to 'message'. 1716 * 1717 * @param message a message object 1718 * @param flag flag to check 1719 * @param is_set pointer to boolean to store flag value. 1720 * 1721 * @retval #NOTMUCH_STATUS_SUCCESS 1722 * @retval #NOTMUCH_STATUS_NULL_POINTER is_set is NULL 1723 * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION Accessing the database 1724 * triggered an exception. 1725 * 1726 * @since libnotmuch 5.3 (notmuch 0.31) 1727 */ 1728 notmuch_status_t 1729 notmuch_message_get_flag_st (notmuch_message_t *message, 1730 notmuch_message_flag_t flag, 1731 notmuch_bool_t *is_set); 1732 1733 /** 1734 * Set a value of a flag for the email corresponding to 'message'. 1735 */ 1736 void 1737 notmuch_message_set_flag (notmuch_message_t *message, 1738 notmuch_message_flag_t flag, notmuch_bool_t value); 1739 1740 /** 1741 * Get the date of 'message' as a time_t value. 1742 * 1743 * For the original textual representation of the Date header from the 1744 * message call notmuch_message_get_header() with a header value of 1745 * "date". 1746 * 1747 * Returns 0 in case of error. 1748 */ 1749 time_t 1750 notmuch_message_get_date (notmuch_message_t *message); 1751 1752 /** 1753 * Get the value of the specified header from 'message' as a UTF-8 string. 1754 * 1755 * Common headers are stored in the database when the message is 1756 * indexed and will be returned from the database. Other headers will 1757 * be read from the actual message file. 1758 * 1759 * The header name is case insensitive. 1760 * 1761 * The returned string belongs to the message so should not be 1762 * modified or freed by the caller (nor should it be referenced after 1763 * the message is destroyed). 1764 * 1765 * Returns an empty string ("") if the message does not contain a 1766 * header line matching 'header'. Returns NULL if any error occurs. 1767 */ 1768 const char * 1769 notmuch_message_get_header (notmuch_message_t *message, const char *header); 1770 1771 /** 1772 * Get the tags for 'message', returning a notmuch_tags_t object which 1773 * can be used to iterate over all tags. 1774 * 1775 * The tags object is owned by the message and as such, will only be 1776 * valid for as long as the message is valid, (which is until the 1777 * query from which it derived is destroyed). 1778 * 1779 * Typical usage might be: 1780 * 1781 * notmuch_message_t *message; 1782 * notmuch_tags_t *tags; 1783 * const char *tag; 1784 * 1785 * message = notmuch_database_find_message (database, message_id); 1786 * 1787 * for (tags = notmuch_message_get_tags (message); 1788 * notmuch_tags_valid (tags); 1789 * notmuch_tags_move_to_next (tags)) 1790 * { 1791 * tag = notmuch_tags_get (tags); 1792 * .... 1793 * } 1794 * 1795 * notmuch_message_destroy (message); 1796 * 1797 * Note that there's no explicit destructor needed for the 1798 * notmuch_tags_t object. (For consistency, we do provide a 1799 * notmuch_tags_destroy function, but there's no good reason to call 1800 * it if the message is about to be destroyed). 1801 */ 1802 notmuch_tags_t * 1803 notmuch_message_get_tags (notmuch_message_t *message); 1804 1805 /** 1806 * The longest possible tag value. 1807 */ 1808 #define NOTMUCH_TAG_MAX 200 1809 1810 /** 1811 * Add a tag to the given message. 1812 * 1813 * Return value: 1814 * 1815 * NOTMUCH_STATUS_SUCCESS: Tag successfully added to message 1816 * 1817 * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL 1818 * 1819 * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long 1820 * (exceeds NOTMUCH_TAG_MAX) 1821 * 1822 * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only 1823 * mode so message cannot be modified. 1824 */ 1825 notmuch_status_t 1826 notmuch_message_add_tag (notmuch_message_t *message, const char *tag); 1827 1828 /** 1829 * Remove a tag from the given message. 1830 * 1831 * Return value: 1832 * 1833 * NOTMUCH_STATUS_SUCCESS: Tag successfully removed from message 1834 * 1835 * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL 1836 * 1837 * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long 1838 * (exceeds NOTMUCH_TAG_MAX) 1839 * 1840 * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only 1841 * mode so message cannot be modified. 1842 */ 1843 notmuch_status_t 1844 notmuch_message_remove_tag (notmuch_message_t *message, const char *tag); 1845 1846 /** 1847 * Remove all tags from the given message. 1848 * 1849 * See notmuch_message_freeze for an example showing how to safely 1850 * replace tag values. 1851 * 1852 * @retval #NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in 1853 * read-only mode so message cannot be modified. 1854 * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION: an exception was thrown 1855 * accessing the database. 1856 */ 1857 notmuch_status_t 1858 notmuch_message_remove_all_tags (notmuch_message_t *message); 1859 1860 /** 1861 * Add/remove tags according to maildir flags in the message filename(s). 1862 * 1863 * This function examines the filenames of 'message' for maildir 1864 * flags, and adds or removes tags on 'message' as follows when these 1865 * flags are present: 1866 * 1867 * Flag Action if present 1868 * ---- ----------------- 1869 * 'D' Adds the "draft" tag to the message 1870 * 'F' Adds the "flagged" tag to the message 1871 * 'P' Adds the "passed" tag to the message 1872 * 'R' Adds the "replied" tag to the message 1873 * 'S' Removes the "unread" tag from the message 1874 * 1875 * For each flag that is not present, the opposite action (add/remove) 1876 * is performed for the corresponding tags. 1877 * 1878 * Flags are identified as trailing components of the filename after a 1879 * sequence of ":2,". 1880 * 1881 * If there are multiple filenames associated with this message, the 1882 * flag is considered present if it appears in one or more 1883 * filenames. (That is, the flags from the multiple filenames are 1884 * combined with the logical OR operator.) 1885 * 1886 * A client can ensure that notmuch database tags remain synchronized 1887 * with maildir flags by calling this function after each call to 1888 * notmuch_database_index_file. See also 1889 * notmuch_message_tags_to_maildir_flags for synchronizing tag changes 1890 * back to maildir flags. 1891 */ 1892 notmuch_status_t 1893 notmuch_message_maildir_flags_to_tags (notmuch_message_t *message); 1894 1895 /** 1896 * return TRUE if any filename of 'message' has maildir flag 'flag', 1897 * FALSE otherwise. 1898 * 1899 * Deprecated wrapper for notmuch_message_has_maildir_flag_st 1900 * 1901 * @returns FALSE in case of error 1902 * @deprecated libnotmuch 5.3 (notmuch 0.31) 1903 */ 1904 NOTMUCH_DEPRECATED (5, 3) 1905 notmuch_bool_t 1906 notmuch_message_has_maildir_flag (notmuch_message_t *message, char flag); 1907 1908 /** 1909 * check message for maildir flag 1910 * 1911 * @param [in,out] message message to check 1912 * @param [in] flag flag to check for 1913 * @param [out] is_set pointer to boolean 1914 * 1915 * @retval #NOTMUCH_STATUS_SUCCESS 1916 * @retval #NOTMUCH_STATUS_NULL_POINTER is_set is NULL 1917 * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION Accessing the database 1918 * triggered an exception. 1919 */ 1920 notmuch_status_t 1921 notmuch_message_has_maildir_flag_st (notmuch_message_t *message, 1922 char flag, 1923 notmuch_bool_t *is_set); 1924 1925 /** 1926 * Rename message filename(s) to encode tags as maildir flags. 1927 * 1928 * Specifically, for each filename corresponding to this message: 1929 * 1930 * If the filename is not in a maildir directory, do nothing. (A 1931 * maildir directory is determined as a directory named "new" or 1932 * "cur".) Similarly, if the filename has invalid maildir info, 1933 * (repeated or outof-ASCII-order flag characters after ":2,"), then 1934 * do nothing. 1935 * 1936 * If the filename is in a maildir directory, rename the file so that 1937 * its filename ends with the sequence ":2," followed by zero or more 1938 * of the following single-character flags (in ASCII order): 1939 * 1940 * * flag 'D' iff the message has the "draft" tag 1941 * * flag 'F' iff the message has the "flagged" tag 1942 * * flag 'P' iff the message has the "passed" tag 1943 * * flag 'R' iff the message has the "replied" tag 1944 * * flag 'S' iff the message does not have the "unread" tag 1945 * 1946 * Any existing flags unmentioned in the list above will be preserved 1947 * in the renaming. 1948 * 1949 * Also, if this filename is in a directory named "new", rename it to 1950 * be within the neighboring directory named "cur". 1951 * 1952 * A client can ensure that maildir filename flags remain synchronized 1953 * with notmuch database tags by calling this function after changing 1954 * tags, (after calls to notmuch_message_add_tag, 1955 * notmuch_message_remove_tag, or notmuch_message_freeze/ 1956 * notmuch_message_thaw). See also notmuch_message_maildir_flags_to_tags 1957 * for synchronizing maildir flag changes back to tags. 1958 */ 1959 notmuch_status_t 1960 notmuch_message_tags_to_maildir_flags (notmuch_message_t *message); 1961 1962 /** 1963 * Freeze the current state of 'message' within the database. 1964 * 1965 * This means that changes to the message state, (via 1966 * notmuch_message_add_tag, notmuch_message_remove_tag, and 1967 * notmuch_message_remove_all_tags), will not be committed to the 1968 * database until the message is thawed with notmuch_message_thaw. 1969 * 1970 * Multiple calls to freeze/thaw are valid and these calls will 1971 * "stack". That is there must be as many calls to thaw as to freeze 1972 * before a message is actually thawed. 1973 * 1974 * The ability to do freeze/thaw allows for safe transactions to 1975 * change tag values. For example, explicitly setting a message to 1976 * have a given set of tags might look like this: 1977 * 1978 * notmuch_message_freeze (message); 1979 * 1980 * notmuch_message_remove_all_tags (message); 1981 * 1982 * for (i = 0; i < NUM_TAGS; i++) 1983 * notmuch_message_add_tag (message, tags[i]); 1984 * 1985 * notmuch_message_thaw (message); 1986 * 1987 * With freeze/thaw used like this, the message in the database is 1988 * guaranteed to have either the full set of original tag values, or 1989 * the full set of new tag values, but nothing in between. 1990 * 1991 * Imagine the example above without freeze/thaw and the operation 1992 * somehow getting interrupted. This could result in the message being 1993 * left with no tags if the interruption happened after 1994 * notmuch_message_remove_all_tags but before notmuch_message_add_tag. 1995 * 1996 * Return value: 1997 * 1998 * NOTMUCH_STATUS_SUCCESS: Message successfully frozen. 1999 * 2000 * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only 2001 * mode so message cannot be modified. 2002 */ 2003 notmuch_status_t 2004 notmuch_message_freeze (notmuch_message_t *message); 2005 2006 /** 2007 * Thaw the current 'message', synchronizing any changes that may have 2008 * occurred while 'message' was frozen into the notmuch database. 2009 * 2010 * See notmuch_message_freeze for an example of how to use this 2011 * function to safely provide tag changes. 2012 * 2013 * Multiple calls to freeze/thaw are valid and these calls with 2014 * "stack". That is there must be as many calls to thaw as to freeze 2015 * before a message is actually thawed. 2016 * 2017 * Return value: 2018 * 2019 * NOTMUCH_STATUS_SUCCESS: Message successfully thawed, (or at least 2020 * its frozen count has successfully been reduced by 1). 2021 * 2022 * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: An attempt was made to thaw 2023 * an unfrozen message. That is, there have been an unbalanced 2024 * number of calls to notmuch_message_freeze and 2025 * notmuch_message_thaw. 2026 */ 2027 notmuch_status_t 2028 notmuch_message_thaw (notmuch_message_t *message); 2029 2030 /** 2031 * Destroy a notmuch_message_t object. 2032 * 2033 * It can be useful to call this function in the case of a single 2034 * query object with many messages in the result, (such as iterating 2035 * over the entire database). Otherwise, it's fine to never call this 2036 * function and there will still be no memory leaks. (The memory from 2037 * the messages get reclaimed when the containing query is destroyed.) 2038 */ 2039 void 2040 notmuch_message_destroy (notmuch_message_t *message); 2041 2042 /** 2043 * @name Message Properties 2044 * 2045 * This interface provides the ability to attach arbitrary (key,value) 2046 * string pairs to a message, to remove such pairs, and to iterate 2047 * over them. The caller should take some care as to what keys they 2048 * add or delete values for, as other subsystems or extensions may 2049 * depend on these properties. 2050 * 2051 * Please see notmuch-properties(7) for more details about specific 2052 * properties and conventions around their use. 2053 * 2054 */ 2055 /**@{*/ 2056 /** 2057 * Retrieve the value for a single property key 2058 * 2059 * *value* is set to a string owned by the message or NULL if there is 2060 * no such key. In the case of multiple values for the given key, the 2061 * first one is retrieved. 2062 * 2063 * @returns 2064 * - NOTMUCH_STATUS_NULL_POINTER: *value* may not be NULL. 2065 * - NOTMUCH_STATUS_SUCCESS: No error occurred. 2066 * @since libnotmuch 4.4 (notmuch 0.23) 2067 */ 2068 notmuch_status_t 2069 notmuch_message_get_property (notmuch_message_t *message, const char *key, const char **value); 2070 2071 /** 2072 * Add a (key,value) pair to a message 2073 * 2074 * @returns 2075 * - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character. 2076 * - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL. 2077 * - NOTMUCH_STATUS_SUCCESS: No error occurred. 2078 * @since libnotmuch 4.4 (notmuch 0.23) 2079 */ 2080 notmuch_status_t 2081 notmuch_message_add_property (notmuch_message_t *message, const char *key, const char *value); 2082 2083 /** 2084 * Remove a (key,value) pair from a message. 2085 * 2086 * It is not an error to remove a non-existent (key,value) pair 2087 * 2088 * @returns 2089 * - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character. 2090 * - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL. 2091 * - NOTMUCH_STATUS_SUCCESS: No error occurred. 2092 * @since libnotmuch 4.4 (notmuch 0.23) 2093 */ 2094 notmuch_status_t 2095 notmuch_message_remove_property (notmuch_message_t *message, const char *key, const char *value); 2096 2097 /** 2098 * Remove all (key,value) pairs from the given message. 2099 * 2100 * @param[in,out] message message to operate on. 2101 * @param[in] key key to delete properties for. If NULL, delete 2102 * properties for all keys 2103 * @returns 2104 * - NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in 2105 * read-only mode so message cannot be modified. 2106 * - NOTMUCH_STATUS_SUCCESS: No error occurred. 2107 * 2108 * @since libnotmuch 4.4 (notmuch 0.23) 2109 */ 2110 notmuch_status_t 2111 notmuch_message_remove_all_properties (notmuch_message_t *message, const char *key); 2112 2113 /** 2114 * Remove all (prefix*,value) pairs from the given message 2115 * 2116 * @param[in,out] message message to operate on. 2117 * @param[in] prefix delete properties with keys that start with prefix. 2118 * If NULL, delete all properties 2119 * @returns 2120 * - NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in 2121 * read-only mode so message cannot be modified. 2122 * - NOTMUCH_STATUS_SUCCESS: No error occurred. 2123 * 2124 * @since libnotmuch 5.1 (notmuch 0.26) 2125 */ 2126 notmuch_status_t 2127 notmuch_message_remove_all_properties_with_prefix (notmuch_message_t *message, const char *prefix); 2128 2129 /** 2130 * Opaque message property iterator 2131 */ 2132 typedef struct _notmuch_string_map_iterator notmuch_message_properties_t; 2133 2134 /** 2135 * Get the properties for *message*, returning a 2136 * notmuch_message_properties_t object which can be used to iterate 2137 * over all properties. 2138 * 2139 * The notmuch_message_properties_t object is owned by the message and 2140 * as such, will only be valid for as long as the message is valid, 2141 * (which is until the query from which it derived is destroyed). 2142 * 2143 * @param[in] message The message to examine 2144 * @param[in] key key or key prefix 2145 * @param[in] exact if TRUE, require exact match with key. Otherwise 2146 * treat as prefix. 2147 * 2148 * Typical usage might be: 2149 * 2150 * notmuch_message_properties_t *list; 2151 * 2152 * for (list = notmuch_message_get_properties (message, "testkey1", TRUE); 2153 * notmuch_message_properties_valid (list); notmuch_message_properties_move_to_next (list)) { 2154 * printf("%s\n", notmuch_message_properties_value(list)); 2155 * } 2156 * 2157 * notmuch_message_properties_destroy (list); 2158 * 2159 * Note that there's no explicit destructor needed for the 2160 * notmuch_message_properties_t object. (For consistency, we do 2161 * provide a notmuch_message_properities_destroy function, but there's 2162 * no good reason to call it if the message is about to be destroyed). 2163 * 2164 * @since libnotmuch 4.4 (notmuch 0.23) 2165 */ 2166 notmuch_message_properties_t * 2167 notmuch_message_get_properties (notmuch_message_t *message, const char *key, notmuch_bool_t exact); 2168 2169 /** 2170 * Return the number of properties named "key" belonging to the specific message. 2171 * 2172 * @param[in] message The message to examine 2173 * @param[in] key key to count 2174 * @param[out] count The number of matching properties associated with this message. 2175 * 2176 * @returns 2177 * 2178 * NOTMUCH_STATUS_SUCCESS: successful count, possibly some other error. 2179 * 2180 * @since libnotmuch 5.2 (notmuch 0.27) 2181 */ 2182 notmuch_status_t 2183 notmuch_message_count_properties (notmuch_message_t *message, const char *key, unsigned int *count); 2184 2185 /** 2186 * Is the given *properties* iterator pointing at a valid (key,value) 2187 * pair. 2188 * 2189 * When this function returns TRUE, 2190 * notmuch_message_properties_{key,value} will return a valid string, 2191 * and notmuch_message_properties_move_to_next will do what it 2192 * says. Whereas when this function returns FALSE, calling any of 2193 * these functions results in undefined behaviour. 2194 * 2195 * See the documentation of notmuch_message_get_properties for example 2196 * code showing how to iterate over a notmuch_message_properties_t 2197 * object. 2198 * 2199 * @since libnotmuch 4.4 (notmuch 0.23) 2200 */ 2201 notmuch_bool_t 2202 notmuch_message_properties_valid (notmuch_message_properties_t *properties); 2203 2204 /** 2205 * Move the *properties* iterator to the next (key,value) pair 2206 * 2207 * If *properties* is already pointing at the last pair then the iterator 2208 * will be moved to a point just beyond that last pair, (where 2209 * notmuch_message_properties_valid will return FALSE). 2210 * 2211 * See the documentation of notmuch_message_get_properties for example 2212 * code showing how to iterate over a notmuch_message_properties_t object. 2213 * 2214 * @since libnotmuch 4.4 (notmuch 0.23) 2215 */ 2216 void 2217 notmuch_message_properties_move_to_next (notmuch_message_properties_t *properties); 2218 2219 /** 2220 * Return the key from the current (key,value) pair. 2221 * 2222 * this could be useful if iterating for a prefix 2223 * 2224 * @since libnotmuch 4.4 (notmuch 0.23) 2225 */ 2226 const char * 2227 notmuch_message_properties_key (notmuch_message_properties_t *properties); 2228 2229 /** 2230 * Return the value from the current (key,value) pair. 2231 * 2232 * This could be useful if iterating for a prefix. 2233 * 2234 * @since libnotmuch 4.4 (notmuch 0.23) 2235 */ 2236 const char * 2237 notmuch_message_properties_value (notmuch_message_properties_t *properties); 2238 2239 2240 /** 2241 * Destroy a notmuch_message_properties_t object. 2242 * 2243 * It's not strictly necessary to call this function. All memory from 2244 * the notmuch_message_properties_t object will be reclaimed when the 2245 * containing message object is destroyed. 2246 * 2247 * @since libnotmuch 4.4 (notmuch 0.23) 2248 */ 2249 void 2250 notmuch_message_properties_destroy (notmuch_message_properties_t *properties); 2251 2252 /**@}*/ 2253 2254 /** 2255 * Is the given 'tags' iterator pointing at a valid tag. 2256 * 2257 * When this function returns TRUE, notmuch_tags_get will return a 2258 * valid string. Whereas when this function returns FALSE, 2259 * notmuch_tags_get will return NULL. 2260 * 2261 * See the documentation of notmuch_message_get_tags for example code 2262 * showing how to iterate over a notmuch_tags_t object. 2263 */ 2264 notmuch_bool_t 2265 notmuch_tags_valid (notmuch_tags_t *tags); 2266 2267 /** 2268 * Get the current tag from 'tags' as a string. 2269 * 2270 * Note: The returned string belongs to 'tags' and has a lifetime 2271 * identical to it (and the query to which it ultimately belongs). 2272 * 2273 * See the documentation of notmuch_message_get_tags for example code 2274 * showing how to iterate over a notmuch_tags_t object. 2275 */ 2276 const char * 2277 notmuch_tags_get (notmuch_tags_t *tags); 2278 2279 /** 2280 * Move the 'tags' iterator to the next tag. 2281 * 2282 * If 'tags' is already pointing at the last tag then the iterator 2283 * will be moved to a point just beyond that last tag, (where 2284 * notmuch_tags_valid will return FALSE and notmuch_tags_get will 2285 * return NULL). 2286 * 2287 * See the documentation of notmuch_message_get_tags for example code 2288 * showing how to iterate over a notmuch_tags_t object. 2289 */ 2290 void 2291 notmuch_tags_move_to_next (notmuch_tags_t *tags); 2292 2293 /** 2294 * Destroy a notmuch_tags_t object. 2295 * 2296 * It's not strictly necessary to call this function. All memory from 2297 * the notmuch_tags_t object will be reclaimed when the containing 2298 * message or query objects are destroyed. 2299 */ 2300 void 2301 notmuch_tags_destroy (notmuch_tags_t *tags); 2302 2303 /** 2304 * Store an mtime within the database for 'directory'. 2305 * 2306 * The 'directory' should be an object retrieved from the database 2307 * with notmuch_database_get_directory for a particular path. 2308 * 2309 * The intention is for the caller to use the mtime to allow efficient 2310 * identification of new messages to be added to the database. The 2311 * recommended usage is as follows: 2312 * 2313 * o Read the mtime of a directory from the filesystem 2314 * 2315 * o Call index_file for all mail files in the directory 2316 * 2317 * o Call notmuch_directory_set_mtime with the mtime read from the 2318 * filesystem. 2319 * 2320 * Then, when wanting to check for updates to the directory in the 2321 * future, the client can call notmuch_directory_get_mtime and know 2322 * that it only needs to add files if the mtime of the directory and 2323 * files are newer than the stored timestamp. 2324 * 2325 * Note: The notmuch_directory_get_mtime function does not allow the 2326 * caller to distinguish a timestamp of 0 from a non-existent 2327 * timestamp. So don't store a timestamp of 0 unless you are 2328 * comfortable with that. 2329 * 2330 * Return value: 2331 * 2332 * NOTMUCH_STATUS_SUCCESS: mtime successfully stored in database. 2333 * 2334 * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception 2335 * occurred, mtime not stored. 2336 * 2337 * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only 2338 * mode so directory mtime cannot be modified. 2339 */ 2340 notmuch_status_t 2341 notmuch_directory_set_mtime (notmuch_directory_t *directory, 2342 time_t mtime); 2343 2344 /** 2345 * Get the mtime of a directory, (as previously stored with 2346 * notmuch_directory_set_mtime). 2347 * 2348 * Returns 0 if no mtime has previously been stored for this 2349 * directory. 2350 */ 2351 time_t 2352 notmuch_directory_get_mtime (notmuch_directory_t *directory); 2353 2354 /** 2355 * Get a notmuch_filenames_t iterator listing all the filenames of 2356 * messages in the database within the given directory. 2357 * 2358 * The returned filenames will be the basename-entries only (not 2359 * complete paths). 2360 * 2361 * Returns NULL if it triggers a Xapian exception 2362 */ 2363 notmuch_filenames_t * 2364 notmuch_directory_get_child_files (notmuch_directory_t *directory); 2365 2366 /** 2367 * Get a notmuch_filenames_t iterator listing all the filenames of 2368 * sub-directories in the database within the given directory. 2369 * 2370 * The returned filenames will be the basename-entries only (not 2371 * complete paths). 2372 * 2373 * Returns NULL if it triggers a Xapian exception 2374 */ 2375 notmuch_filenames_t * 2376 notmuch_directory_get_child_directories (notmuch_directory_t *directory); 2377 2378 /** 2379 * Delete directory document from the database, and destroy the 2380 * notmuch_directory_t object. Assumes any child directories and files 2381 * have been deleted by the caller. 2382 * 2383 * @since libnotmuch 4.3 (notmuch 0.21) 2384 */ 2385 notmuch_status_t 2386 notmuch_directory_delete (notmuch_directory_t *directory); 2387 2388 /** 2389 * Destroy a notmuch_directory_t object. 2390 */ 2391 void 2392 notmuch_directory_destroy (notmuch_directory_t *directory); 2393 2394 /** 2395 * Is the given 'filenames' iterator pointing at a valid filename. 2396 * 2397 * When this function returns TRUE, notmuch_filenames_get will return 2398 * a valid string. Whereas when this function returns FALSE, 2399 * notmuch_filenames_get will return NULL. 2400 * 2401 * It is acceptable to pass NULL for 'filenames', in which case this 2402 * function will always return FALSE. 2403 */ 2404 notmuch_bool_t 2405 notmuch_filenames_valid (notmuch_filenames_t *filenames); 2406 2407 /** 2408 * Get the current filename from 'filenames' as a string. 2409 * 2410 * Note: The returned string belongs to 'filenames' and has a lifetime 2411 * identical to it (and the directory to which it ultimately belongs). 2412 * 2413 * It is acceptable to pass NULL for 'filenames', in which case this 2414 * function will always return NULL. 2415 */ 2416 const char * 2417 notmuch_filenames_get (notmuch_filenames_t *filenames); 2418 2419 /** 2420 * Move the 'filenames' iterator to the next filename. 2421 * 2422 * If 'filenames' is already pointing at the last filename then the 2423 * iterator will be moved to a point just beyond that last filename, 2424 * (where notmuch_filenames_valid will return FALSE and 2425 * notmuch_filenames_get will return NULL). 2426 * 2427 * It is acceptable to pass NULL for 'filenames', in which case this 2428 * function will do nothing. 2429 */ 2430 void 2431 notmuch_filenames_move_to_next (notmuch_filenames_t *filenames); 2432 2433 /** 2434 * Destroy a notmuch_filenames_t object. 2435 * 2436 * It's not strictly necessary to call this function. All memory from 2437 * the notmuch_filenames_t object will be reclaimed when the 2438 * containing directory object is destroyed. 2439 * 2440 * It is acceptable to pass NULL for 'filenames', in which case this 2441 * function will do nothing. 2442 */ 2443 void 2444 notmuch_filenames_destroy (notmuch_filenames_t *filenames); 2445 2446 2447 /** 2448 * set config 'key' to 'value' 2449 * 2450 * @since libnotmuch 4.4 (notmuch 0.23) 2451 * @retval #NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in 2452 * read-only mode so message cannot be modified. 2453 * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION: an exception was thrown 2454 * accessing the database. 2455 * @retval #NOTMUCH_STATUS_SUCCESS 2456 */ 2457 notmuch_status_t 2458 notmuch_database_set_config (notmuch_database_t *db, const char *key, const char *value); 2459 2460 /** 2461 * retrieve config item 'key', assign to 'value' 2462 * 2463 * keys which have not been previously set with n_d_set_config will 2464 * return an empty string. 2465 * 2466 * return value is allocated by malloc and should be freed by the 2467 * caller. 2468 * 2469 * @since libnotmuch 4.4 (notmuch 0.23) 2470 * 2471 */ 2472 notmuch_status_t 2473 notmuch_database_get_config (notmuch_database_t *db, const char *key, char **value); 2474 2475 /** 2476 * Create an iterator for all config items with keys matching a given prefix 2477 * 2478 * @since libnotmuch 4.4 (notmuch 0.23) 2479 */ 2480 notmuch_status_t 2481 notmuch_database_get_config_list (notmuch_database_t *db, const char *prefix, 2482 notmuch_config_list_t **out); 2483 2484 /** 2485 * Is 'config_list' iterator valid (i.e. _key, _value, _move_to_next can be called). 2486 * 2487 * @since libnotmuch 4.4 (notmuch 0.23) 2488 */ 2489 notmuch_bool_t 2490 notmuch_config_list_valid (notmuch_config_list_t *config_list); 2491 2492 /** 2493 * return key for current config pair 2494 * 2495 * return value is owned by the iterator, and will be destroyed by the 2496 * next call to notmuch_config_list_key or notmuch_config_list_destroy. 2497 * 2498 * @since libnotmuch 4.4 (notmuch 0.23) 2499 */ 2500 const char * 2501 notmuch_config_list_key (notmuch_config_list_t *config_list); 2502 2503 /** 2504 * return 'value' for current config pair 2505 * 2506 * return value is owned by the iterator, and will be destroyed by the 2507 * next call to notmuch_config_list_value or notmuch config_list_destroy 2508 * 2509 * @since libnotmuch 4.4 (notmuch 0.23) 2510 * @retval NULL for errors 2511 */ 2512 const char * 2513 notmuch_config_list_value (notmuch_config_list_t *config_list); 2514 2515 2516 /** 2517 * move 'config_list' iterator to the next pair 2518 * 2519 * @since libnotmuch 4.4 (notmuch 0.23) 2520 */ 2521 void 2522 notmuch_config_list_move_to_next (notmuch_config_list_t *config_list); 2523 2524 /** 2525 * free any resources held by 'config_list' 2526 * 2527 * @since libnotmuch 4.4 (notmuch 0.23) 2528 */ 2529 void 2530 notmuch_config_list_destroy (notmuch_config_list_t *config_list); 2531 2532 /** 2533 * Configuration keys known to libnotmuch 2534 */ 2535 typedef enum _notmuch_config_key { 2536 NOTMUCH_CONFIG_FIRST, 2537 NOTMUCH_CONFIG_DATABASE_PATH = NOTMUCH_CONFIG_FIRST, 2538 NOTMUCH_CONFIG_MAIL_ROOT, 2539 NOTMUCH_CONFIG_HOOK_DIR, 2540 NOTMUCH_CONFIG_BACKUP_DIR, 2541 NOTMUCH_CONFIG_EXCLUDE_TAGS, 2542 NOTMUCH_CONFIG_NEW_TAGS, 2543 NOTMUCH_CONFIG_NEW_IGNORE, 2544 NOTMUCH_CONFIG_SYNC_MAILDIR_FLAGS, 2545 NOTMUCH_CONFIG_PRIMARY_EMAIL, 2546 NOTMUCH_CONFIG_OTHER_EMAIL, 2547 NOTMUCH_CONFIG_USER_NAME, 2548 NOTMUCH_CONFIG_AUTOCOMMIT, 2549 NOTMUCH_CONFIG_LAST 2550 } notmuch_config_key_t; 2551 2552 /** 2553 * get a configuration value from an open database. 2554 * 2555 * This value reflects all configuration information given at the time 2556 * the database was opened. 2557 * 2558 * @param[in] notmuch database 2559 * @param[in] key configuration key 2560 * 2561 * @since libnotmuch 5.4 (notmuch 0.32) 2562 * 2563 * @retval NULL if 'key' unknown or if no value is known for 2564 * 'key'. Otherwise returns a string owned by notmuch which should 2565 * not be modified nor freed by the caller. 2566 */ 2567 const char * 2568 notmuch_config_get (notmuch_database_t *notmuch, notmuch_config_key_t key); 2569 2570 /** 2571 * set a configuration value from in an open database. 2572 * 2573 * This value reflects all configuration information given at the time 2574 * the database was opened. 2575 * 2576 * @param[in,out] notmuch database open read/write 2577 * @param[in] key configuration key 2578 * @param[in] val configuration value 2579 * 2580 * @since libnotmuch 5.4 (notmuch 0.32) 2581 * 2582 * @retval returns any return value for notmuch_database_set_config. 2583 */ 2584 notmuch_status_t 2585 notmuch_config_set (notmuch_database_t *notmuch, notmuch_config_key_t key, const char *val); 2586 2587 /** 2588 * Returns an iterator for a ';'-delimited list of configuration values 2589 * 2590 * These values reflect all configuration information given at the 2591 * time the database was opened. 2592 * 2593 * @param[in] notmuch database 2594 * @param[in] key configuration key 2595 * 2596 * @since libnotmuch 5.4 (notmuch 0.32) 2597 * 2598 * @retval NULL in case of error. 2599 */ 2600 notmuch_config_values_t * 2601 notmuch_config_get_values (notmuch_database_t *notmuch, notmuch_config_key_t key); 2602 2603 /** 2604 * Returns an iterator for a ';'-delimited list of configuration values 2605 * 2606 * These values reflect all configuration information given at the 2607 * time the database was opened. 2608 * 2609 * @param[in] notmuch database 2610 * @param[in] key configuration key 2611 * 2612 * @since libnotmuch 5.4 (notmuch 0.32) 2613 * 2614 * @retval NULL in case of error. 2615 */ 2616 notmuch_config_values_t * 2617 notmuch_config_get_values_string (notmuch_database_t *notmuch, const char *key); 2618 2619 /** 2620 * Is the given 'config_values' iterator pointing at a valid element. 2621 * 2622 * @param[in] values iterator 2623 * 2624 * @since libnotmuch 5.4 (notmuch 0.32) 2625 * 2626 * @retval FALSE if passed a NULL pointer, or the iterator is exhausted. 2627 * 2628 */ 2629 notmuch_bool_t 2630 notmuch_config_values_valid (notmuch_config_values_t *values); 2631 2632 /** 2633 * Get the current value from the 'values' iterator 2634 * 2635 * @param[in] values iterator 2636 * 2637 * @since libnotmuch 5.4 (notmuch 0.32) 2638 * 2639 * @retval a string with the same lifetime as the iterator 2640 */ 2641 const char * 2642 notmuch_config_values_get (notmuch_config_values_t *values); 2643 2644 /** 2645 * Move the 'values' iterator to the next element 2646 * 2647 * @param[in,out] values iterator 2648 * 2649 * @since libnotmuch 5.4 (notmuch 0.32) 2650 * 2651 */ 2652 void 2653 notmuch_config_values_move_to_next (notmuch_config_values_t *values); 2654 2655 2656 /** 2657 * reset the 'values' iterator to the first element 2658 * 2659 * @param[in,out] values iterator. A NULL value is ignored. 2660 * 2661 * @since libnotmuch 5.4 (notmuch 0.32) 2662 * 2663 */ 2664 void 2665 notmuch_config_values_start (notmuch_config_values_t *values); 2666 2667 /** 2668 * Destroy a config values iterator, along with any associated 2669 * resources. 2670 * 2671 * @param[in,out] values iterator 2672 * 2673 * @since libnotmuch 5.4 (notmuch 0.32) 2674 */ 2675 void 2676 notmuch_config_values_destroy (notmuch_config_values_t *values); 2677 2678 2679 /** 2680 * Returns an iterator for a (key, value) configuration pairs 2681 * 2682 * @param[in] notmuch database 2683 * @param[in] prefix prefix for keys. Pass "" for all keys. 2684 * 2685 * @since libnotmuch 5.4 (notmuch 0.32) 2686 * 2687 * @retval NULL in case of error. 2688 */ 2689 notmuch_config_pairs_t * 2690 notmuch_config_get_pairs (notmuch_database_t *notmuch, 2691 const char *prefix); 2692 2693 /** 2694 * Is the given 'config_pairs' iterator pointing at a valid element. 2695 * 2696 * @param[in] pairs iterator 2697 * 2698 * @since libnotmuch 5.4 (notmuch 0.32) 2699 * 2700 * @retval FALSE if passed a NULL pointer, or the iterator is exhausted. 2701 * 2702 */ 2703 notmuch_bool_t 2704 notmuch_config_pairs_valid (notmuch_config_pairs_t *pairs); 2705 2706 /** 2707 * Move the 'config_pairs' iterator to the next element 2708 * 2709 * @param[in,out] pairs iterator 2710 * 2711 * @since libnotmuch 5.4 (notmuch 0.32) 2712 * 2713 */ 2714 void 2715 notmuch_config_pairs_move_to_next (notmuch_config_pairs_t *pairs); 2716 2717 /** 2718 * Get the current key from the 'config_pairs' iterator 2719 * 2720 * @param[in] pairs iterator 2721 * 2722 * @since libnotmuch 5.4 (notmuch 0.32) 2723 * 2724 * @retval a string with the same lifetime as the iterator 2725 */ 2726 const char * 2727 notmuch_config_pairs_key (notmuch_config_pairs_t *pairs); 2728 2729 /** 2730 * Get the current value from the 'config_pairs' iterator 2731 * 2732 * @param[in] pairs iterator 2733 * 2734 * @since libnotmuch 5.4 (notmuch 0.32) 2735 * 2736 * @retval a string with the same lifetime as the iterator 2737 */ 2738 const char * 2739 notmuch_config_pairs_value (notmuch_config_pairs_t *pairs); 2740 2741 /** 2742 * Destroy a config_pairs iterator, along with any associated 2743 * resources. 2744 * 2745 * @param[in,out] pairs iterator 2746 * 2747 * @since libnotmuch 5.4 (notmuch 0.32) 2748 */ 2749 void 2750 notmuch_config_pairs_destroy (notmuch_config_pairs_t *pairs); 2751 2752 /** 2753 * get a configuration value from an open database as Boolean 2754 * 2755 * This value reflects all configuration information given at the time 2756 * the database was opened. 2757 * 2758 * @param[in] notmuch database 2759 * @param[in] key configuration key 2760 * @param[out] val configuration value, converted to Boolean 2761 * 2762 * @since libnotmuch 5.4 (notmuch 0.32) 2763 * 2764 * @retval #NOTMUCH_STATUS_ILLEGAL_ARGUMENT if either key is unknown 2765 * or the corresponding value does not convert to Boolean. 2766 */ 2767 notmuch_status_t 2768 notmuch_config_get_bool (notmuch_database_t *notmuch, 2769 notmuch_config_key_t key, 2770 notmuch_bool_t *val); 2771 2772 /** 2773 * return the path of the config file loaded, if any 2774 * 2775 * @retval NULL if no config file was loaded 2776 */ 2777 const char * 2778 notmuch_config_path (notmuch_database_t *notmuch); 2779 2780 /** 2781 * get the current default indexing options for a given database. 2782 * 2783 * This object will survive until the database itself is destroyed, 2784 * but the caller may also release it earlier with 2785 * notmuch_indexopts_destroy. 2786 * 2787 * This object represents a set of options on how a message can be 2788 * added to the index. At the moment it is a featureless stub. 2789 * 2790 * @since libnotmuch 5.1 (notmuch 0.26) 2791 * @retval NULL in case of error 2792 */ 2793 notmuch_indexopts_t * 2794 notmuch_database_get_default_indexopts (notmuch_database_t *db); 2795 2796 /** 2797 * Stating a policy about how to decrypt messages. 2798 * 2799 * See index.decrypt in notmuch-config(1) for more details. 2800 */ 2801 typedef enum { 2802 NOTMUCH_DECRYPT_FALSE, 2803 NOTMUCH_DECRYPT_TRUE, 2804 NOTMUCH_DECRYPT_AUTO, 2805 NOTMUCH_DECRYPT_NOSTASH, 2806 } notmuch_decryption_policy_t; 2807 2808 /** 2809 * Specify whether to decrypt encrypted parts while indexing. 2810 * 2811 * Be aware that the index is likely sufficient to reconstruct the 2812 * cleartext of the message itself, so please ensure that the notmuch 2813 * message index is adequately protected. DO NOT SET THIS FLAG TO TRUE 2814 * without considering the security of your index. 2815 * 2816 * @since libnotmuch 5.1 (notmuch 0.26) 2817 */ 2818 notmuch_status_t 2819 notmuch_indexopts_set_decrypt_policy (notmuch_indexopts_t *indexopts, 2820 notmuch_decryption_policy_t decrypt_policy); 2821 2822 /** 2823 * Return whether to decrypt encrypted parts while indexing. 2824 * see notmuch_indexopts_set_decrypt_policy. 2825 * 2826 * @since libnotmuch 5.1 (notmuch 0.26) 2827 */ 2828 notmuch_decryption_policy_t 2829 notmuch_indexopts_get_decrypt_policy (const notmuch_indexopts_t *indexopts); 2830 2831 /** 2832 * Destroy a notmuch_indexopts_t object. 2833 * 2834 * @since libnotmuch 5.1 (notmuch 0.26) 2835 */ 2836 void 2837 notmuch_indexopts_destroy (notmuch_indexopts_t *options); 2838 2839 2840 /** 2841 * interrogate the library for compile time features 2842 * 2843 * @since libnotmuch 4.4 (notmuch 0.23) 2844 */ 2845 notmuch_bool_t 2846 notmuch_built_with (const char *name); 2847 /**@}*/ 2848 2849 #pragma GCC visibility pop 2850 2851 NOTMUCH_END_DECLS 2852 2853 #endif 2854